千问图像生成与编辑 3.0（百炼原生协议）

模型

两个模型都同时支持文生图（T2I）和图生图 / 图像编辑（I2I）：不传参考图是文生图，传 1–3 张参考图是图生图。图像同步返回，无需轮询。

不支持异步任务通道。 这一族只在同步接口上服务；打 /v1/content_generation/tasks 会被拒。

两条入站通道

同一个模型有两种调用写法，能力完全一致，按你现有代码的形状选：

两条通道的 size 分隔符不同，且互不接受：OpenAI 兼容通道用字母 x（1024x1024），百炼原生通道用星号 *（1024*1024）。写错的那一侧会返回 400 并点名正确的分隔符，不会被静默改写 —— 这是为了让协议混用尽早显形，而不是在别处出更难查的问题。

1. OpenAI 兼容通道

POST https://api.modelgo.com/v1/images/generations

文生图

curl https://api.modelgo.com/v1/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "prompt": "一只毛茸茸的橘猫坐在阳光下的窗台上，午后光线，胶片质感",
    "size": "1024x1024",
    "n": 1
  }'

图生图 / 图像编辑

不用 multipart，参考图放在请求体顶层的 image 字段：

curl https://api.modelgo.com/v1/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "prompt": "保留这位女性的面部特征，把服装换成香槟色真丝衬衫与深灰西装外套",
    "image": ["https://example-cdn.com/portrait.png"],
    "size": "1024x1024",
    "prompt_extend": true
  }'

响应

{
  "created": 1788339600,
  "data": [{"url": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"}],
  "usage": {
    "output_width": 1024, "output_height": 1024,
    "input_image_count": 0, "input_image_type": "qima_input_1k",
    "output_image_count": 1, "output_image_type": "qima_output_1k"
  }
}

• 图像格式为 PNG，链接有效期 24 小时，请及时下载，不要持久化该 URL。
• usage 是图片张数与档位，不是 token 用量 —— 这一族的计费完全按张，见「计费口径」。
• 传 response_format: "b64_json" 不会报错，但会被忽略，响应中仍是图像 URL。

使用 OpenAI SDK

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MODELGO_API_KEY"],
    base_url="https://api.modelgo.com/v1",
    timeout=600.0,   # 出图耗时较长，实测单张 40-60 秒
)

resp = client.images.generate(
    model="qwen-image-3.0-pro",
    prompt="一只毛茸茸的橘猫坐在阳光下的窗台上，胶片质感",
    size="1024x1024",
    n=1,
    extra_body={"prompt_extend": True},   # 扩展字段走 extra_body
)
print(resp.data[0].url)

image / negative_prompt / seed / prompt_extend / prompt_extend_mode / enable_thinking / watermark 不是 OpenAI 官方参数，用 OpenAI SDK 时通过 extra_body 传入；直接发 HTTP 请求时放在请求体顶层即可。

2. 百炼原生通道

POST https://api.modelgo.com/api/v1/services/aigc/multimodal-generation/generation

请求与响应两头都是百炼原样的形状，网关不做翻译。

curl https://api.modelgo.com/api/v1/services/aigc/multimodal-generation/generation \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0-pro",
    "input": {
      "messages": [
        {
          "role": "user",
          "content": [
            {"image": "https://example-cdn.com/portrait.png"},
            {"text": "把服装换成香槟色真丝衬衫"}
          ]
        }
      ]
    },
    "parameters": {"size": "1024*1024", "n": 1, "prompt_extend": true}
  }'

响应

{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [{"image": "https://dashscope-result-sz.oss-cn-shenzhen.aliyuncs.com/xxx.png?Expires=xxx"}]
        }
      }
    ]
  },
  "usage": {
    "output_width": 1024, "output_height": 1024,
    "input_image_count": 1, "input_image_type": "qima_input_1k",
    "output_image_count": 1, "output_image_type": "qima_output_1k"
  },
  "request_id": "571ae02f-5c9d-436c-83c2-f221e6df0xxx"
}

这条通道的约束

• input.messages 有且只有一个对象，role 必须是 user（仅支持单轮对话）。
• content 里有且只有一个 {"text": ...}，不传或传多个都会 400。
• {"image": ...} 0–3 个：0 个是文生图，1–3 个是图生图。
• 生成参数放在 parameters 下（不是顶层）：size / n / seed / negative_prompt / prompt_extend / prompt_extend_mode / enable_thinking / watermark。
• 使用百炼官方 SDK（dashscope）时，把 dashscope.base_http_api_url 指向 https://api.modelgo.com/api/v1、api_key 换成 ModelGo API Key 即可。

3. 参数说明

参数校验在调用前完成

下列请求在创建时就被拒（HTTP 400），不会打到上游、不产生费用：

• n 不是 1–6 的整数，或写成了字符串 / 小数；
• size 的总像素不在 512×512 – 2048×2048 之间，或宽高比超出 1:8 – 8:1；
• size 用了另一条通道的分隔符（错误信息会点名该用 x 还是 *）；
• image 为 null、空数组，或超过 3 张；
• prompt_extend_mode: "agent" 与 image 同时出现（APE 仅支持文生图）；
• seed 超出 0 – 2147483647；
• 原生通道上 messages 不是恰好一个、或 content 里的 text 不是恰好一个。

参考图的要求

• 格式：JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF。
• 建议宽高均在 384 – 2048 像素之间，单张不超过 10 MB。
• 支持公网 URL（HTTP / HTTPS）或 Base64（data:{MIME_type};base64,{base64_data}）。
• 公网 URL 必须是上游能直接 GET 到的直链：无鉴权、无跳转、不依赖 Referer / Cookie。部分站点对非浏览器抓取返回 403，会导致请求失败。

4. 计费口径

按张计费，不按 token。 输入（参考图）与输出（生成图）分别计价，各自再分 1k / 2k 两档：

档位按「输出」像素面积判定：面积 ≤ 2,250,000（即 1500×1500）为 1k，更大为 2k。输入图的档位同样按输出面积判定，不是按参考图自己的尺寸 —— 这是上游的口径。响应 usage 里的 output_image_type / input_image_type 就是本次实际命中的档位。

计费金额 = 输出张数 × 该档输出单价 + 输入张数 × 输入单价。几个实测例子（国内生产，2026-09-11）：

文生图不产生输入费用：没有参考图时 input_image_count 为 0，只结算输出张数。

5. 完整示例（Python，百炼官方 SDK）

import os
import dashscope
from dashscope import MultiModalConversation

dashscope.base_http_api_url = "https://api.modelgo.com/api/v1"

response = MultiModalConversation.call(
    api_key=os.environ["MODELGO_API_KEY"],
    model="qwen-image-3.0-pro",
    messages=[{
        "role": "user",
        "content": [
            {"image": "https://example-cdn.com/portrait.png"},
            {"text": "把服装换成香槟色真丝衬衫，背景换成现代简约咖啡店"},
        ],
    }],
    prompt_extend=True,
)

if response.status_code == 200:
    print(response.output.choices[0].message.content[0]["image"])
else:
    print(f"Error: {response.code} - {response.message}")