Qwen Image 3.0 图像生成 API 文档

来源：ModelVerse（astraflow.ucloud.cn）模型：qwen-image-3.0（标准版）、qwen-image-3.0-pro（Pro 版），均支持文生图（T2I）与图生图/图像编辑（I2I）

认证

通过请求头传入 API Key：


Authorization: Bearer <MODELVERSE_API_KEY>

API 端点：https://api.modelverse.cn

一、同步图像生成


POST /v1/images/generations

同步生成或编辑图像。prompt、image、images 至少提供一项：

仅提供 prompt → 文生图（T2I）
提供 image 或 images → 图生图/图像编辑（I2I），支持 1-3 张参考图

请求体参数

参数	类型	必填	默认值	说明
`model`	string	是	—	`qwen-image-3.0` 或 `qwen-image-3.0-pro`
`prompt`	string	条件必填	—	正向提示词，描述期望生成或编辑的图像内容、风格和构图。支持中英文，推荐不超过 4500 Token
`image`	string	条件必填	—	单张输入图像（URL 或 Base64 Data URL），见下方「输入图像规格」
`images`	string[]	条件必填	—	多张参考图（1-3 张），按数组顺序定义图像顺序
`size`	string	否	模型自动推荐	输出分辨率，格式 `宽高`（如 `10241024`）。总像素面积需在 `512512` ~ `20482048` 之间，宽高比 `1:8` ~ `8:1`
`n`	integer	否	`1`	输出图像数量，1-6 张
`seed`	integer	否	随机	随机数种子，`[0, 2147483647]`，固定种子可使结果相对稳定
`negative_prompt`	string	否	—	反向提示词，描述不希望出现的内容
`watermark`	boolean	否	`false`	是否添加水印
`prompt_extend`	boolean	否	`true`	是否开启提示词智能改写（建议开启）
`prompt_extend_mode`	string	否	`direct`	改写方式：`direct`（DPE，T2I/I2I 均支持）或 `agent`（APE，仅支持 T2I；I2I 传入将返回 400）
`enable_thinking`	boolean	否	`true`	思考模式，提升出图质量但增加耗时。仅 `prompt_extend=true` 时生效；适用于 Direct T2I、Direct I2I、Agent T2I

输入图像规格

支持公网 URL（HTTP/HTTPS）或 Base64 Data URL（data:{MIME_type};base64,{base64_data}）
格式：JPG、JPEG、PNG、BMP、TIFF、WEBP、GIF
建议宽高均在 384 ~ 2048 像素之间，单张不超过 10MB

请求示例

文生图（T2I）：


{
  "model": "qwen-image-3.0-pro",
  "prompt": "一只赛博朋克风格的猫，霓虹灯光，电影感构图",
  "size": "1024*1024",
  "n": 1,
  "seed": 123456,
  "watermark": false
}

图生图/图像编辑（I2I）：


{
  "model": "qwen-image-3.0",
  "prompt": "将参考图片转换为中国水墨画风格，保留主体与构图",
  "image": "https://example.com/reference.png",
  "size": "1536*1024",
  "prompt_extend": true,
  "watermark": false
}

响应（200）

生成图片 URL 有效期为 24 小时，格式为 PNG。


{
  "created": 1775558400,
  "data": [
    { "url": "https://example.com/generated-image-1.png" }
  ]
}

字段	类型	说明
`created`	integer	请求创建的 Unix 时间戳（秒）
`data`	array	生成图像 URL 列表
`data[].url`	string	图像下载 URL（PNG，24 小时有效）

错误响应（400 / default）


{
  "error": {
    "code": "InvalidParameter",
    "message": "prompt_extend_mode=agent is only supported for text-to-image (T2I)"
  },
  "request_id": "req_202604021530000001"
}

二、异步任务提交


POST /v1/tasks/submit

提交异步图像生成任务，成功后返回 task_id，用于后续状态查询。

input.prompt、input.images、input.img_url 至少提供一项：仅 prompt 为 T2I；提供 images 或 img_url 为 I2I（1-3 张参考图）。

请求体参数

