Qwen Image 3.0 API 中文接入教程

TL;DR

Qwen Image 3.0（通义千问图像 3.0）在 HiAPI 上有 4 个入口：标准版 qwen-image-3.0/text-to-image、qwen-image-3.0/image-to-image，Pro 版 qwen-image-3.0-pro/text-to-image、qwen-image-3.0-pro/image-to-image。打开模型页就能在线试。
标准版一口价每张 $0.0358（1K、2K 同价）；Pro 1K $0.0497、2K $0.0993。改图和生图同价，1–3 张参考图不加钱。
中文和中英双语文字是强项。调用方式：POST /v1/tasks 传 prompt、aspect_ratio、resolution，轮询到 success 后下载。

先看一张

标准版，16:9，招牌上的中文逐字写对：

qwen-image-3.0/text-to-image，16:9，$0.0358。

参数速查

字段	必填	取值	说明
`prompt`	是	最长 18000 字符	要出现的文字逐字写进引号里
`aspect_ratio`	否	`1:1`（默认）`3:2` `2:3` `4:3` `3:4` `16:9` `9:16` `21:9`
`resolution`	否	`1K`（默认）/ `2K`	标准版两档同价，Pro 2K 贵一倍
`output_format`	否	`png`（默认）/ `jpeg`
`prompt_extend`	否	布尔，默认 `true`	自动改写提示词；文字要求精确时关掉
`negative_prompt`	否	最长 500 字符	不想出现的内容
`seed`	否	0–2147483647	固定后便于复现
`image_urls`	改图入口必填	1–3 张	JPEG、PNG、WEBP 等，每张不超过 10 MB

参数严格校验，多传字段返回 400。注意：旧写法 "model": "qwen-image-3.0" 加 size 已经不能用了，会返回「模型不可用」或 additional properties 'size' not allowed，请改成上面的模型名和 aspect_ratio + resolution。

curl：跑通第一张

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0/text-to-image",
    "input": {
      "prompt": "一张秋季饮品海报，中间是一杯桂花拿铁，顶部大标题逐字写“秋日限定”，下方副标题写“桂花拿铁”，留白充足，柔和自然光",
      "aspect_ratio": "3:4",
      "resolution": "2K",
      "prompt_extend": false
    }
  }'

返回里有 data.taskId。轮询 GET /v1/tasks/{taskId}，status 变成 success 后从 output[0].url 下载。标准版 2K 和 1K 同价，直接要 2K。

Python：先生图，再改图

# pip install requests; export HIAPI_KEY=你的 Key
import os, time, uuid, requests

API = "https://api.hiapi.ai/v1/tasks"
H = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(model, timeout_s=300, **inp):
    # 重试同一次提交时复用同一个 Idempotency-Key，只会扣一次费
    r = requests.post(API, json={"model": model, "input": inp},
                      headers={**H, "Idempotency-Key": str(uuid.uuid4())}, timeout=30)
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        d = requests.get(f"{API}/{task_id}", headers=H, timeout=30).json()["data"]
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(4)
    raise TimeoutError(task_id)

# 文生图，标准版 2K（$0.0358）
poster = run("qwen-image-3.0/text-to-image",
             prompt="茶叶礼盒产品图，牛皮纸方盒正面写“云雾绿茶”，下方小字“净含量 100 克”，石板台面，柔和顶光",
             aspect_ratio="1:1", resolution="2K", prompt_extend=False)

# 改图：换成深色背景，文字不变（同样 $0.0358）
edited = run("qwen-image-3.0/image-to-image",
             prompt="保持礼盒和上面的文字完全不变，把背景换成深墨绿色绒布，加一缕侧光",
             image_urls=[poster], aspect_ratio="1:1", resolution="2K")

with open("tea.png", "wb") as f:
    f.write(requests.get(edited).content)

要换 Pro，只改模型名：qwen-image-3.0-pro/text-to-image 或 qwen-image-3.0-pro/image-to-image，参数完全一样。

多少钱

入口	1K	2K
标准版文生图 / 改图	$0.0358	$0.0358
Pro 文生图 / 改图	$0.0497	$0.0993

HiAPI 现价，2026 年 10 月 18 日核对。失败不扣费。

两档同提示词对照见 Qwen Image 3.0 API 价格。

上线前注意

文字要求精确时关掉 prompt_extend：默认会改写你的提示词，可能顺手改动你要的字。
要出现的文字逐字写进引号，并加一句「除以上文字外不要其他文字」。
用回调代替轮询：在 input 同级加 "callback": {"url": "https://your-app.example.com/hiapi/callback", "when": "final"}，按 taskId 去重。
带上 Idempotency-Key 请求头，重试时同一个 Key 只建一次任务。
结果马上下载：output[0].url 有有效期。