> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Qwen Image 3.0 图像生成

>  - 异步处理模式，返回任务 ID 用于后续查询
- 支持文生图、图生图（1-3 张参考图编辑）
- 支持 1K / 2K 分辨率，单次最多 6 张
- 提供标准版与 Pro 版（密集排版、图文更强） 

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.apimart.ai/v1/images/generations \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "qwen-image-3.0",
      "prompt": "一张咖啡馆海报，主标题写着「秋日限定」，暖色调，排版精致",
      "size": "16:9",
      "resolution": "1K"
    }'
  ```

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

  url = "https://api.apimart.ai/v1/images/generations"

  payload = {
      "model": "qwen-image-3.0",
      "prompt": "一张咖啡馆海报，主标题写着「秋日限定」，暖色调，排版精致",
      "size": "16:9",
      "resolution": "1K",
  }

  headers = {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
  }

  response = requests.post(url, json=payload, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://api.apimart.ai/v1/images/generations";

  const payload = {
    model: "qwen-image-3.0",
    prompt: "一张咖啡馆海报，主标题写着「秋日限定」，暖色调，排版精致",
    size: "16:9",
    resolution: "1K",
  };

  const headers = {
    Authorization: "Bearer <token>",
    "Content-Type": "application/json",
  };

  fetch(url, {
    method: "POST",
    headers: headers,
    body: JSON.stringify(payload),
  })
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "code": 200,
    "data": [
      {
        "status": "submitted",
        "task_id": "task_01JGXYZ1234567890ABCDEF"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "code": 400,
      "message": "请求参数无效",
      "type": "invalid_request_error"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "code": 401,
      "message": "身份验证失败，请检查您的API密钥",
      "type": "authentication_error"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "code": 402,
      "message": "账户余额不足，请充值后再试",
      "type": "payment_required"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "code": 429,
      "message": "请求过于频繁，请稍后再试",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseExample>

## 支持的模型

| 模型名                  | 说明                       | 最大张数 | 分辨率     |
| -------------------- | ------------------------ | ---- | ------- |
| `qwen-image-3.0`     | 指令理解清晰，文字渲染稳定，常规出图更划算    | 6 张  | 1K / 2K |
| `qwen-image-3.0-pro` | 内容更丰实，适合报纸、分镜、菜单、试卷等密集排版 | 6 张  | 1K / 2K |

<Tip>
  排版密集、字多的场景优先用 `-pro`；常规出图用 `qwen-image-3.0`。提示词最长约 **4.5k token**。模型名与 2.0 系列不兼容互换。
</Tip>

## Authorizations

<ParamField header="Authorization" type="string" required>
  所有接口均需要使用 Bearer Token 进行认证

  获取 API Key：

  访问 [API Key 管理页面](https://apimart.ai/keys) 获取您的 API Key

  使用时在请求头中添加：

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  模型名称

  * `qwen-image-3.0` - 标准版
  * `qwen-image-3.0-pro` - Pro 版（密集图文 / 排版）
</ParamField>

<ParamField body="prompt" type="string" required>
  图像生成的文本描述，最长约 **4.5k token**
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图 URL 数组（图生图 / 图像编辑），**1-3 张**

  * 支持公网 `http(s)://` URL，或 `data:image/png;base64,...`（base64 会先转存）
  * 格式：JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF
  * 单张 ≤ 10MB，宽高建议 384-2048 像素
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  分辨率档位（与计费档位相关）

  * `1K`（默认，兼容小写）
  * `2K`

  也可跳过档位，在 `size` 中直接写像素（如 `1600x900`）。直接给像素时，面积 **> 225 万像素** 按 2K 档计费。
</ParamField>

<ParamField body="size" type="string" default="1:1">
  图像宽高比，或直接像素尺寸

  支持的宽高比：

  * `1:1`（默认）
  * `4:3` / `3:4`
  * `16:9` / `9:16`
  * `3:2` / `2:3`

  也兼容 `16x9` 写法，或像素如 `1024x1024`。自定义像素时，**宽与高各自**须在 **512 \~ 2048**，宽高比 1:8 \~ 8:1。

  不传 `size` 也不传 `resolution` 时固定出 **1024×1024**。
</ParamField>

<ParamField body="n" type="integer" default="1">
  出图张数，**1-6**。超过 6 会自动截断为 6。
</ParamField>

<ParamField body="negative_prompt" type="string">
  反向提示词，描述不希望出现的内容
</ParamField>

<ParamField body="prompt_extend" type="boolean" default="false">
  提示词智能改写

  默认关闭，以保证结果可预测。需要智能改写时设为 `true`。
