> ## Documentation Index
> Fetch the complete documentation index at: https://quwan-b8010aef.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 千问图片生成与编辑示例

> 通过统一图片 API 调用 Qwen Image 3.0、2.1 Pro，并查看参数与用量

# 千问图片生成与编辑

通过平台的图片 API（`https://api.tokenops.ai/v1`）调用千问模型。若从阿里云原生接口迁移，请将 `prompt_extend`、`prompt_extend_mode` 和 `enable_thinking` 分别写入 `optimize_prompt_options.enable`、`optimize_prompt_options.mode` 和 `optimize_prompt_options.enable_thinking`。

请求前通过 `GET /v1/models` 确认目标模型已在当前环境开放。本页给出平台的请求方式、模型限制和响应字段。

## Qwen Image 3.0 文生图

`qwen-image-3.0-pro` 与 `qwen-image-3.0` 使用相同的请求结构。示例开启 Agent 提示词增强和思考模式；`agent` 仅用于文生图。

```bash theme={null}
curl --request POST 'https://api.tokenops.ai/v1/images/generations' \
  --header "Authorization: Bearer $TOKENOPS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen-image-3.0-pro",
    "prompt": "一张雨后街角咖啡店的海报，招牌清晰写着「今日特调」，暖色灯光，写实摄影",
    "n": 2,
    "size": "1024x1024",
    "response_format": "url",
    "optimize_prompt_options": {
      "enable": true,
      "mode": "agent",
      "enable_thinking": true,
      "negative_prompt": "文字错乱、模糊"
    },
    "watermark": false
  }'
```

将 `model` 改为 `qwen-image-3.0` 即可调用标准版。`size` 按 `宽x高` 填写，例如 `1024x1024`；省略时由模型选择分辨率。

## Qwen Image 3.0 图片编辑

编辑请求使用 JSON。`image` 按顺序提供 1–3 张公网 URL 或 `data:image/...;base64,...` 图片；`mode` 使用 `direct`。请将示例 URL 换成可公开访问的图片。

```bash theme={null}
curl --request POST 'https://api.tokenops.ai/v1/images/edits' \
  --header "Authorization: Bearer $TOKENOPS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen-image-3.0",
    "prompt": "保留图一人物的面部特征，让她穿上图二的外套，置于干净的摄影棚背景",
    "image": [
      "https://example.com/person.png",
      "https://example.com/jacket.png"
    ],
    "n": 1,
    "optimize_prompt_options": {
      "enable": true,
      "mode": "direct",
      "enable_thinking": true
    }
  }'
```

编辑请求不能使用 `mode: "agent"`；平台也不支持 Qwen Image 3.0 的 `mask` 参数。`enable_thinking` 只有在 `enable` 为 `true` 时才生效。

## Qwen Image 2.1 Pro

`qwen-image-2.1-pro` 同时支持文生图和图片编辑，`n` 可取 1–6。图片编辑可传入 1–10 张参考图；其用量字段与 3.0 系列不同。

```bash 文生图 theme={null}
curl --request POST 'https://api.tokenops.ai/v1/images/generations' \
  --header "Authorization: Bearer $TOKENOPS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen-image-2.1-pro",
    "prompt": "白色背景上的玻璃茶杯，柔和自然光，产品摄影",
    "n": 2,
    "size": "1024x1024",
    "optimize_prompt_options": {
      "enable": true
    }
  }'
```

```bash 图片编辑 theme={null}
curl --request POST 'https://api.tokenops.ai/v1/images/edits' \
  --header "Authorization: Bearer $TOKENOPS_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "qwen-image-2.1-pro",
    "prompt": "保留主体，将背景改为日落时分的海边",
    "image": ["https://example.com/product.png"],
    "n": 1
  }'
```

## 参数矩阵

以下为**平台请求参数**。`model` 和非空 `prompt` 必填；提示词建议不超过 4500 Token。`size` 使用小写 `x` 分隔，`n` 不传时为 1。

