Qwen-Image-3.0 图片生成与编辑接口

本文档描述通过魔芋AI网关调用千问图像生成模型（qwen-image-3.0、qwen-image-3.0-pro）的 HTTP API、参数、限制。

一、可用模型

模型	说明
`qwen-image-3.0`	标准版，指令理解与文字渲染均衡，批量产出成本更优
`qwen-image-3.0-pro`	专业版，密集信息排版、小字渲染与细节质感更强

两个模型能力一致，同一模型同时支持文生图（T2I）与图生图 / 图像编辑（I2I），区别只在输出质量与价格。

二、基础说明

Base URL：https://www.moyu.cn（下文以 BASE_URL 指代）

认证：请求头 Authorization: Bearer sk-xxxx，令牌在控制台「令牌管理」创建

令牌分组：令牌所在分组必须包含所调用的图片模型，否则返回 401 / 403

请求格式：

文生图：Content-Type: application/json

图生图 / 图像编辑：Content-Type: multipart/form-data

不要在前端浏览器代码里直接写 sk- 令牌，应由自己的后端代为调用。

三、调用方式总览

场景	方法	路径	请求格式	参考图
文生图 T2I	POST	`/v1/images/generations`	JSON	不传
图生图 I2I	POST	`/v1/images/edits`	multipart/form-data	`image[]` 上传文件，1~3 张

四、文生图（`/v1/images/generations`）

请求参数

参数	类型	必填	默认	说明
`model`	string	是	-	`qwen-image-3.0` 或 `qwen-image-3.0-pro`
`prompt`	string	是	-	正向提示词，支持中文、英文等多国语言
`size`	string	否	上游自选	输出尺寸，形如 `宽高`（如 `10241024`）。*推荐统一用 `` 分隔*，用 `x` 会由网关转成 ``
`n`	number	否	1	生成张数。平台侧 1~3 张均有成功记录，更高值以上游为准；费用按实际输出张数计算
`watermark`	bool	否	false	是否添加水印
`negative_prompt`	string	否	-	反向提示词，描述不希望在画面中出现的内容
`prompt_extend`	bool	否	上游默认	是否开启提示词智能改写
`prompt_extend_mode`	string	否	`direct`	提示词改写方式：`direct`（更贴近原意）、`agent`（改写更精细、耗时更长）
`parameters`	object	否	-	原样透传给上游的参数对象，可整体覆盖 `size` / `n` / `watermark`

关于 parameters 的两点注意：

一旦传了 parameters，网关不再从顶层补 size / n / watermark——请把这些字段一并写进 parameters。negative_prompt / prompt_extend / prompt_extend_mode 不受影响，放顶层仍生效。

parameters.size 必须是 宽*高（* 分隔），不会做 x → * 的转换。

文生图响应

成功时返回 HTTP 200：

