Qwen-Image-2.1 图片生成 API

快速开始

1. 文生图 —— 一次调用直接拿图

# 中文提示词请写进文件再提交（Windows 终端直接 -d '中文' 会编码错乱）
cat > body.json <<'EOF'
{"model":"qwen_image_2.1",
 "prompt":"一只金色巨龙盘踞在崩塌的山巅，乌云翻涌，金色光柱自天而降，电影级质感",
 "size":"1024x1024"}
EOF

curl -X POST http://47.111.83.139:13527/v1/images/generations \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  --data-binary @body.json

{
  "created": 1789959716,
  "data": [
    { "url": "http://47.111.83.139:13527/images/qwen21/img_1101560001_00001_.png",
      "filename": "img_1101560001_00001_.png", "width": 1024, "height": 1024 }
  ],
  "task_id": "img_1101560001",
  "status": "completed",
  "elapsed_seconds": 19.6
}

响应直接就是 OpenAI Images 形态（created + data[].url），拿 data[0].url 下载即可。 一张 1024×1024 默认约 20 秒（5 步 Turbo；传 turbo=false 走原版 25 步约 85 秒），请求会一直等到出图再返回。

2. 队列很深时会转异步（极少发生）

如果前面排了太多任务、1 小时内没能出图，响应会变成 202 并给 task_id（此时没有 data）， 这时才需要改用轮询：

curl http://47.111.83.139:13527/v1/images/generations/<task_id> \
  -H "Authorization: Bearer <你的 API Key>"
# status = completed 时 data[0].url 就是图

status 取值：pending（排队中，含 queue_position）→ running → completed / failed。 提交前可先 GET /health 看 queue.pending。

智能路由：不用指定模式

端点一览

参数完整说明

必填

输入（决定模式）

输出尺寸

传比例时怎么换算（保持总像素 ≈ 1024²，各取 16 的倍数，所以不同比例的耗时相近）：

加速开关 turbo（默认开启）

{ "prompt": "……", "turbo": false }   → 改走原版 25 步

采样（服务已固定，不接受自定义）

透明通道

其他 OpenAI 标准字段

完整示例

示例 1 · 文生图（固定种子，可复现）

curl -X POST http://47.111.83.139:13527/v1/images/generations \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "东方玄幻写实风格，不周山下崩塌山巅，万丈金色真龙盘踞，乌云紫雷，金色天缝倾泻金光",
    "size": "1536x1024",
    "seed": 20260921
  }'

示例 2 · 单图编辑（改一处，其余保持）

curl -X POST http://47.111.83.139:13527/v1/images/generations \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "把背景换成黄昏的海边，人物保持不动",
    "image": "http://47.111.83.139:13527/v1/files/my_photo.png",
    "resolution": 1024
  }'

示例 3 · 多图合成（最多 10 张）

curl -X POST http://47.111.83.139:13527/v1/images/generations \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "让图1的模特穿上图2的衣服、图3的鞋、戴图4的帽子，站在图5的场景里",
    "ref_images": [
      "https://example.com/model.png",
      "https://example.com/coat.png",
      "https://example.com/shoes.png",
      "https://example.com/hat.png",
      "https://example.com/scene.jpg"
    ]
  }'

示例 4 · 透明背景 PNG（角色素材）

curl -X POST http://47.111.83.139:13527/v1/images/generations \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只可爱的卡通小龙贴纸，正面站立",
    "background": "transparent",
    "output_format": "png"
  }'

示例 5 · 上传本地图再编辑

# 第一步：上传，拿回可复用的 URL / 文件名
curl -X POST http://47.111.83.139:13527/v1/files/upload \
  -H "Authorization: Bearer <你的 API Key>" \
  -F "image=@./my_photo.png"
# => {"data":[{"filename":"up_120000_000_png","url":".../v1/files/up_120000_000_png", ...}]}

# 第二步：用 upload 返回的 url 作为 image 提交编辑
curl -X POST http://47.111.83.139:13527/v1/images/generations \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"改成水彩风格","image":"http://47.111.83.139:13527/v1/files/up_120000_000_png"}'

示例 6 · /v1/images/edits（OpenAI multipart 形式）

curl -X POST http://47.111.83.139:13527/v1/images/edits \
  -H "Authorization: Bearer <你的 API Key>" \
  -F "image=@./a.png" \
  -F "image=@./b.png" \
  -F "prompt=把两张图里的人合成到同一张合影里" \
  -F "resolution=1024"

这个端点必须带图（否则 400）。它与 /v1/images/generations + ref_images 完全等价，选一个用即可。

示例 7 · Python（同步，一次调用拿图）

import requests

BASE = "http://47.111.83.139:13527"
H = {"Authorization": "Bearer <你的 API Key>"}