</ParamField>

<ParamField body="prompt_extend_mode" type="string">
  改写方式（仅 3.0 系列，且需 `prompt_extend: true`）

  * `direct` - 文生图 / 图生图均可
  * `agent` - **仅文生图**，改写更激进

  取值非法时忽略该字段。
</ParamField>

## 尺寸对照表

通过 `resolution`（档位）+ `size`（比例）组合控制输出尺寸：

| 分辨率    | 1:1       | 4:3       | 3:4       | 16:9      | 9:16      | 3:2       | 2:3       |
| ------ | --------- | --------- | --------- | --------- | --------- | --------- | --------- |
| **1K** | 1024×1024 | 1152×864  | 864×1152  | 1280×720  | 720×1280  | 1248×832  | 832×1248  |
| **2K** | 2048×2048 | 2048×1536 | 1536×2048 | 2048×1152 | 1152×2048 | 2048×1360 | 1360×2048 |

## 使用场景示例

### 文生图（多张）

```json theme={null}
{
  "model": "qwen-image-3.0",
  "prompt": "扁平插画风格的城市天际线，黄昏，暖橙色调",
  "size": "16:9",
  "resolution": "1K",
  "n": 4
}
```

### 文生图（密集排版，开改写）

```json theme={null}
{
  "model": "qwen-image-3.0-pro",
  "prompt": "一份西餐厅菜单，分前菜/主菜/甜品三栏，每栏 5 道菜带价格，衬线字体，米色底",
  "size": "3:4",
  "resolution": "2K",
  "prompt_extend": true,
  "prompt_extend_mode": "agent"
}
```

### 图生图（图像编辑）

```json theme={null}
{
  "model": "qwen-image-3.0-pro",
  "prompt": "把画面里的招牌文字改成「营业中」，其余保持不变",
  "image_urls": ["https://example.com/shop.jpg"],
  "size": "1:1"
}
```

### 带反向提示词

```json theme={null}
{
  "model": "qwen-image-3.0",
  "prompt": "写实风格的山间小屋，清晨薄雾",
  "negative_prompt": "文字, 水印, 人物, 低分辨率",
  "size": "3:2"
}
```

## 限制

| 项     | 限制                                         |
| ----- | ------------------------------------------ |
| 提示词   | ≤ 4.5k token                               |
| 输出尺寸  | 自定义像素时宽、高各自 512 \~ 2048；宽高比 1:8 \~ 8:1     |
| 出图张数  | 1-6（超出自动截断）                                |
| 参考图数量 | 1-3 张                                      |
| 参考图格式 | JPG / JPEG / PNG / BMP / TIFF / WEBP / GIF |
| 参考图大小 | ≤ 10MB，宽高建议 384-2048 像素                    |

## Response

<ResponseField name="code" type="integer">
  响应状态码，成功时为 200
</ResponseField>

<ResponseField name="data" type="array">
  返回数据数组

  <Expandable title="属性">
    <ResponseField name="status" type="string">
      任务状态，初始提交时为 `submitted`
    </ResponseField>

    <ResponseField name="task_id" type="string">
      任务唯一标识符，用于查询结果
    </ResponseField>
  </Expandable>
</ResponseField>

## 与 2.0 的差异

|                      | 2.0 系列  | 3.0 系列                   |
| -------------------- | ------- | ------------------------ |
| 提示词长度                | 较短      | 约 4.5k token             |
| `prompt_extend_mode` | 不支持     | `direct` / `agent`       |
| 分辨率                  | 1K / 2K | 1K / 2K（Pro 的 2K 档位价格更高） |
| 参考图                  | 支持      | 1-3 张                    |

## 注意事项

1. **异步处理**：提交后返回 `task_id`，使用 [获取任务状态](/cn/api-reference/tasks/status) 轮询；建议每 **3\~5 秒**一次，超时约 **3 分钟**（2K + 多张更慢）。
2. **图片存储**：生成图片已镜像到平台 CDN，返回地址长期可用。
3. **计费**：按实际出图张数 × 分辨率档位计费；档位按**实际像素面积**判定（> 225 万像素为 2K）。`qwen-image-3.0` 的 1K/2K 同价；`-pro` 的 2K 为 1K 的两倍。任务失败全额退款；参考图不额外收费。
4. **常见错误**：自定义 `size` 宽或高不在 512–2048、比例越界、`agent` 用在图生图、参考图不可访问或超 10MB 等返回 400；限流 429。

<Note>
  **查询任务结果**

  使用 [获取任务状态](/cn/api-reference/tasks/status) 接口查询进度与 `result.images`。
</Note>