图片生成调用文档

# 图片生成调用文档

图片生成接口根据文本描述生成图片，支持 GPT Image 和 Qwen Image 模型。不同模型的请求结构及结果获取方式不同，请按所用模型选择下文对应的调用示例。

需要基于已有图片修改内容时，请使用 [图片编辑接口](图片编辑调用文档.md)。

## 接口信息

| 项目 | 内容 |
| --- | --- |
| 基础地址 | `https://aiproxy-api.cloudcare.cn` |
| 请求方法 | `POST` |
| 接口路径 | `/v1/images/generations` |
| 鉴权 | `Authorization: Bearer <平台 API Key>` |
| 请求类型 | `Content-Type: application/json` |
| 响应类型 | `application/json` |
| 调用模式 | GPT Image 同步返回；Qwen Image 异步提交并查询结果 |

调用示例使用环境变量 `AIPROXY_API_KEY` 传递平台 API Key。请将 `YOUR_API_KEY` 替换为实际密钥。

```bash
export AIPROXY_API_KEY='YOUR_API_KEY'
```

## 模型与调用方式

| 模型系列 | 请求中的提示词位置 | 尺寸示例 | 结果获取方式 |
| --- | --- | --- | --- |
| GPT Image 2 / 2.5 | 顶层 `prompt` | 顶层 `size: "1024x1024"` | 响应 `data[].b64_json`，解码保存 |
| Qwen Image | `input.messages[].content[].text` | `parameters.size: "1024*1024"` | 提交后使用 `output.task_id` 查询，成功后下载图片 |

两种方式均使用 `/v1/images/generations` 和平台 API Key。参数位置与尺寸分隔符应按对应示例填写。

## GPT Image

请求头 `X-EEProxy-Async: false` 用于指定同步返回。请求完成后，可直接从响应中读取图片结果。

### 可用模型

| 模型名称 | 说明 |
| --- | --- |
| `gpt-image-2` | GPT Image 2 模型，支持图片生成和编辑 |
| `gpt-image-2.5-flare` | GPT Image 2.5 Flare 模型，支持图片生成和编辑 |
| `gpt-image-2.5-sunburst` | GPT Image 2.5 Sunburst 模型，支持图片生成和编辑 |

请使用当前 API Key 已开通的模型。切换模型时替换请求中的 `model` 字段，模型名称应完整填写。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型名称，取值见本节可用模型 |
| `prompt` | string | 是 | 图片描述文本 |
| `n` | integer | 否 | 生成图片数量，范围 1～10，默认 1 |
| `size` | string | 否 | 图片分辨率，采用 `宽x高` 格式，例如 `1024x1024`；具体限制见下文 |
| `quality` | string | 否 | `gpt-image-2` 支持 `low`、`medium`、`high`；`gpt-image-2.5-flare` 和 `gpt-image-2.5-sunburst` 支持 `auto`、`low`、`medium`、`high`、`xhigh`、`max` |
| `output_compression` | integer | 否 | 压缩级别，仅对 JPEG/WebP 有效 |
| `moderation` | string | 否 | 内容审核级别；`low` 放宽过滤，`auto`（默认）为标准过滤 |
| `background` | string | 否 | 背景类型；`transparent` 为透明背景，`opaque` 为不透明背景，`auto` 由模型自动决定 |

#### 图片分辨率

`size` 支持自定义分辨率，需同时满足以下条件：

- 宽和高均为 16 像素的倍数。
- 长边不超过 3,840 像素（4K）。
- 长边与短边之比不超过 3:1。
- 总像素数（宽 × 高）在 655,360～8,294,400 之间。

总像素数超过 3,686,400（`2560x1440`）属于实验性功能，可能不稳定。

| 常用尺寸 | 说明 |
| --- | --- |
| `1024x1024` | 正方形 |
| `1536x1024` | 横屏 HD |
| `1024x1536` | 竖屏 HD |
| `2560x1440` | QHD，推荐上限 |

### 请求示例