参数	类型	必填	说明
`model`	string	是	`qwen-image-3.0` 或 `qwen-image-3.0-pro`
`input`	object	是	输入内容，见下表
`parameters`	object	否	生成参数，见下表

input 对象：

参数	类型	必填	说明
`prompt`	string	条件必填	正向提示词（同上）
`negative_prompt`	string	否	反向提示词
`images`	string[]	条件必填	多张参考图（1-3 张）
`img_url`	string	条件必填	单张输入图像

parameters 对象（含义与同步接口一致）：

参数	类型	默认值
`size`	string	模型自动推荐
`n`	integer	`1`（1-6）
`seed`	integer	随机
`watermark`	boolean	`false`
`prompt_extend`	boolean	`true`
`prompt_extend_mode`	string	`direct`（`direct` / `agent`）
`enable_thinking`	boolean	`true`

请求示例

文生图任务：


{
  "model": "qwen-image-3.0-pro",
  "input": {
    "prompt": "一只赛博朋克风格的猫，霓虹灯光，电影感构图"
  },
  "parameters": {
    "size": "1024*1024",
    "prompt_extend": true,
    "watermark": false
  }
}

图生图/图像编辑任务：


{
  "model": "qwen-image-3.0",
  "input": {
    "prompt": "将参考图片转换为中国水墨画风格，保留主体与构图",
    "images": [
      "https://example.com/reference-1.png",
      "https://example.com/reference-2.png"
    ]
  },
  "parameters": {
    "size": "1536*1024",
    "prompt_extend": true,
    "prompt_extend_mode": "direct",
    "seed": 123456
  }
}

响应（200）


{
  "output": {
    "task_id": "3c7d6b6c-7cdb-4f37-bf41-7f2b0f1a9f0d"
  },
  "request_id": "req_202604021530000001"
}

三、异步任务状态查询


GET /v1/tasks/status?task_id=<task_id>

查询异步图像任务的执行状态、结果 URL 与用量信息。

查询参数

参数	类型	必填	说明
`task_id`	string	是	由 `/v1/tasks/submit` 返回的任务标识

响应（200）

成功任务：


{
  "output": {
    "task_id": "3c7d6b6c-7cdb-4f37-bf41-7f2b0f1a9f0d",
    "task_status": "Success",
    "urls": [
      "https://example.com/generated-image-1.png"
    ],
    "submit_time": 1775115000,
    "finish_time": 1775115038
  },
  "usage": {
    "image_count": 1,
    "input_image_count": 0,
    "pixel_count": 1048576
  },
  "request_id": ""
}

失败任务：


{
  "output": {
    "task_id": "3c7d6b6c-7cdb-4f37-bf41-7f2b0f1a9f0d",
    "task_status": "Failure",
    "submit_time": 1775115000,
    "finish_time": 1775115012,
    "error_message": "code=InvalidParameter, message=invalid image url"
  },
  "request_id": ""
}

响应字段

output 对象：

字段	类型	说明
`task_id`	string	异步任务标识
`task_status`	string	任务状态：`Pending` / `Running` / `Success` / `Failure` / `Cancelled`
`urls`	string[]	生成图像结果 URL 列表（24 小时有效）
`submit_time`	integer	任务提交时间戳
`finish_time`	integer	任务完成时间戳
`error_message`	string	任务失败时的错误信息

usage 对象：

字段	类型	说明
`image_count`	integer	实际生成的输出图片数量
`input_image_count`	integer	输入图片数量（T2I 为 0）
`pixel_count`	integer	输出图片像素值（宽×高），用于按像素分档计费

通用错误响应结构

字段	类型	说明
`error.code`	string	错误码，如 `InvalidParameter`
`error.message`	string	错误信息，如 `invalid image url` / `invalid task_id`
`request_id`	string	可选的请求标识

注意事项

生成图片 URL 有效期为 24 小时，请及时下载保存
prompt_extend_mode=agent 仅支持文生图；图生图场景传入会返回 400 错误
enable_thinking 仅在 prompt_extend=true 时生效，且 I2I + Agent 组合暂不支持
输出总像素面积限制：512*512 ~ 2048*2048；宽高比限制：1:8 ~ 8:1