城市天气画报生成接口(英文名称 cweather)是一类基于工作流的图片生成服务:调用方输入城市名或景点名,服务端自动完成省市消歧、实时天气查询、城市地标提炼与构图设计,把天气、地标、日期与指定绘画风格融合成画报提示词,最终异步产出一张城市天气宣传画报图片。绘画风格支持水墨画、吉卜力漫画、浪漫主义、扁平插画;画面比例支持 1:1、3:4、4:3、16:9、9:16。接口采用异步任务模式:先创建任务拿到任务标识,再轮询查询生成结果,适合文旅宣传素材、城市名片、社交分享配图与媒体配图等技术场景。本文从接口契约、参数设计、返回结构、在线调试、错误排查与工程实践几个角度,梳理这套接口的接入方式。
一、技术简介
城市天气画报生成接口把「查天气 + 找地标 + 写提示词 + 文生图」这条链路封装成一次业务调用。对调用方而言,只需要给出城市、风格和比例三个输入,服务端会按六个步骤依次处理:城市消歧、天气查询、地标构图、提示词生成、图片生成与状态轮询。整个过程不需要调用方自己接入天气数据源,也不需要手工编写绘画提示词。
从技术形态上看,这是一个典型的异步工作流接口,具备三个特征:
- 输入收敛:必填项只有一个城市名字段,风格与比例都有默认值,接入成本低。
- 过程可追踪:返回结果里保留了每个步骤的中间产物(如消歧结果、天气明细、地标列表、提示词文本),便于调试与审计。
- 结果即图片:最终产物是一张可直接访问的画报图片链接,调用方拿到链接后可直接用于展示或转存。
接口通过标准 HTTPS 提供服务,请求与响应均为 JSON,鉴权采用阿里云云市场 API 网关的 APPCODE 简单认证方式(请求头 Authorization: APPCODE <appcode>),也支持 AppKey & AppSecret 签名认证。调用凭据在订购后于控制台获取。

二、能力概览
接口提供的能力可以归纳为六个方面,均为中性技术描述,具体返回以控制台实时配置为准。
| 能力 | 说明 | 适用情形 |
|---|---|---|
| 城市消歧 | 输入城市或景点名,识别标准省市 | 城市名存在同名或简称时 |
| 实时天气融合 | 查询目标城市天气与气温区间并写入画面文字 | 画报需带当日气象信息时 |
| 地标构图 | 提炼城市地标,设计前景-中景-远景三层构图 | 突出城市辨识度的画面 |
| 多风格生成 | 按指定绘画风格生成画报提示词与图片 | 不同宣传调性的视觉素材 |
| 灵活比例 | 按指定宽高比输出竖版或横版画面 | 适配海报、封面、Banner 等 |
| 异步任务 | 创建任务后轮询查询状态与结果 | 批量提交与系统集成场景 |
绘画风格与画面比例都是枚举输入,取值需要在请求体中严格按约定拼写。
| 参数 | 可选值 | 说明 |
|---|---|---|
| style | 吉卜力漫画、水墨画、浪漫主义、扁平插画 | 绘画风格,缺省时按服务端默认处理 |
| ratio | 1:1、3:4、4:3、16:9、9:16 | 画面宽高比,竖版常用 9:16、3:4 |
| city | 城市名或景点名 | 必填,建议「省份+城市」以避免同名歧义 |
三、适用场景
以下场景描述的是数据流向与技术情境,不涉及业务收益量化。
文旅宣传素材生产:把城市名作为输入,服务端融合地标与当日天气后生成画报图片,调用方把图片链接接入自有内容系统。数据流向为:城市名 → 标准省市 → 天气明细 → 地标列表 → 提示词 → 图片链接。
城市名片与景点介绍:输入景点名时,系统会先做省市消歧,识别景点所属的标准城市,再据此提炼地标。对于「西安」这类存在同名区级单位的名字,建议显式传入「陕西西安」减少歧义。
社交分享与媒体配图:指定风格与比例后生成竖版画面,调用方按需转存。由于每次调用都会实时生成,同一城市在不同日期调用会得到带当日天气信息的新画报。
批量素材流水线:由于接口是异步任务模式,可以在提交侧连续创建多个任务,再用任务标识逐个轮询结果,适合多城市、多风格的批量素材整理。