```bash
curl --request POST 'https://aiproxy-api.cloudcare.cn/v1/images/generations' \
  --header "Authorization: Bearer ${AIPROXY_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'X-EEProxy-Async: false' \
  --data-raw '{
    "model": "gpt-image-2",
    "prompt": "一只坐在窗边看雨的橘猫，电影感光影，细节丰富",
    "n": 1,
    "size": "1024x1024",
    "quality": "low"
  }' \
  --output generation.json
```

使用其他模型时，将 `model` 替换为 `gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst`。成功响应保存到 `generation.json`，解码方法见下文。

### 响应示例

以下为响应结构示例，Base64 内容已缩略，用量数值仅供参考。

```json
{
  "created": 1778487970,
  "background": "opaque",
  "data": [
    {
      "b64_json": "iVBORw0KG...tAAAAAElFTkSuQmCC"
    }
  ],
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "usage": {
    "input_tokens": 9,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 9
    },
    "output_tokens": 196,
    "total_tokens": 205
  },
  "taskId": "tsk-xxx"
}
```

#### 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `created` | integer | 响应创建时间，Unix 时间戳，单位为秒 |
| `background` | string | 背景类型，示例为 `opaque` |
| `data` | array | 生成的图片列表 |
| `data[].b64_json` | string | 图片文件的 Base64 编码，解码后得到二进制图片 |
| `output_format` | string | 输出图片格式，示例为 `png` |
| `quality` | string | 本次输出的质量 |
| `size` | string | 本次输出的图片尺寸 |
| `usage.input_tokens` | integer | 输入 Token 总量 |
| `usage.input_tokens_details.text_tokens` | integer | 输入文本 Token 数 |
| `usage.input_tokens_details.image_tokens` | integer | 输入图片 Token 数 |
| `usage.output_tokens` | integer | 输出 Token 数 |
| `usage.total_tokens` | integer | 总 Token 数 |
| `taskId` | string | 可选，用于问题排查的请求标识 |

图片结果直接位于 `data` 中，无需轮询。`taskId` 仅用于问题排查，不用于 `/v1/tasks/{task_id}` 查询。

### 保存图片

执行成功后，使用 Python 将 `generation.json` 中的图片解码保存：

```bash
python3 - <<'PY'
import base64
import json
from pathlib import Path

result = json.loads(Path('generation.json').read_text())
for index, item in enumerate(result['data'], start=1):
    path = Path(f'generated_{index}.png')
    path.write_bytes(base64.b64decode(item['b64_json'], validate=True))
    print(path)
PY
```

此示例对应 `output_format=png`；其他格式应使用相应的文件扩展名。缩略的响应示例不能用于解码，请使用真实接口返回的完整数据。

## Qwen Image

生成流程分为提交任务、查询状态和下载结果三步。以下示例使用 `qwen-image-3.0-pro`。

### 可用模型

| 模型名称 | 说明 |
| --- | --- |
| `qwen-image-3.0-pro` | 3.0 Pro 模型，支持图片生成和编辑 |
| `qwen-image-3.0` | 3.0 标准模型，兼顾质量与速度，支持图片生成和编辑 |
| `qwen-image-2.1-pro` | 2.1 Pro 模型，支持图片生成和编辑，可根据提示词生成透明背景图片 |
| `qwen-image-2.1-turbo` | 2.1 Turbo 模型，支持图片生成和编辑，可根据提示词生成透明背景图片 |

请使用当前 API Key 已开通的模型。切换模型时替换请求中的 `model` 字段，模型名称应完整填写。

### 请求参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型名称，取值见本节可用模型 |
| `input.messages` | array | 是 | 仅一条消息 |
| `input.messages[].role` | string | 是 | 固定为 `user` |
| `input.messages[].content` | array | 是 | 文生图仅放一个 `text` 对象 |
| `input.messages[].content[].text` | string | 是 | 图片描述，支持中英文，建议不超过 4500 Token |
| `parameters` | object | 否 | 生成选项 |
| `parameters.n` | integer | 否 | 生成图片数量，范围 1～6，默认 1；请传整数 |
| `parameters.size` | string | 否 | `宽*高`，例如 `1024*1024`；省略时自动选择尺寸 |
| `parameters.prompt_extend` | boolean | 否 | 是否优化提示词，默认 `true` |
| `parameters.prompt_extend_mode` | string | 否 | 提示词优化方式，默认 `direct`；可选 `direct`、`agent` |
| `parameters.enable_thinking` | boolean | 否 | 是否开启思考，默认 `true`；仅在 `prompt_extend=true` 时生效，开启后可能增加耗时 |
| `parameters.watermark` | boolean | 否 | 是否添加水印，默认 `false` |
| `parameters.seed` | integer | 否 | 随机种子，范围 0～2147483647 |
| `parameters.negative_prompt` | string | 否 | 不希望出现的内容，仅 Qwen Image 3.0 系列支持 |

