# Qwen Image

> Qwen Image 3.0、2.1、2.0 的 OpenAI Images 和百炼原生同步生图、编辑调用文档。

Canonical URL: https://docs.uniai.tv/models/image/qwen-image
Locale: zh-CN

支持 OpenAI Images 和百炼原生接口，均同步返回图片 URL，无需轮询任务。

## 模型

| 模型 ID | 参考图上限 |
| --- | --- |
| `qwen-image-3.0-pro` | 3 张 |
| `qwen-image-3.0` | 3 张 |
| `qwen-image-2.1-pro` | 10 张 |
| `qwen-image-2.1-turbo` | 10 张 |
| `qwen-image-2.0-pro` | 3 张 |
| `qwen-image-2.0` | 3 张 |

## 接口

服务地址为 `https://api.uniai.tv`，使用 `Authorization: Bearer $UNIAI_API_KEY` 认证。示例中的 Key 和参考图地址请替换为自己的值。

| 格式 | 方法 | 路径 |
| --- | --- | --- |
| OpenAI 生图 | POST | `/v1/images/generations` |
| OpenAI 编辑（JSON 或 multipart） | POST | `/v1/images/edits` |
| 百炼原生生图与编辑 | POST | `/api/v1/services/aigc/multimodal-generation/generation` |

## 参数

OpenAI JSON 将下列字段放在顶层。百炼原生格式中，`model` 放顶层，提示词和图片放在 `input.messages`，生成选项放在 `parameters`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 上述六个模型 ID 之一。 |
| `prompt` | string | 是 | 生图或编辑指令。原生格式使用 `input.messages[0].content` 中的一条 `text`。 |
| `image` | string 或 array | 编辑时必填 | 按顺序传入参考图 URL 或图片 data URL。原生格式每张图使用一条 `image` 内容项。 |
| `n` | integer | 否 | 输出图片数，1–6，默认 `1`。 |
| `size` | string | 否 | `WIDTHxHEIGHT`、`WIDTH*HEIGHT` 或 `auto`，范围见下方限制。 |
| `seed` | integer | 否 | 0–2147483647。 |
| `negative_prompt` | string | 否 | 仅 3.0 和 2.0 系列支持。 |
| `prompt_extend` | boolean | 否 | 是否扩写提示词。 |
| `prompt_extend_mode` | string | 否 | `direct` 或 `agent`，仅 3.0 和 2.1 支持；`agent` 仅用于文生图。 |
| `enable_thinking` | boolean | 否 | 仅 3.0 和 2.1 系列支持。 |
| `watermark` | boolean | 否 | 是否添加水印。 |
| `response_format` | string | 否 | 仅 OpenAI 格式使用，只支持 `url`。 |

OpenAI 还支持 `n` 的别名 `num_images`，以及参考图字段 `image_url`、`image_urls`、`images`。参考图字段选用一种；同时传入 `n` 和 `num_images` 时必须一致。生成选项也可放在 `extra_body`，与顶层重复时值必须一致。

## OpenAI Images {/* #openai-images */}

### 文生图

```bash
curl "https://api.uniai.tv/v1/images/generations" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0",
    "prompt": "A blue ceramic cup on a wooden table",
    "n": 1,
    "size": "1024x1024",
    "seed": 0,
    "prompt_extend": false,
    "enable_thinking": false,
    "watermark": false
  }'
```

### 使用参考图 URL 编辑

```bash
curl "https://api.uniai.tv/v1/images/edits" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-pro",
    "prompt": "Turn the cup blue and keep the rest unchanged",
    "image": ["https://images.example.com/reference.png"],
    "n": 1,
    "size": "1024x1024"
  }'
```

同一 JSON 请求也可发送至 `/v1/images/generations`，包含 `image` 时执行编辑。参考图数组顺序保持不变。

### 上传本地图片编辑

```bash
curl "https://api.uniai.tv/v1/images/edits" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -F "model=qwen-image-2.1-pro" \
  -F "prompt=Turn the cup blue and keep the rest unchanged" \
  -F "image[]=@reference.png" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "seed=0" \
  -F "enable_thinking=false"
```

多张参考图可重复添加 `-F "image[]=@another.png"`。表单中的整数使用数字字符串，布尔值使用 `true` / `false`；multipart 的 Content-Type 由 cURL 自动设置。

### 响应

生图和编辑返回相同结构，从 `data[].url` 获取图片地址。

```json
{
  "created": 1792627200,
  "data": [
    {
      "url": "https://images.example.com/result.png"
    }
  ]
}
```

## 百炼原生接口 {/* #bailian-native */}

只传一条 `user` 消息，其中必须包含一条 `text`。编辑时添加 `image` 内容项，文生图时省略图片。

### 文生图

```bash
curl "https://api.uniai.tv/api/v1/services/aigc/multimodal-generation/generation" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-3.0",
    "input": {
      "messages": [{
        "role": "user",
        "content": [{"text": "A blue ceramic cup on a wooden table"}]
      }]
    },
    "parameters": {
      "n": 1,
      "size": "1024*1024",
      "seed": 0,
      "prompt_extend": false,
      "enable_thinking": false,
      "watermark": false
    }
  }'
```

### 图片编辑

```bash
curl "https://api.uniai.tv/api/v1/services/aigc/multimodal-generation/generation" \
  -H "Authorization: Bearer $UNIAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen-image-2.1-pro",
    "input": {
      "messages": [{
        "role": "user",
        "content": [
          {"image": "https://images.example.com/reference.png"},
          {"text": "Turn the cup blue and keep the rest unchanged"}
        ]
      }]
    },
    "parameters": {"n": 1, "size": "1024*1024"}
  }'
```

### 响应

从 `output.choices[].message.content[].image` 获取图片地址。

```json
{
  "output": {
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": [
            {
              "image": "https://images.example.com/result.png"
            }
          ]
        }
      }
    ]
  },
  "request_id": "req_example"
}
```

## 限制

- 输出总像素为 262,144–4,194,304（512²–2048²），宽高比为 1:8–8:1。这是面积限制，不是单边最多 2048 像素；`3840x2160` 等标准 4K 尺寸超出范围。
- 参考图每张不超过 10 MB，数量上限见模型表。
- 输出格式为 PNG。2.1 系列需要透明背景时，在提示词中描述。
- 不支持流式、蒙版编辑或 Base64 输出；不要传 `quality`、`output_format`、`operation`。

请求可能耗时数十秒。超时后先检查请求记录，再决定是否重发。图片 URL 可能过期，请及时保存结果。

## 请求错误

HTTP 400 时检查必填字段、模型支持的选项、参考图数量和尺寸范围；HTTP 401 时检查 Bearer Key。`/v1/images/edits` 至少需要一张参考图。