四、接入流程
接入分两步:先创建任务,再轮询查询。鉴权统一使用请求头 Authorization: APPCODE <appcode>。
4.1 创建任务
- 请求方式:POST
- 路径:
/weatherPainter/execute - 请求体(Body,JSON):
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| city | string | 是 | 城市名或景点名,建议「省份+城市」 |
| style | string | 否 | 绘画风格枚举值 |
| ratio | string | 否 | 画面宽高比枚举值 |
请求体示例:
{
"city": "陕西西安",
"style": "水墨画",
"ratio": "9:16"
}
创建成功后会返回任务标识 task_id,用于后续查询。
4.2 轮询查询
- 请求方式:GET
- 路径:
/weatherPainter/query/{task_id} - 路径参数:
task_id,来自创建任务的返回值 - 请求头:
Authorization: APPCODE <appcode>
建议轮询间隔 1–2 秒,当 task_status 变为 SUCCEEDED 或 FAILED 时停止轮询。运行中状态为 RUNNING。

4.3 完整步骤
- 在控制台订购服务并获取 APPCODE。
- 用 APPCODE 组装鉴权请求头。
- 调用创建任务接口,解析返回中的
task_id。 - 用
task_id定时调用查询接口,读取task_status与progress。 - 状态为成功后,读取
flow_result.output中的图片链接与相关字段。 - 对图片链接做可访问性校验,再按需转存到自有存储。
五、调用示例与返回结构
下面给出四种语言的调用示例。示例中的域名按控制台给出的接入地址填写,鉴权头统一用 APPCODE。
5.1 Python 示例
import json
import time
import urllib.request
APPCODE = "YOUR_APPCODE"
BASE = "https://cweather.market.alicloudapi.com"
HEADERS = {
"Authorization": "APPCODE " + APPCODE,
"Content-Type": "application/json",
}
def post(path, payload):
req = urllib.request.Request(
BASE + path,
data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
headers=HEADERS,
method="POST",
)
with urllib.request.urlopen(req, timeout=30) as resp:
return json.loads(resp.read().decode("utf-8"))
def get(path):
req = urllib.request.Request(BASE + path, headers=HEADERS, method="GET")
with urllib.request.urlopen(req, timeout=30) as resp:
return json.loads(resp.read().decode("utf-8"))
# 1) 创建任务
created = post("/weatherPainter/execute", {
"city": "陕西西安", "style": "水墨画", "ratio": "9:16"
})
task_id = created["showapi_res_body"]["flow_result"]["output"]["task_id"]
# 2) 轮询查询
for _ in range(60):
r = get("/weatherPainter/query/" + task_id)
body = r["showapi_res_body"]
status = body.get("task_status")
if status in ("SUCCEEDED", "FAILED"):
break
time.sleep(2)
# 3) 读取结果
output = body["flow_result"]["output"]
print(output["poster_image_url"], output["temperature_range"])
5.2 Java 示例
import java.net.*;
import java.io.*;
import java.nio.charset.StandardCharsets;
public class WeatherPoster {
static final String APPCODE = "YOUR_APPCODE";
static final String BASE = "https://cweather.market.alicloudapi.com";
static String request(String path, String method, String bodyJson) throws Exception {
HttpURLConnection conn = (HttpURLConnection) new URL(BASE + path).openConnection();
conn.setRequestMethod(method);
conn.setRequestProperty("Authorization", "APPCODE " + APPCODE);
conn.setRequestProperty("Content-Type", "application/json; charset=utf-8");
if (bodyJson != null) {
conn.setDoOutput(true);
conn.getOutputStream().write(bodyJson.getBytes(StandardCharsets.UTF_8));
}
int code = conn.getResponseCode();
InputStream in = code >= 200 && code < 300 ? conn.getInputStream() : conn.getErrorStream();
ByteArrayOutputStream bos = new ByteArrayOutputStream();
byte[] buf = new byte[4096];
int n;
while ((n = in.read(buf)) != -1) bos.write(buf, 0, n);
return new String(bos.toByteArray(), StandardCharsets.UTF_8);
}
public static void main(String[] args) throws Exception {
String created = request("/weatherPainter/execute", "POST",
"{\"city\":\"陕西西安\",\"style\":\"水墨画\",\"ratio\":\"9:16\"}");
// 解析 created 中的 task_id 后按间隔轮询 query 接口,读取 flow_result.output
System.out.println(created);
}
}
5.3 PHP 示例
<?php
$appcode = "YOUR_APPCODE";
$base = "https://cweather.market.alicloudapi.com";
function call_api($base, $path, $appcode, $payload = null) {
$ch = curl_init($base . $path);
$headers = ["Authorization: APPCODE " . $appcode, "Content-Type: application/json; charset=utf-8"];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
if ($payload !== null) {
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload, JSON_UNESCAPED_UNICODE));
}
$res = curl_exec($ch);
curl_close($ch);
return json_decode($res, true);
}
$created = call_api($base, "/weatherPainter/execute", $appcode,
["city" => "陕西西安", "style" => "水墨画", "ratio" => "9:16"]);
// 解析 task_id,定时调用 /weatherPainter/query/{task_id} 读取 flow_result.output
print_r($created);
5.4 JavaScript 示例(Node.js)
const APPCODE = "YOUR_APPCODE";
const BASE = "https://cweather.market.alicloudapi.com";
async function call(path, options = {
}) {
const resp = await fetch(BASE + path, {
...options,
headers: {
"Authorization": "APPCODE " + APPCODE,
"Content-Type": "application/json; charset=utf-8",
},
});
return resp.json();
}
(async () => {
const created = await call("/weatherPainter/execute", {
method: "POST",
body: JSON.stringify({
city: "陕西西安", style: "水墨画", ratio: "9:16" }),
});
// 解析 task_id 后按间隔轮询 /weatherPainter/query/{task_id}
console.log(JSON.stringify(created, null, 2));
})();
5.5 返回结构样例
成功任务的返回结果中,核心信息集中在 flow_result.output,样例如下(字段以实际返回为准):
{
"showapi_res_error": "",
"showapi_res_body": {
"status": "SUCCESS",
"flow_name": "城市天气宣传画报生成",
"steps_num": 6,
"progress": 100,
"task_status": "SUCCEEDED",
"flow_result": {
"input": {
"city": "西安", "style": "漫画风格", "ratio": "9:16" },
"output": {
"poster_prompt": "一幅城市天气宣传画报……画面上书写城市名、天气与气温、日期……",
"poster_image_url": "https://.../tasks/xxxx.png",
"temperature_range": "24℃~38℃",
"city_name": "陕西西安",
"weather_condition": "晴"
},
"step_1_city_disambiguate": {
"result": {
"data": {
"city_name": "西安" } } },
"step_2_get_weather": {
"result": {
"data": {
"f2": {
"day_weather": "小雨" } } } },
"step_3_landmark_composition": {
"result": {
"data": {
"landmarks": [] } } },
"step_4_generate_poster_prompt": {
"result": {
"data": {
"result": "" } } },
"step_5_generate_image": {
"result": {
"data": {
} } },
"step_6_poll_image_status": {
"result": {
"data": {
"task_status": "SUCCEEDED" } } }
}
}
}
output 各字段含义:
| 字段 | 含义 | 示例 |
|---|---|---|
| poster_image_url | 生成的画报图片链接 | https://.../tasks/xxxx.png |
| poster_prompt | 用于生成画报的提示词文本 | 一段中文画面描述 |
| temperature_range | 气温区间 | 24℃~38℃ |
| city_name | 标准化后的城市名 | 陕西西安 |
| weather_condition | 天气状况 | 晴 |