输出像素面积范围为 512×512 至 2048×2048，宽高比范围为 1:8 至 8:1。例如 `1024*1024` 的像素面积为 1,048,576，宽高比为 1:1。

`direct` 为直接优化提示词，`agent` 为更精细的提示词优化，仅用于文生图。

### 请求示例

提交生成任务：

```bash
curl --request POST 'https://aiproxy-api.cloudcare.cn/v1/images/generations' \
  --header "Authorization: Bearer ${AIPROXY_API_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'X-EEProxy-Async: true' \
  --data-raw '{
    "model": "qwen-image-3.0-pro",
    "input": {
      "messages": [{
        "role": "user",
        "content": [{"text": "一只橘猫在书店窗边打盹，午后暖光，水彩插画"}]
      }]
    },
    "parameters": {
      "size": "1024*1024",
      "n": 1,
      "prompt_extend": true,
      "watermark": false
    }
  }' \
  --output image_task.json
```

本例使用 `X-EEProxy-Async: true`；省略该请求头也使用异步模式。Qwen Image 请按此方式提交任务，无需添加其他异步请求头。

### 响应示例

任务提交成功后的响应：

```json
{
  "output": {
    "task_id": "proxy-task-example",
    "task_status": "PENDING"
  },
  "request_id": "request-example"
}
```

保存 `output.task_id`，后续查询使用同一 API Key。提交成功表示任务已受理，尚未生成最终图片。

#### 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `output.task_id` | string | 任务标识，查询时原样传入 |
| `output.task_status` | string | 当前任务状态 |
| `request_id` | string | 请求标识，可用于问题排查 |

### 查询任务结果

将 `TASK_ID` 替换为提交响应中的完整 `output.task_id`：

```bash
TASK_ID='proxy-task-example'
curl --request GET "https://aiproxy-api.cloudcare.cn/v1/tasks/${TASK_ID}" \
  --header "Authorization: Bearer ${AIPROXY_API_KEY}" \
  --output image_result.json
```

| `output.task_status` | 说明 | 后续操作 |
| --- | --- | --- |
| `PENDING` | 排队中 | 等待后继续查询 |
| `RUNNING` | 处理中 | 等待后继续查询 |
| `SUCCEEDED` | 成功 | 读取图片地址 |
| `FAILED` | 失败 | 读取错误信息，停止查询 |
| `CANCELED` | 已取消 | 停止查询 |
| `UNKNOWN` | 状态未知或任务不可查询 | 停止查询，联系技术支持 |

可从 2 秒间隔开始查询，逐步增加间隔。查询返回 HTTP 200 后，仍需检查任务状态；等待时应继续查询已有任务，避免重复提交生成请求。

### 任务成功响应

以下为成功响应示例，地址与用量仅作结构演示：

```json
{
  "output": {
    "task_id": "proxy-task-example",
    "task_status": "SUCCEEDED",
    "choices": [{
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": [{"image": "https://example.com/generated.png"}]
      }
    }]
  },
  "usage": {
    "output_width": 1024,
    "output_height": 1024,
    "input_image_count": 0,
    "output_image_count": 1
  },
  "request_id": "request-example"
}
```

图片地址位于 `output.choices[].message.content[].image`。结果返回图片 URL，不能按 GPT Image 的 `b64_json` 解码。Qwen Image 3.0 的 `usage` 按图片数量和尺寸计量；2.1 系列可返回 `image_count`、`width`、`height`，这些字段均不是 Token 数。

