Qwen Image 2.1 API 接入文档

使用 VezAPI 密钥接入 Qwen Image 2.1。下列操作共用同一个账号余额和鉴权方式。

服务地址： https://api.vezapi.com
请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key，查询同一笔提交时才复用。

Qwen 2.1 图生图

POST/api/v1/jobs/createTask

模型标识： qwen2-1/image-to-image

参数	类型	说明与限制
`model` 必填	`string`	用于生成的模型名称。该接口必须使用 `qwen2-1/image-to-image`。可选值：`"qwen2-1/image-to-image"` 默认：`"qwen2-1/image-to-image"`
`callBackUrl` 可选	`string`	任务完成后的回调地址。可选参数。填写后，任务无论成功还是失败，系统都会向该地址发起一次 POST 请求；不填则不发送回调通知。回调签名校验见 [Webhook 签名校验指南](/cn/common-api/webhook-verification)。
`input` 必填	`object`	图生图任务的输入参数。
`input.image_urls` 必填	`array`	参考图 URL 数组，1–10 张，必填。数组顺序即提示词里「第一张图 / 第二张图」的指代顺序。支持 JPEG、PNG、WebP，单张不超过 30MB、不超过 25MP，且每个 URL 都要能直接 GET 取到。图片地址无法获取时，任务以 failCode 400 失败。超过 10 张时请求会被拒绝。参考图越多，单张保留的细节越少，需要高保真时建议控制在 4 张以内。把多个人物或物品合成到同一画面时，建议使用 `3:2`、`16:9` 这类横幅比例。 `minItems: 1` `maxItems: 10`
`input.prompt` 必填	`string`	画面描述提示词，用于描述期望得到的结果。必填。支持任意语言，最长 5000 字符，超长时请求会被拒绝。传了 `mask_url` 时，用它描述掩码白色区域要生成或改成什么。 `minLength: 1` `maxLength: 5000`
`input.mask_url` 可选	`string`	局部编辑掩码图，传入后进入局部编辑模式。一张黑白图，白色 = 要修改的区域，黑色 = 保持不变，边界有几个像素的羽化过渡。必须与恰好 1 张 `image_urls` 同用，否则请求会被拒绝。掩码应与该参考图同宽高比，尺寸不同会按原图缩放。局部编辑时输出宽高比跟随原图，因此 `aspect_ratio` 与 `enhance_prompt` 都会被忽略。不能与 `background=transparent` 同用，否则请求会被拒绝。
`input.aspect_ratio` 可选	`string`	输出画面比例。默认 `auto`，即取第一张参考图的宽高比并吸附到最近的一档。实际输出像素还取决于 `resolution`。局部编辑模式下本参数被忽略。可选值：`"auto", "1:1", "4:3", "3:4", "3:2", "2:3", "16:9", "9:16", "21:9", "9:21"` 默认：`"auto"`
`input.resolution` 可选	`string`	输出分辨率档位。`1K` 更快；`2K` 像素量是前者的四倍，耗时明显更长，带参考图时最长约 3 分钟。只接受 `1K` 与 `2K`，传 `4K` 或其他值时请求会被拒绝。可选值：`"1K", "2K"` 默认：`"1K"`
`input.background` 可选	`string`	背景类型。transparent 输出带真实透明通道的 PNG 或 WebP,不能与 JPEG 同用。使用 transparent 时,提示词只描述主体;若提到背景、场景、台面等,结果可能不是透明背景。可选值：`"opaque", "transparent"` 默认：`"opaque"`
`input.output_format` 可选	`string`	输出图片格式。`png`（默认）与 `webp` 都带 alpha 通道，可以配合 `background: transparent` 使用；`jpeg` 没有 alpha 通道，不能与透明背景同时使用。可选值：`"png", "webp", "jpeg"` 默认：`"png"`
`input.enhance_prompt` 可选	`boolean`	出图前先把提示词改写成更完整的画面描述,能明显提升效果。默认开启(不传该参数也视为开启),传 false 可关闭。默认：`true`
`input.seed` 可选	`integer`	随机种子。不传则随机生成。传入相同种子并搭配相同的提示词与参数，在同一服务版本内可复现同一张图。
`input.nsfw_checker` 可选	`boolean`	默认 false。为 false 时不额外进行内容过滤，结果由模型直接返回。

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "qwen2-1/image-to-image",
  "input": {
    "image_urls": [
      "https://example.com/input.png",
      "https://example.com/input.png"
    ],
    "prompt": "Replace the backpack in the first image with the colour scheme from the second image, and leave everything else unchanged",
    "aspect_ratio": "auto",
    "resolution": "1K"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 可选	`integer`	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`data` 必填	`object`
`data.taskId` 必填	`string`	任务 ID，可结合「获取任务详情」接口查询任务状态
`msg` 可选	`string`	响应消息，请求失败时返回错误描述

Qwen 2.1 文生图

POST/api/v1/jobs/createTask

模型标识： qwen2-1/text-to-image

参数	类型	说明与限制
`model` 必填	`string`	用于生成的模型名称。该接口必须使用 `qwen2-1/text-to-image`。可选值：`"qwen2-1/text-to-image"` 默认：`"qwen2-1/text-to-image"`
`callBackUrl` 可选	`string`	任务完成后的回调地址。可选参数。填写后，任务无论成功还是失败，系统都会向该地址发起一次 POST 请求；不填则不发送回调通知。回调签名校验见 [Webhook 签名校验指南](/cn/common-api/webhook-verification)。
`input` 必填	`object`	图片生成任务的输入参数。
`input.prompt` 必填	`string`	画面描述提示词，用于描述想要生成的画面内容、风格与构图。必填。支持任意语言，最长 5000 字符，超长时请求会被拒绝。 `minLength: 1` `maxLength: 5000`
`input.aspect_ratio` 可选	`string`	输出画面比例，默认 `1:1`。实际输出像素还取决于 `resolution`。可选值：`"1:1", "4:3", "3:4", "3:2", "2:3", "16:9", "9:16", "21:9", "9:21"` 默认：`"1:1"`
`input.resolution` 可选	`string`	输出分辨率档位。`1K` 更快；`2K` 像素量是前者的四倍，耗时更长。只接受 `1K` 与 `2K`，传 `4K` 或其他值时请求会被拒绝。可选值：`"1K", "2K"` 默认：`"1K"`
`input.background` 可选	`string`	背景类型。transparent 输出带真实透明通道的 PNG 或 WebP,不能与 JPEG 同用。使用 transparent 时,提示词只描述主体;若提到背景、场景、台面等,结果可能不是透明背景。可选值：`"opaque", "transparent"` 默认：`"opaque"`
`input.output_format` 可选	`string`	输出图片格式。`png`（默认）与 `webp` 都带 alpha 通道，可以配合 `background: transparent` 使用；`jpeg` 没有 alpha 通道，不能与透明背景同时使用。可选值：`"png", "webp", "jpeg"` 默认：`"png"`
`input.enhance_prompt` 可选	`boolean`	出图前先把提示词改写成更完整的画面描述,能明显提升效果。默认开启(不传该参数也视为开启),传 false 可关闭。默认：`true`
`input.seed` 可选	`integer`	随机种子。不传则随机生成。传入相同种子并搭配相同的提示词与参数，在同一服务版本内可复现同一张图。
`input.nsfw_checker` 可选	`boolean`	默认 false。为 false 时不额外进行内容过滤，结果由模型直接返回。

请求示例

curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "qwen2-1/text-to-image",
  "input": {
    "prompt": "A corgi wearing a yellow rain hat sitting on stone steps after the rain, shallow depth of field",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }
}'

返回值与错误

HTTP 200

请求成功

参数	类型	说明与限制
`code` 必填	`integer`	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。可选值：`200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505`
`msg` 必填	`string`	响应消息，失败时的错误描述
`data` 必填	`object`
`data.taskId` 必填	`string`	可以使用任务 ID 与“获取任务详细信息”端点一起查询任务状态。

任务状态与回调

异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询，或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。

超时可能表示请求已经受理。请在控制台查看原请求，不要自动新建任务。回调可能重试并重复到达，请使用 X-VezAPI-Event-Id 去重。

文件、日志与计费

生成媒体通常随上游保留 14 天，上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源，不提供永久作品库。请求日志保留两个自然月。

调用前预留积分，最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。