六、在线调试实录
服务端一次任务包含六个处理步骤,progress 字段反映整体推进程度,各步骤结果写入 flow_result 便于追踪。

下面用一次完整走查说明请求设计、响应追踪与字段解读。
请求参数设计:城市取「陕西西安」而不是「西安」,是为了在消歧阶段直接命中标准省市,减少同名干扰;风格选「水墨画」,比例选 9:16,得到适合竖版展示的画报。请求体只有三个字段,鉴权放在请求头。
响应追踪:创建任务后拿到 task_id,进入轮询。前几次轮询 task_status 为 RUNNING、progress 逐步上升;最终一次 task_status 为 SUCCEEDED、progress 为 100,此时 flow_result 里六个步骤的结果都已填好。
字段解读:从 output 读取 poster_image_url 即为画报图片链接;poster_prompt 记录服务端根据天气、地标、日期与风格融合出的提示词,可用于复现或审计;temperature_range、city_name、weather_condition 分别给出气温区间、标准城市名与天气状况,可与业务侧数据核对。
调试建议:把每次轮询的 task_status、progress、polling_count 打印到日志,便于定位是卡在消歧、天气查询还是生图阶段;失败时先检查 city 是否为合法城市名,再检查风格与比例是否使用了约定枚举值。

七、接口调用限制与规范
以下为通用工程约束,具体数值以控制台实时配置为准。
| 维度 | 说明 |
|---|---|
| 鉴权 | 请求头 Authorization: APPCODE <appcode>,或 AppKey & AppSecret 签名方式 |
| 数据格式 | 请求与响应均为 JSON,字符编码 UTF-8 |
| 协议 | HTTPS |
| 调用模式 | 异步:创建任务 + 轮询查询 |
| 轮询节奏 | 建议 1–2 秒一次,成功或失败后停止 |
| 频率约束 | 遵守账户对应的调用频率与并发限制,超限返回限流错误 |
| 输入约束 | city 必填;style、ratio 取约定枚举值 |
| 合规要求 | 按授权范围使用生成内容,不用于超出用途的场景 |
高频调用时建议在提交侧做节奏控制:连续创建任务后按队列方式轮询,避免对查询结果接口造成瞬时压力;对同一个 task_id 的轮询结果做本地缓存,成功后不再重复请求。
八、能力边界与免责声明
支持范围:城市名与景点名的画报生成;标准枚举内的绘画风格与画面比例;异步任务创建与结果查询;返回中间步骤产物用于调试与审计。
不支持场景:非城市/景点的任意文本生成画报;枚举外的自定义风格或任意尺寸;对历史某一天的天气画报做回溯生成;实时同步返回结果(接口为异步模式)。
边界说明:天气信息来自服务端查询结果,具有时效性;地标提炼依赖城市知名度与数据覆盖,小众地点可能识别不完整;同一输入在不同时间调用,因天气变化会得到不同画报。
免责声明:接口返回的数据与图片仅供参考,调用方应结合自身业务校验后再使用,不对基于生成内容作出的业务决策承担责任。图片内容由生成模型产出,使用前应做必要的合规检查。
九、错误码与排查指南
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
| 返回权限不足 | APPCODE 错误或未提供 | 检查鉴权头格式与 APPCODE 是否有效 |
| 返回参数错误 | city 为空或字段拼写错误 |
核对必填项与字段名 |
| 风格/比例不生效 | 使用了枚举外的值 | 改用约定枚举值,注意中文字符完全一致 |
| 城市消歧结果异常 | 输入为同名城市简称 | 改用「省份+城市」格式,如「陕西西安」 |
| 一直处于 RUNNING | 生图阶段耗时较长 | 延长轮询窗口,检查 progress 是否推进 |
| 返回限流错误 | 调用频率超限 | 降低提交节奏,做退避重试 |
| 图片链接打不开 | 链接过期或网络问题 | 重新查询任务结果,或转存到自有存储 |
| JSON 解析失败 | 响应被截断或编码不一致 | 确认以 UTF-8 读取完整性后再解析 |
排查顺序建议:先鉴权、再参数、后状态、最后网络。鉴权与参数属于调用方可控问题,优先排查可以最快恢复调用。
十、常见问题 FAQ
Q:一次调用能直接拿到画报图片吗?
A:不能。接口为异步模式,先创建任务拿到 task_id,再轮询查询,成功后从 flow_result.output 读取 poster_image_url。
Q:城市名一定要带省份吗?
A:不强制,但建议「省份+城市」格式。仅输入城市名时系统会自动消歧,遇到同名城市时显式带省份更稳妥。
Q:支持哪些绘画风格和比例?
A:风格为吉卜力漫画、水墨画、浪漫主义、扁平插画;比例为 1:1、3:4、4:3、16:9、9:16。均需在请求体中按约定值填写。
Q:多久能生成一张画报?
A:取决于服务端排队与生图耗时,通常在数十秒量级。以 task_status 变为 SUCCEEDED 为准,不要按固定时间假设结果已完成。
Q:轮询间隔多少合适?
A:建议 1–2 秒一次。间隔过短会增加无效请求,过长会拉高整体等待时间。
Q:返回的提示词有什么用?
A:poster_prompt 记录了服务端融合天气、地标、日期与风格后的画面描述,可用于结果复现、内容审计或二次处理。
十一、内容小结
城市天气画报生成接口把城市消歧、天气查询、地标构图、提示词生成与图片生成封装成一条异步工作流。接入要点可以归纳为四条:一是鉴权统一用请求头 APPCODE;二是输入只有三个字段,其中 city 必填,建议「省份+城市」;三是采用创建任务 + 轮询查询两步模式,成功或失败后停止轮询;四是最终结果集中在 flow_result.output,核心是 poster_image_url,并附带提示词、气温区间、标准城市名与天气状况。
工程实践上,建议把轮询状态与进度纳入日志,对任务结果做本地缓存,设置合理的超时与退避重试,并对生成的图片链接做可访问性校验后再转存。这样可以在保证调用稳定性的同时,便于定位问题与审计结果。