#### 响应字段

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `output.choices` | array | 图片结果列表，可能包含多个选项 |
| `output.choices[].finish_reason` | string | 结束原因，正常结束为 `stop` |
| `output.choices[].message.role` | string | 固定为 `assistant` |
| `output.choices[].message.content[].image` | string | 图片下载地址 |
| `usage.output_width`、`usage.output_height` | integer | Qwen Image 3.0 输出宽、高，单位为像素 |
| `usage.input_image_count` | integer | 输入图片数，文生图为 0 |
| `usage.output_image_count` | integer | 实际输出图片数 |
| `usage.input_image_type`、`usage.output_image_type` | string | 返回时表示图片用量档位 |
| `usage.image_count` | integer | Qwen Image 2.1 输出图片数 |
| `usage.width`、`usage.height` | integer | Qwen Image 2.1 输出宽、高，单位为像素 |

不同模型返回的用量字段不同，请按实际字段读取。图片数量以最终成功响应为准。

### 保存图片

结果图片链接有效期为 24 小时，应及时下载保存。将 `IMAGE_URL` 替换为结果中的完整地址，包括查询参数：

```bash
IMAGE_URL='替换为结果中的完整图片 URL'
curl --fail --location "$IMAGE_URL" --output qwen_generated.png
```

下载图片时无需携带平台 API Key。

### 任务失败

任务执行失败时，查询响应可能仍为 HTTP 200。检查 `output.task_status`，并读取实际返回的 `code`、`message` 或 `output.code`、`output.message`。排查时提供任务 ID、调用时间及错误信息。

### 自动查询示例

以下 Python 示例使用标准库读取前面保存的 `image_task.json`，等待任务结束并输出全部图片地址。运行前设置 `AIPROXY_API_KEY`：

```bash
python3 - <<'PYTHON'
import json
import os
import time
from pathlib import Path
from urllib.request import Request, urlopen

submitted = json.loads(Path('image_task.json').read_text())
task_id = submitted['output']['task_id']
headers = {'Authorization': 'Bearer ' + os.environ['AIPROXY_API_KEY']}
url = 'https://aiproxy-api.cloudcare.cn/v1/tasks/' + task_id
deadline = time.monotonic() + 600

while time.monotonic() < deadline:
    with urlopen(Request(url, headers=headers), timeout=30) as response:
        result = json.load(response)
    output = result['output']
    status = output['task_status']
    if status == 'SUCCEEDED':
        Path('image_result.json').write_text(json.dumps(result, ensure_ascii=False))
        for choice in output.get('choices', []):
            for item in choice['message'].get('content', []):
                if item.get('image'):
                    print(item['image'])
        break
    if status in ('FAILED', 'CANCELED', 'UNKNOWN'):
        raise RuntimeError(json.dumps(result, ensure_ascii=False))
    if status not in ('PENDING', 'RUNNING'):
        raise RuntimeError('Unexpected task status: ' + status)
    time.sleep(2)
else:
    raise TimeoutError('等待超时，可使用同一任务 ID 稍后继续查询')
PYTHON
```

查询超时不代表任务失败，可保留任务 ID 稍后继续查询。

## 错误处理

请求失败时，请检查 HTTP 状态码和响应中的 `error` 对象。以下为参数错误的响应结构示例：

```json
{
  "error": {
    "message": "model is required",
    "type": "ee_proxy_error",
    "code": "invalid_request"
  },
  "request_id": "request-example"
}
```

`error.message` 为错误说明，`error.code` 为错误标识；`request_id` 有值时返回。常见 HTTP 状态码及处理方式如下：

| HTTP 状态码 | 说明 | 处理方式 |
| --- | --- | --- |
| `400` | 请求参数不合法 | 检查必填字段、请求格式及参数取值 |
| `401` | 鉴权失败 | 检查是否携带有效的 API Key |
| `403` | 无权访问或额度受限 | 检查模型访问权限及可用额度 |
| `429` | 请求频率受限 | 降低请求频率，等待后重试 |
| `503` | 服务暂时无法完成请求 | 稍后重试；持续失败时联系技术支持 |

排查问题时，请提供调用时间、模型名称、HTTP 状态码、错误响应，以及响应头 `X-EE-Response-ID`。响应中如有 `taskId`，也可一并提供。