如何使用 Qwen Image 2.1 Turbo API：curl、Python 及一次实测请求

Qwen Image 2.1 Turbo（qwen-image-2.1-turbo）是 hiapi 上阿里巴巴 2.1 图像系列中速度快、价格低的档位。它接收文本提示词，可选 0–10 张参考图像，返回一张 2048×2048 的 PNG。本指南给出一个可直接运行的请求、API 实际强制执行的输入 schema、一次编辑调用，以及我们在测试“透明 PNG”这一说法时看到的结果。

你需要从控制台获取 hiapi API 密钥。调用通过统一的异步任务 API 进行，因此没有同步的图像响应。

最小请求：文本生成图像

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "贴纸风格的插画：一只戴着草帽的柴犬坐在冲浪板上，平涂配色，粗轮廓线，珊瑚橙与海蓝色",
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'
# {"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

然后轮询 GET /v1/tasks/<taskId>，直到 data.status 为 success，并读取 data.output[0].url。

import os, time, requests

BASE = "https://www.hiapi.ai"
HEADERS = {"Authorization": f"Bearer {os.environ['HIAPI_KEY']}"}

def run(input_: dict) -> str:
    r = requests.post(f"{BASE}/v1/tasks", headers=HEADERS, timeout=30,
                      json={"model": "qwen-image-2.1-turbo", "input": input_})
    r.raise_for_status()
    task_id = r.json()["data"]["taskId"]          # 注意：字段是 taskId，不是 id

    while True:
        try:
            d = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30).json()["data"]
        except requests.RequestException:
            time.sleep(3)                          # 临时网络错误：继续轮询同一个 id
            continue
        if d["status"] == "success":
            return d["output"][0]["url"]
        if d["status"] in ("fail", "failed"):
            raise RuntimeError(d)
        time.sleep(3)                              # pending / running / archiving

url = run({"prompt": "a straw-hat shiba on a surfboard, flat sticker style", "aspect_ratio": "1:1"})
open("out.png", "wb").write(requests.get(url, timeout=60).content)

请立即下载文件。输出 URL 位于 temp.hiapi.ai，带有 expireAt 时间戳（在我们的运行中约为创建后七天）；如果需要保留更久，请自行保存文件字节。

输入 schema（API 实际强制执行的规则）

以下内容来自我们故意发送无效请求后返回的校验错误，因此反映的是线上端点的真实行为，而不是文档的转述：

字段	规则
prompt	必填字符串（模型页面的表单将其上限设为 4500 个字符）
aspect_ratio	取值为 1:1、16:9、9:16、4:3、3:4 之一
image_urls	参考图像 URL 数组，0–10 项；直接传字符串会被拒绝，并返回 image_urls must be an array
prompt_extend	布尔值，提示词优化开关
seed	整数，0 到 2147483647

有两点与同系列的其他 Qwen 模型不同。这里没有 resolution 字段：发送该字段会返回 additional properties 'resolution' not allowed。对于 1:1，输出是固定的 2048×2048 画布，这一点我们已实测。此外，未知字段通常会被拒绝，而不是被忽略。错误的 aspect_ratio 会返回 HTTP 400，带有 error_code: INVALID_REQUEST，并在 message 中列出允许的取值。

使用参考图像进行编辑

编辑和风格重绘使用相同的模型 id。将源图像放入 image_urls，并在提示词中描述修改内容：

curl -s -X POST https://www.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-turbo",
    "input": {
      "prompt": "把草帽重新着色为深紫色，其他部分保持不变",
      "image_urls": ["https://temp.hiapi.ai/.../source.png"],
      "aspect_ratio": "1:1",
      "seed": 42
    }
  }'

我们在真实运行中观察到的结果

我们在 2026-10-24 运行了一次文本生成图像调用和一次编辑调用，均使用 seed: 42、aspect_ratio: "1:1"。

• 延迟：文本生成图像在创建后约 29 秒达到 success（任务 created 到 completed 时间戳）；编辑约用了 22 秒。状态在进入 success 之前会经过 archiving 若干次轮询，因此不要把非终态视为错误。这只是两个样本，不是基准测试。
• 输出：两者都返回了 2048×2048 的 PNG，文本生成图像的结果约 3.9 MB。
• 编辑行为：我们将第一个输出重新输入，并要求把帽子变成紫色。结果保留了狗、姿态、海浪和布局，并将帽带和丝带偏向紫色；帽子的草编主体基本仍为草色。对于有纹理物体上的颜色修改，编辑的指令遵循程度可能只是部分生效，提示词应写得具体（例如“把帽带重新着色”），而不是笼统描述。
• 透明背景：alpha 通道完全不透明。模型页面宣传可输出透明背景 PNG，我们在提示词中写入了“纯透明背景，仅保留主体和飞溅效果”。返回的文件是 RGBA，但每个像素的 alpha 均为 255（零个透明像素），四角为浅灰白色（例如 (241, 243, 248, 255)）。查看图像后发现，模型将淡淡的棋盘格风格背景绘制进了像素中，而不是让这些像素保持透明。编辑输出表现相同（最小 alpha 为 241）。因此在我们的运行中，仅靠提示词并没有得到可直接放到彩色页面上的抠图。这一结果仅对应一种提示词写法；我们没有找到可切换透明度的请求字段（transparent 会因未知属性被拒绝）。如果你需要真正的 alpha 通道，请规划一个背景移除步骤，例如参考 851-labs 背景移除指南，并在上线前用类似 Image.open(f).getchannel("A").getextrema() 的像素检查进行验证。

生产环境注意事项

• 高并发下用回调替代轮询：在任务请求体中添加 "callback": {"url": "https://your.app/hook", "when": "final"}，将回调视为提示，再用 GET /v1/tasks/<taskId> 确认结果。
• 保留 taskId：如果轮询因网络错误失败，请重新轮询同一个 id，而不是重新提交。重新提交会创建并计费第二个任务。
• 固定 seed，以便在调整提示词时获得可比较的输出；将其视为尽力而为，而不是硬性保证。
• 计费前先校验：schema 错误（HTTP 400、INVALID_REQUEST）会在创建时返回，此时尚未生成任何图像。

选择哪个档位

同一系列还有 Qwen Image 2.1 Pro，在定价页面上标注的每张图像价格高于 Turbo。两者都被描述为支持文本生成图像、编辑和 0–10 张参考图像；我们只运行了 Turbo，因此不对相对图像质量作任何断言。Turbo 的优势在于更低的价格和 8 步速度；如果你的素材更看重输出质量，请用相同的提示词和 seed 在两者上分别运行并比较。对于更新的 Qwen 3.0 代际，请参阅 Qwen Image 3.0 API 指南和 Qwen Image 3.0 Pro 指南。

相关内容

• Qwen Image 2.1 Turbo 模型页面
• 定价
• Qwen Image 3.0 API 指南
• 文档

常见问题

模型 id 是什么？ qwen-image-2.1-turbo，通过 POST /v1/tasks 发送。

可以选择输出分辨率吗？ 在此 schema 中不可以：没有 resolution 字段。请从五个允许值中选择一个 aspect_ratio。

支持编辑吗？ 支持：在 image_urls 中传入 1–10 张源图像，并附上指令提示词。在我们的测试中，对有纹理区域的颜色编辑仅部分生效。

会返回透明 PNG 吗？ 在我们的测试中不会：文件是 RGBA 模式，但 alpha 通道完全不透明，且带有绘制出的背景。请自行验证 alpha，如果需要真正的透明度，请添加背景移除步骤。

价格是多少？ 请参阅定价页面；在撰写本文时，它是两个 2.1 档位中价格较低的一个。