Qwen Image 2.1

POST https://api.beatapi.io/v1/images/tasks

通过文字或最多十张公开 HTTPS 参考图生成、编辑图片，支持 1K、2K 及透明 PNG、WebP。

支持的生成方式

请求规则： auto 沿用首张参考图比例，无图时为 1:1。enhance_prompt 无图默认 true、有图默认 false。透明背景须用 png 或 webp，不能用 jpeg。参考示例 URL 是占位地址，请替换为可访问的 HTTPS 图片。示例描述保存的公开合同，不是已完成的模型调用。

异步任务流程

创建任务后保存 data.id，每 5–10 秒调用 GET /v1/tasks/{task_id} 查询状态。status 为 succeeded 时读取 data.output.media，为 failed 时读取 data.error_code 和 data.error_message，随后按错误与重试策略处理。

使用本地文件

请先上传本地输入，再将返回的 data.url 填入请求。

鉴权

Authorization   string   必填

在 Authorization 请求头中以 Bearer 令牌发送服务端 API 密钥，可在控制台创建。

Authorization: Bearer <BEATAPI_API_KEY>

永久 API 密钥只能保存在可信服务端，不能写入浏览器、移动端、公开脚本、日志或截图。请求体必须使用 Content-Type: application/json。建议为每个逻辑创建请求设置唯一的 Idempotency-Key，只有完全相同的请求体才能安全复用原键。

请求体

字段名、类型和枚举值保留英文原样，用途和限制用中文说明。

aspect_ratio   enum<string>   选填

auto 沿用首张参考图比例；无图时输出 1:1。

取值与默认值: 可选值 auto、1:1、4:3、3:4、3:2、2:3、16:9、9:16、21:9、9:21；默认值 auto

background   enum<string>   选填

opaque 或 transparent；透明输出须选 PNG 或 WebP。

取值与默认值: 可选值 opaque、transparent；默认值 opaque

enhance_prompt   boolean   选填

渲染前改写提示词；无图默认 true，有图默认 false，没有无条件默认值。

images   string[]   选填

1–10 个公开 HTTPS 图片 URL；文生图省略此字段。

取值与默认值: 1–10 项

model   enum<string>   必填

必须使用 qwen-image-2.1。

取值与默认值: 可选值 qwen-image-2.1

output_format   enum<string>   选填

输出格式；透明背景使用 png 或 webp，jpeg 不保留 alpha。

取值与默认值: 可选值 png、webp、jpeg；默认值 png

prompt   string   必填

生成或参考编辑指令，长度为 1–5000 字符。

取值与默认值: 长度 1–5000 字符

resolution   enum<string>   选填

输出档位为 1K 或 2K；提示词不能代替档位设置。

取值与默认值: 可选值 1K、2K；默认值 1K

seed   integer   选填

可选的 0–2147483647 整数；不接受 -1，没有文档默认值。

取值与默认值: 取值范围 0–2147483647

请求示例

文生图

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A white porcelain crane above misty mountains, no text."
}'

透明 WebP

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "A single green glass perfume bottle, isolated on a transparent background, no text.",
  "resolution": "2K",
  "aspect_ratio": "1:1",
  "background": "transparent",
  "output_format": "webp",
  "enhance_prompt": true,
  "seed": 0
}'

参考图生成

curl --request POST \
  --url https://api.beatapi.io/v1/images/tasks \
  --header 'Authorization: Bearer <BEATAPI_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "qwen-image-2.1",
  "prompt": "Keep the product shape and label from the reference, place it on a pale stone counter under soft morning light.",
  "images": [
    "https://example.com/product.png"
  ],
  "resolution": "1K",
  "aspect_ratio": "auto",
  "background": "opaque",
  "output_format": "png",
  "enhance_prompt": false,
  "seed": 42
}'

响应

仅为合同响应示例，不是实际运行或生成结果。1K 示例金额来自本页保存价目，实际用量以任务返回为准。

{
  "data": {
    "id": "task_8K2qA",
    "object": "task",
    "task_kind": "image",
    "capability_id": "qwen-image-2.1",
    "capability_version": null,
    "media_type": "image",
    "model": "qwen-image-2.1",
    "status": "queued",
    "stage": "queued",
    "created_at": 1782210000,
    "updated_at": 1782210000,
    "completed_at": null,
    "output": null,
    "usage": {
      "credits_reserved": 0.03,
      "credits_charged": 0.03,
      "credits_settled": 0,
      "credits_refunded": 0
    },
    "request_id": "req_abc123",
    "error_code": null,
    "error_message": null
  }
}

下一步

保存接受响应中的 data.id，每 5–10 秒轮询 GET /v1/tasks/{task_id}。任务成功后从 data.output.media 读取托管结果。

错误