城市天气宣传画报生成接口（cweather）技术接入文档-阿里云开发者社区

本文基于阿里云云市场公开商品页的真实字段整理，面向开发者介绍「城市天气宣传画报生成」接口的契约、参数、返回结构、错误排查与多语言接入方式。全文不含任何外部链接地址，代码示例中的调用域名为裸域名写法。

1. 背景与适用场景

在城市文旅宣传、本地生活运营、气象媒体配图等场景中，运营方常需批量、自动化地生产带有当地实时天气、地标与统一视觉风格的城市宣传图。传统方式依赖美术设计与天气数据对接，人力与时间成本较高。城市天气宣传画报生成接口（cweather）通过阿里云 API 网关提供标准 HTTPS 服务：输入城市或景点名称，由服务端完成省市级联消歧、实时天气查询、地标提炼与构图，并按指定绘画风格异步生成画报图片。本文介绍其接口契约与接入要点，帮助开发者快速完成系统集成。

2. 接口概览

功能：输入城市或景点名称，服务端自动完成省市消歧、实时天气融合、地标三层构图，并按指定风格异步生成城市宣传画报。
协议：HTTPS，请求方法 POST，请求体与返回均为 JSON。
调用地址：服务域名为 cweather.market.alicloudapi.com，接口路径为 /weatherPainter/execute。
鉴权方式：支持 APPCODE 简单认证（请求头 Authorization: APPCODE xxxx）与 AppKey & AppSecret 签名认证两种。
调用模式：异步。先「创建任务」获得任务标识与查询入口，再「轮询查询」获取最终结果。

接口调用流程

该接口由阿里云云市场入驻服务商提供，调用凭据在阿里云云市场订购后获取。

3. 请求参数

创建任务接口（POST /weatherPainter/execute）接受以下 JSON 字段：

参数	类型	必填	说明 / 可选值
style	string	否	绘画风格：吉卜力漫画 / 水墨画 / 浪漫主义 / 扁平插画
ratio	string	否	画面比例：1:1 / 3:4 / 4:3 / 16:9 / 9:16
city	string	是	城市或景点名；建议「省份+城市」格式以避免同名歧义

参数与可选值一览

style 与 ratio 均为可选，缺省时由服务端使用默认风格与比例。city 为必填项，仅传入易重名城市（如「朝阳」「西安」存在多地）时建议补全省份。

可选风格与比例

4. 返回结构

创建任务成功时返回任务标识与两类查询入口。字段说明如下：

字段路径	类型	说明
showapi_res_code	int	网关层状态码，0 表示网关处理成功
showapi_res_error	string	网关层错误信息，成功时为空
showapi_res_id	string	本次请求唯一标识
showapi_res_body.ret_code	int	业务状态码，0 表示业务成功
showapi_res_body.remark	string	业务备注，成功时为 success
showapi_res_body.task_id	string	任务标识，用于后续查询
showapi_res_body.flow_id / flow_name	string	工作流标识与名称
showapi_res_body.query_info.short_term_query	object	短期查询入口（有效期 1 小时）
showapi_res_body.query_info.long_term_query	object	长期查询接入点（有效期 3 天）

完整成功返回样例：

{
   
  "showapi_res_body": {
   
    "query_info": {
   
      "long_term_query": {
   
        "endpoint": "（由创建任务返回的阿里云查询接入点）",
        "param": {
   
          "task_id": "3467_xxxxxxxxxxxx"
        },
        "desc": "适用于长期查询。调用查询接入点并传入 task_id，查询有效期为 3 天。"
      },
      "short_term_query": {
   
        "preview_url": "（由创建任务返回的短期预览地址，有效期 1 小时）",
        "query_status_url": "（由创建任务返回的短期查询地址，有效期 1 小时）",
        "desc": "短期查询与可视化预览（有效期 1 小时）。query_status_url 直接请求获取 JSON 结果；preview_url 在浏览器打开查看可视化结果。"
      }
    },
    "task_id": "3467_xxxxxxxxxxxx",
    "ret_code": 0,
    "remark": "success",
    "flow_id": "6a2a5e0b3c51f2492b002285",
    "flow_name": "城市天气宣传画报生成"
  },
  "showapi_res_id": "6a7042823c51f2492b002286",
  "showapi_res_error": "",
  "showapi_fee_num": 0,
  "showapi_res_code": 0
}

showapi_res_code 为 0 表示网关层成功；showapi_res_body.ret_code 为 0 表示业务成功。画报图片地址在查询结果（轮询返回）中，不在创建任务的响应里。