def generate(prompt, **kw):
    # 同步：超时要给够（一张图 ~20 秒，排队时更久）
    r = requests.post(f"{BASE}/v1/images/generations", headers=H,
                      json={"prompt": prompt, **kw}, timeout=900)
    if r.status_code >= 400:
        raise RuntimeError(r.json())          # 参数问题在这里能看到 issues
    job = r.json()
    if "data" not in job:                     # 队列太深时转异步
        raise RuntimeError("转异步了，请轮询 task_id: " + job["task_id"])
    return job["data"]                        # [{"url": ..., "width":..., "height":...}]

for img in generate("赛博朋克风格的城市夜景，霓虹倒影", size="1024x1024", seed=42):
    print(img["url"])

# 用 OpenAI 官方 SDK 也行（记得调大超时）：
#   from openai import OpenAI
#   c = OpenAI(base_url="http://47.111.83.139:13527/v1", api_key="<你的 API Key>", timeout=900)
#   r = c.images.generate(model="qwen_image_2.1", prompt="...", size="1024x1024")
#   print(r.data[0].url)

示例 8 · Node.js

const BASE = "http://47.111.83.139:13527";
const H = { "Authorization": "Bearer <你的 API Key>",
            "Content-Type": "application/json" };

async function generate(prompt, extra = {}) {
  const r = await fetch(`${BASE}/v1/images/generations`, {
    method: "POST", headers: H, body: JSON.stringify({ prompt, ...extra }),
  });
  const job = await r.json();
  if (!r.ok) throw new Error(JSON.stringify(job.error, null, 2));
  while (true) {
    const s = await (await fetch(`${BASE}/v1/images/generations/${job.id}`, { headers: H })).json();
    if (s.status === "completed") return s.data;
    if (s.status === "failed") throw new Error(s.error.message);
    await new Promise(r => setTimeout(r, 3000));
  }
}

console.log(await generate("一只在月球上弹吉他的猫", { background: "transparent" }));

内容规范

被拒绝时返回什么

HTTP 400
{
  "error": {
    "type": "content_filtered",
    "code": "content_filtered",
    "message": "提示词包含被禁止的内容，已拒绝生成。命中分类：色情；触发词：\"裸体\"（在 prompt 字段）。请修改后重试。",
    "category": "色情",
    "matched": "裸体",
    "field": "prompt",
    "issues": [
      { "field": "prompt", "code": "content_filtered", "message": "包含色情内容：「裸体」" }
    ]
  }
}

会**明确告诉你命中了哪个词** —— 这是有意的：万一你的正常提示词被误伤（比如"裸体雕塑"这类美术场景）， 你能立刻知道该改哪个词，而不是拿到一个莫名其妙的失败。

错误处理

参数错误（400）

{
  "error": {
    "type": "invalid_request_error",
    "message": "参数有 3 处问题，逐条见 issues",
    "issues": [
      { "field": "size",        "code": "bad_format",
        "message": "size 格式不对：收到 \"big\"，应为 \"宽x高\"（如 \"1024x1024\"），或预设值 1024x1024 / 1024x1536 / 1536x1024 / auto" },
      { "field": "steps",       "code": "out_of_range",
        "message": "steps 需在 1~100 之间，收到 0" },
      { "field": "ref_images[3]","code": "too_many",
        "message": "最多 10 张参考图（官方上限），当前给了 13 张" }
    ]
  }
}

field 定位到具体字段（数组带下标）；code 便于程序判断；message 是给人看的中文说明。

队列满（429）

{
  "error": {
    "type": "queue_full",
    "message": "队列已满：当前排队 50 个，上限 50 个。请稍后重试（可在 GET /health 查看实时排队数）。",
    "queue": { "pending": 50, "limit": 50 }
  }
}

队列上限 50 是排队数（不含正在跑的那个）。想知道什么时候能提交，先 GET /health 看 queue.pending。

其他状态码

任务本身失败（不是参数问题）时，HTTP 仍是 200，看 body 的 status: "failed" 和 error.message，里面带 ComfyUI 的具体报错节点。

查询模型

curl http://47.111.83.139:13527/v1/models      # 免鉴权

{
  "object": "list",
  "data": [{
    "id": "qwen_image_2.1",
    "object": "model",
    "owned_by": "qwen",
    "modes": ["t2i", "edit"],
    "mode_routing": "自动：请求带 image/ref_images 走 edit，否则走 t2i",
    "max_ref_images": 10,
    "native_size": "1024x1024（原生支持到 2048x2048）",
    "transparency": "支持，background=transparent（PNG）"
  }]
}

健康检查 / 队列

curl http://47.111.83.139:13527/health          # 免鉴权

{
  "status": "ok",
  "backend": { "reachable": true, "busy": false },
  "queue":   { "pending": 3, "limit": 50, "running": 0 }
}

使用须知