{
  "created": 1792410527,
  "data": [
    {
      "url": "https://dashscope-xxxx.oss-accelerate.aliyuncs.com/1d/xx/20261016/xxxx.png?Expires=...&OSSAccessKeyId=...&Signature=...",
      "b64_json": "",
      "revised_prompt": ""
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 0,
    "total_tokens": 1
  },
  "metadata": {
    "output": {
      "choices": [
        {
          "finish_reason": "stop",
          "message": {
            "role": "assistant",
            "content": [{ "image": "https://dashscope-xxxx.oss-accelerate.aliyuncs.com/..." }]
          }
        }
      ]
    },
    "usage": {
      "image_count": 1,
      "output_image_count": 1,
      "input_image_count": 0,
      "output_image_type": "qima_output_1k",
      "size": "1024*1024"
    },
    "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  }
}

字段	说明
`created`	生成时间戳（秒）
`data[].url`	结果图片地址，直接透传上游的临时链接（阿里百炼图片结果链接通常带签名、有效期约 24 小时，以实际上游为准）。请拉取后转存到自己的存储，不要长期依赖该地址
`data[].b64_json`	图片 base64。千问走的是上游多模态响应（`metadata.output.choices`），上游给的是 URL，所以实际观测到该字段恒为空字符串；仅当上游某次直接返回 base64 时才会填充。另外请求里传 `response_format: "b64_json"` 无效（网关未把该参数接入千问链路），需要 base64 请自行下载 `url` 后本地编码
`data[].revised_prompt`	与图片同批返回的文字（上游 `content[].text`），开启 `prompt_extend` 时通常是改写后的提示词
`usage`	占位字段：`prompt_tokens` 与 `total_tokens` 都等于请求里的 `n`、`completion_tokens` 为 0。实际计费不按 token，见第七节
`metadata`	上游原始响应体透传，含 `request_id` 与上游 usage 明细。*其中 `usage.` 子字段随上游版本不同，可能缺省**（`output_image_type` / `output_width` 等新版字段并非每次返回）；排障时提供 `request_id` 最快

cURL 示例

JavaScript 示例

五、图生图 / 图像编辑（`/v1/images/edits`）

请求参数（multipart/form-data）

参数	类型	必填	默认	说明
`model`	text	是	-	`qwen-image-3.0` 或 `qwen-image-3.0-pro`
`prompt`	text	是	-	编辑指令，如「把背景换成雪山日落」
`image[]`	file	是	-	参考图文件，1~3 张（不传报 `image is required`，4 张及以上由上游报错）。字段名也可用单数 `image`（单张时），两者都识别
`size`	text	否	上游自选	输出尺寸，形如 `10241024`（用 `x` 会由网关转成 ``）
`n`	text	否	1	生成张数
`watermark`	text	否	false	`"true"` / `"false"`
`quality`	text	否	-	可传，但千问系列不消费该值，不影响出图与计费

本接口不支持 negative_prompt / prompt_extend / prompt_extend_mode / parameters 等扩展参数——需要这些参数时请用文生图接口 /v1/images/generations。
只有图片 URL 时，请先下载成文件再以 image[] 上传（本接口只收文件）。

图生图响应

结构与文生图完全一致（data[].url + metadata），差别只在 metadata.usage.input_image_count 会返回实际参考图张数，output_image_type 等新字段可能缺省。

图生图 cURL 示例

图生图 JavaScript 示例

六、尺寸与计费档位对照

计费档位按输出图片的像素面积判定，与宽高比无关：

面积 ≤ 2,250,000（约 1500×1500）→ 1K 档

面积 > 2,250,000 → 2K 档

`size`	像素面积	档位
`512*512`	262,144	1K（面积下限）
`1024*1024`	1,048,576	1K
`1328*1328`	1,763,584	1K
`1472*1140`	1,678,080	1K
`1920*1080`	2,073,600	1K
`1080*1920`	2,073,600	1K
`1600*1600`	2,560,000	2K
`1664*1664`	2,768,896	2K
`2048*2048`	4,194,304	2K
`2560*2560`	6,553,600	2K（面积上限）

尺寸约束：输出 size 的像素面积必须落在 262,144（512×512）~ 6,553,600（2560×2560） 区间，超出直接报错；参考图单边须在 1 ~ 8000 像素、面积同样受 i2i 区间约束。注意 1920*1080 / 1080*1920 面积只有 207 万，属于 1K 档，不要按「1080P = 2K」估算成本。
quality、style 等 OpenAI 图像参数对千问系列无意义，传了也不会生效（体验中心对这两个模型不展示这些选项）。

七、限制与报错对照

以下为平台侧真实请求触发的上游限制与报错，排障时可直接对照：

触发条件	上游报错信息	处理方式
参考图传了 4 张以上	`Model 'qwen-image-3.0' supports 0~3 image content items. Got 4 image items.`	参考图最多 3 张
面积超出 512²~2560²	`Image area must be between 262144 (512x512) and 6553600 (2560x2560) pixels for t2i/i2i requests. Got area=...`	调整 `size`，参考图也要满足同区间
单张图片超过 10MB	`File size exceeds maximum allowed size of 10485760 bytes`	压缩图片后重传，单张 ≤ 10MB
base64 单项超过 20MB	`Exceeded limit on max bytes per data-uri item : 20971520`	压缩参考图
请求体超过 16MB	`Exceeded limit on max bytes to request body : 16777216`	减少参考图数量或压缩后再传
`size` 未用 `*` 分隔	`Expected format: '<width>*<height>'`	`parameters.size` 必须是 `1024*1024` 形式
图片分辨率超过 8000	`Error validating image, resolution must be at most 8000x8000` / `Reference image dimensions must be within 1..8000`	参考图单边 ≤ 8000
边长为 1（异常尺寸）	`image length and width do not meet model restrictions. [height:1 or width:1 must be larger than 10]`	检查 `size` 是否被误传
content 项里既没文字也没图片（或两者都有）	`Either 'text' or 'image' must be provided, but not both.`	上游要求 messages 的每个 content 项有且仅有 `text` 或 `image` 之一。常见触发是提示词为空：请传入非空 `prompt`
触发限流	`Requests rate limit exceeded, try again later.`	降低并发，指数退避后重试
内容审核拦截（提示词）	`Green net check failed for text (input): Input data may contain inappropriate content.`	调整提示词
内容审核拦截（输入图）	`Green net check rejected image (input)`	更换参考图
内容审核拦截（出图）	`Green net check rejected image (output)`	提示词 / 参考图可能触发安全策略，调整后重试
上游偶发不可用	`<503> InternalError.Algo: Service is temporarily unavailable.`	稍后重试

错误响应体统一为：

{ "error": { "message": "……", "type": "……", "code": "……" } }

八、完整示例（Python）

九、常见问题

问题	原因 / 处理
返回 200 但 `data[0].b64_json` 是空的	正常现象：千问链路默认返回 `data[0].url`，需要 base64 请自行下载该 URL 后编码
下载图片报 403 / 链接失效	上游结果链接是临时地址（通常数小时~24 小时有效），请拿到后立刻转存；失效后只能重新生成
传了 `image` 数组却像文生图一样忽略参考图	图生图必须走 multipart `/v1/images/edits` 上传 `image[]` 文件，JSON 请求里没有承载参考图的字段
图生图想传 `negative_prompt` / `prompt_extend_mode`	本接口的表单字段只有 model / prompt / image[] / size / n / watermark / quality；扩展参数请改用文生图接口 `/v1/images/generations`
传了 `parameters` 后 `size` / `n` 不生效	传 `parameters` 时这些字段必须写在 `parameters` 内部
提示 `Expected format: '<width>*<height>'`	`size` 改用 `` 分隔（如 `10241024`）
同样的 `size`，两次计费不同	档位按实际输出图片面积判定，且图生图会按参考图张数加收输入费
长宽比不受支持	宽高比由 `size` 决定，不做比例参数映射；请直接给目标宽高
请求很慢或超时	同步接口，生成耗时可超过 10 分钟；客户端超时设 300 秒以上

Qwen-Image-3.0 图片生成与编辑接口

一、可用模型#

二、基础说明#

三、调用方式总览#

四、文生图（/v1/images/generations）#

请求参数#

文生图响应#

cURL 示例#

JavaScript 示例#

五、图生图 / 图像编辑（/v1/images/edits）#

请求参数（multipart/form-data）#

图生图响应#

图生图 cURL 示例#

图生图 JavaScript 示例#

六、尺寸与计费档位对照#

七、限制与报错对照#

八、完整示例（Python）#

九、常见问题#