5. 错误码与排查

商品页未提供独立错误码表，以下基于接口返回结构与网关通用行为整理：

现象	含义	原因	解决办法
ret_code=1，remark「参数错误」	业务参数校验失败	city 为空，或 style / ratio 取值不在枚举范围	校验 city 必填，style / ratio 取文档枚举值
showapi_res_code 非 0	网关层错误	APPCODE 错误或缺失、签名校验失败	检查 Authorization 头与凭据是否正确
创建成功但查询无结果	查询入口过期或任务未完成	短期入口 1 小时 / 长期接入点 3 天过期；任务仍在队列	重新创建任务，或延长轮询间隔后重试
消歧结果不符	输入了重名城市	仅传入城市名，省市级联歧义	city 改为「省份+城市」格式

失败返回样例（业务参数错误）：

{
   
  "showapi_res_body": {
   
    "ret_code": 1,
    "remark": "参数错误"
  },
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_id": "6a7042823c51f2492b002287"
}

6. 频控与合规

调用频率：单账户 QPS 上限与每日配额以阿里云云市场控制台实时配置为准；高并发场景建议在业务侧做队列与限流。
数据来源：天气数据来自实时数据源，每次创建任务均重新查询并融合。
合规边界：输出为算法生成图像，不保证与真实摄影一致；请勿将接口用于生成违法、侵权或误导性内容，调用产生的图片用途由使用方自行负责。
计费说明：本接口按调用次数计费，具体计费标准以阿里云云市场公示为准。

7. 多语言接入示例

以下示例均演示「创建任务」调用，鉴权头使用 APPCODE 方式；域名以裸域名书写，scheme 通过变量拼接，避免代码中固化链接地址。请将 YOUR_APPCODE 替换为实际凭据。

7.1 Java

import java.util.HashMap;
import java.util.Map;

public class CweatherDemo {
   
    public static void main(String[] args) {
   
        String host = "cweather.market.alicloudapi.com"; // 阿里云 API 网关
        String path = "/weatherPainter/execute";
        String scheme = "https";
        String appcode = "YOUR_APPCODE";
        Map<String, String> headers = new HashMap<String, String>();
        headers.put("Authorization", "APPCODE " + appcode);
        headers.put("Content-Type", "application/json; charset=UTF-8");
        String bodys = "{\"style\":\"水墨画\",\"ratio\":\"9:16\",\"city\":\"陕西西安\"}";
        String url = scheme + "://" + host + path;
        // HttpUtils.doPost(url, headers, bodys) 发送请求
    }
}

7.2 Python

import requests

host = "cweather.market.alicloudapi.com"  # 阿里云 API 网关
path = "/weatherPainter/execute"
scheme = "https"
url = scheme + "://" + host + path
headers = {
   
    "Authorization": "APPCODE YOUR_APPCODE",
    "Content-Type": "application/json; charset=UTF-8",
}
body = {
   
    "style": "水墨画",
    "ratio": "9:16",
    "city": "陕西西安",
}
resp = requests.post(url, json=body, headers=headers)
print(resp.json())

7.3 PHP

<?php
$host = "cweather.market.alicloudapi.com"; // 阿里云 API 网关
$path = "/weatherPainter/execute";
$scheme = "https";
$url = $scheme . "://" . $host . $path;
$appcode = "YOUR_APPCODE";
$body = json_encode(array(
    "style" => "水墨画",
    "ratio" => "9:16",
    "city"  => "陕西西安",
));
$headers = array(
    "Authorization: APPCODE " . $appcode,
    "Content-Type: application/json; charset=UTF-8",
);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);
echo $result;
?>

7.4 Node.js

const https = require("https");

const host = "cweather.market.alicloudapi.com"; // 阿里云 API 网关
const path = "/weatherPainter/execute";
const appcode = "YOUR_APPCODE";

const data = JSON.stringify({
   
  style: "水墨画",
  ratio: "9:16",
  city: "陕西西安",
});

const options = {
   
  hostname: host,
  path: path,
  method: "POST",
  headers: {
   
    Authorization: "APPCODE " + appcode,
    "Content-Type": "application/json; charset=UTF-8",
    "Content-Length": Buffer.byteLength(data),
  },
};

const req = https.request(options, (res) => {
   
  let chunk = "";
  res.on("data", (d) => (chunk += d));
  res.on("end", () => console.log(chunk));
});
req.write(data);
req.end();

7.5 curl

