跳至正文
EN
获取 API Key
☰
Alibaba · 模型接口

Qwen Image 2.1 API

Qwen Image 2.1 API 的模型能力、计价规格、请求参数和接入示例。使用 VezAPI 账号密钥统一接入。

文生图图生图

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 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。

打开完整文档 →

Qwen Image 2.1 API 价格

下方费率为参考估算，最终按实际优惠扣分 1:1 结算。按标准充值包换算，1,000 积分约为 10 美元，大额充值包可降低每积分实际单价。

规格积分计价单位美元参考
Qwen-Image-2.1, image to image, 2K8每张图片$0.08
Qwen-Image-2.1, image to image, 1K4每张图片$0.04
Qwen-Image-2.1, text to image, 2K8每张图片$0.08
Qwen-Image-2.1, text to image, 1K4每张图片$0.04