城市天气画报生成接口|输入城市、绘画风格与画面比例,返回画报图片链接、提示词与气温区间

简介: 接入城市天气画报生成接口常被异步任务状态与返回字段结构卡住?本文给出参数设计、创建任务与轮询查询流程、多语言调用示例与错误排查清单。内容覆盖城市消歧、天气融合、地标构图到提示词生成的处理链路,接口鉴权与请求参数、返回结构详解,以及在线调试、调用限制、能力边界与常见问题,帮助开发者完成城市天气画报生成接口的接入与结果解析。

城市天气画报生成接口(英文名称 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 完整步骤

  1. 在控制台订购服务并获取 APPCODE。
  2. 用 APPCODE 组装鉴权请求头。
  3. 调用创建任务接口,解析返回中的 task_id。
  4. 用 task_id 定时调用查询接口,读取 task_status 与 progress。
  5. 状态为成功后,读取 flow_result.output 中的图片链接与相关字段。
  6. 对图片链接做可访问性校验,再按需转存到自有存储。

五、调用示例与返回结构

下面给出四种语言的调用示例。示例中的域名按控制台给出的接入地址填写,鉴权头统一用 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,并附带提示词、气温区间、标准城市名与天气状况。

工程实践上,建议把轮询状态与进度纳入日志,对任务结果做本地缓存,设置合理的超时与退避重试,并对生成的图片链接做可访问性校验后再转存。这样可以在保证调用稳定性的同时,便于定位问题与审计结果。

相关文章
|
18天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
7866 58
|
3天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
1481 0
|
5天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
19天前
|
JavaScript API iOS开发
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(DSH)是DeepSeek于2026年开源的MIT协议AI Agent框架,支持插件化组装模型、工具、沙箱与UI,兼容主流大模型。本文提供免Node.js的桌面端安装包(Win/macOS),含详细图文教程及热门插件推荐。
5689 68
|
6天前
|
云安全 人工智能 安全
|
13天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
2930 9
|
5天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
3天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
2057 0
|
11天前
|
人工智能 安全 API
DeepSeek Harness下载、安装、配置一篇搞定(2026整理,送常用插件)
DeepSeek Harness(dsh)是DeepSeek AI于2026年开源的轻量级Agent运行框架,基于Cordis内核,践行“一切皆插件”理念。支持Web/桌面双端,开箱即用;内置多模型接入、丰富插件生态(超3.5万),适配编程、办公、创作等场景。(239字)
1875 1