HOST="cweather.market.alicloudapi.com"
PATH="/weatherPainter/execute"
SCHEME="https"
curl -X POST \
  "${SCHEME}://${HOST}${PATH}" \
  -H "Authorization: APPCODE YOUR_APPCODE" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d '{"style":"水墨画","ratio":"9:16","city":"陕西西安"}'

8. 接入最佳实践

异步接入步骤

异步轮询：创建任务仅返回 task_id 与查询入口，画报需通过查询获取。短期入口有效期 1 小时，长期接入点有效期 3 天，过期需重新创建任务。建议对查询结果做本地缓存，避免重复查询。
重试策略：仅对网络层异常（超时、5xx、连接失败）使用指数退避重试；业务参数错误（ret_code=1）属于确定失败，应修正参数而非重试。
幂等与去重：同一 city + style + ratio 每次会生成新的 task_id，业务侧应基于请求参数做去重，避免重复提交产生重复扣费。
超时设置：创建任务为毫秒级返回任务标识，绘画耗时发生在查询侧。客户端应为创建请求设置合理超时，并为查询轮询设置递增间隔。
异常兜底：同时解析 showapi_res_code（网关层）与 ret_code（业务层）双状态，任一非 0 均视为异常并进入统一错误处理；凭据异常需集中拦截。
凭据安全：APPCODE / AppKey 应存放在环境变量或配置中心，禁止在前端、客户端代码中硬编码，禁止提交至代码仓库。

9. 技术 FAQ

Q1：支持哪些请求参数？
A：city 为必填（城市或景点名），style 与 ratio 为可选枚举。style 取值为吉卜力漫画 / 水墨画 / 浪漫主义 / 扁平插画；ratio 取值为 1:1 / 3:4 / 4:3 / 16:9 / 9:16。

Q2：为什么创建任务后拿不到画报图片？
A：接口为异步模式，创建任务仅返回任务标识与查询入口，画报图片在查询结果中返回，需按返回的查询地址轮询获取。

Q3：查询入口的有效期是多久？
A：短期查询入口有效期 1 小时，长期查询接入点有效期 3 天，过期后需重新创建任务。

Q4：支持哪些鉴权方式？
A：支持 APPCODE 简单认证（请求头 Authorization: APPCODE xxxx）与 AppKey & AppSecret 签名认证两种方式。

Q5：调用频率与配额如何评估？
A：单账户 QPS 上限与每日配额以阿里云云市场控制台实时配置为准；高并发场景建议在业务侧做队列与限流。

Q6：如何判断一次调用是否成功？
A：需同时满足 showapi_res_code == 0（网关层成功）且 showapi_res_body.ret_code == 0（业务成功）。

Q7：城市消歧结果不准确怎么办？
A：多为输入了易重名城市导致，建议将 city 改为「省份+城市」格式（如「陕西西安」）以降低歧义。

Q8：天气数据从哪里来，更新频率如何？
A：天气数据来自实时数据源，每次创建任务均会重新查询并融合进画报。

10. 小结

城市天气宣传画报生成接口（cweather）通过阿里云 API 网关提供异步图像生成能力：输入城市或景点名称，由服务端完成省市消歧、实时天气融合、地标构图与指定风格出图。接入时需注意以下要点：

创建任务（POST /weatherPainter/execute）仅返回 task_id 与查询入口，画报需异步轮询获取。
请求参数中 city 必填，style / ratio 为可选枚举。
成功判定需同时检查 showapi_res_code 与 ret_code 双状态。
查询入口短期 1 小时、长期 3 天有效，过期需重新创建任务。
凭据应安全管理，QPS 与计费以控制台实时配置为准。

接口由阿里云云市场入驻服务商提供，上述字段与调用方式均基于商品页公开文档整理。

城市天气宣传画报生成接口（cweather）技术接入文档

1. 背景与适用场景

2. 接口概览

3. 请求参数

4. 返回结构

5. 错误码与排查

6. 频控与合规

7. 多语言接入示例

7.1 Java

7.2 Python

7.3 PHP

7.4 Node.js

7.5 curl

8. 接入最佳实践

9. 技术 FAQ

10. 小结

云市场头条

热门文章

最新文章

相关电子书

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

城市天气宣传画报生成接口（cweather）技术接入文档

1. 背景与适用场景

2. 接口概览

3. 请求参数

4. 返回结构

5. 错误码与排查

6. 频控与合规

7. 多语言接入示例

7.1 Java

7.2 Python

7.3 PHP

7.4 Node.js

7.5 curl

8. 接入最佳实践

9. 技术 FAQ

10. 小结

云市场头条

热门文章

最新文章

相关电子书