| 参数 | Qwen Image 3.0 / 3.0 Pro | Qwen Image 2.1 Pro | 平台行为 |
| - | - | - | - |
| 接口 | 文生图：`/v1/images/generations`；编辑：`/v1/images/edits`，JSON | 同左 | 3.0 文生图接口也能通过 `image` 传参考图；2.1 编辑请使用 `/v1/images/edits` |
| `image` | 编辑输入 1–3 张 | 编辑输入 1–10 张 | JSON 中传 URL 或 Data URL；多图传字符串数组 |
| `n` | 1–6 | 1–6 | 3.0 超出范围会报错；2.1 超出 6 会按 6 处理，请传入有效范围 |
| `size` | 可省略；指定时总像素数为 512×512 至 2048×2048，宽高比为 1:8 至 8:1 | 同左 | 例如 `1024x1024`；要由模型选择尺寸，请省略该字段 |
| `optimize_prompt_options.enable` | 支持，默认 `true` | 支持，默认 `true` | 传入 `optimize_prompt_options` 时，请显式填写 `enable` |
| `optimize_prompt_options.mode` | `direct` 或 `agent`；编辑只允许 `direct` | 不支持 | 省略时默认为 `direct`；3.0 编辑使用 `agent` 会报错 |
| `optimize_prompt_options.enable_thinking` | 支持；仅在 `enable=true` 时生效 | 不支持 | 省略时模型默认为 `true`；开启会增加生成耗时 |
| `optimize_prompt_options.negative_prompt` | 支持 | 不支持 | 2.1 请求不要传入 |
| `seed` | 支持 | 支持 | 模型范围 0–2147483647；接口仅传递正整数，`0` 等同未指定 |
| `watermark` | 支持，默认 `false` | 支持，默认 `false` | 直接转发 |
| `response_format` | `url`、`b64_json` | `url`、`b64_json` | 通过 `data[].url` 或 `data[].b64_json` 获取图片 |
| `stream` / `mask` | 不支持流式输出；3.0 编辑不支持 `mask` | 不支持流式输出 | 使用非流式 JSON 请求 |

### 输入图片要求

* 格式：JPG、JPEG、PNG、BMP、TIFF、WEBP 或 GIF；GIF 仅处理第一帧。
* 尺寸：宽和高各为 1–8000 像素，长边与短边之比不超过 10:1；建议宽和高各为 384–2048 像素。
* 大小：每张不超过 10 MB。
* 传入方式：公网 HTTP/HTTPS URL，或完整的 Data URL，例如 `data:image/png;base64,...`。单张图可传字符串；多张图传字符串数组，顺序与提示词中的“图一”“图二”一致。不要传 `null` 或空数组。

旧模型 `qwen-image-plus`、`qwen-image` 的文生图输出固定为 1 张；`qwen-image-edit-plus` 和 `qwen-image-edit-plus-2025-10-30` 可输出 1–6 张，`qwen-image-edit` 固定为 1 张。旧模型的可用性请以当前环境的 `/v1/models` 为准。

## 读取响应与用量

平台返回 OpenAI 风格的 `data[]`，不返回阿里云原始的 `output.choices[]`。使用 URL 格式时读取 `data[].url`：

```python theme={null}
import os
import requests

response = requests.post(
    "https://api.tokenops.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['TOKENOPS_API_KEY']}"},
    json={
        "model": "qwen-image-3.0",
        "prompt": "一只橘猫坐在窗边，水彩画风格",
        "n": 1,
        "optimize_prompt_options": {"enable": True, "mode": "direct"},
    },
    timeout=600,
)
response.raise_for_status()
result = response.json()

for image in result["data"]:
    print(image["url"])
print(result.get("usage"))
```

3.0 系列的 `usage` 包含 `image_count`、`input_image_count`、`output_image_count`、`input_image_type`、`output_image_type`、`output_width` 和 `output_height`。`qwen-image-2.1-pro` 的公开 `usage.image_count` 为实际返回的图片数，不提供 3.0 的输入与输出档位字段。图片费用依据实际返回数量及对应模型的计费规则结算；不要根据请求中的 `n` 推算账单。

3.0 系列用量示意如下；文生图时 `input_image_count` 为 `0`，编辑时为实际输入的图片数：

```json theme={null}
{
  "data": [{"url": "https://example.com/result.png"}],
  "usage": {
    "image_count": 1,
    "input_image_count": 2,
    "output_image_count": 1,
    "input_image_type": "qima_input_1k",
    "output_image_type": "qima_output_1k",
    "output_width": 1024,
    "output_height": 1024
  }
}
```

输入与输出的 `1k`、`2k` 档位由输出图像的像素面积决定：不超过 2,250,000 像素为 `1k`，超过则为 `2k`。`image_count` 与 `output_image_count` 应等于实际返回的 `data` 图片数；如果 3.0 模型报告的输出数量与实际返回数量不一致，接口会返回错误，避免按错误数量计费。

输出图片为 PNG。收到 `data[].url` 后请及时下载或持久化；临时链接过期后将无法访问。

## 参考资料

* [阿里云百炼：千问图像生成与编辑 API 参考](https://help.aliyun.com/zh/model-studio/qwen-image-generation-and-editing-api-reference)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.