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

# gpt-image-2

## 1. 概述

OpenAI 图片生成模型（gpt-image-2）支持两种生成模式：

| 模型名称          | 能力                  | 说明                                      |
| ------------- | ------------------- | --------------------------------------- |
| `gpt-image-2` | 文生图 (Text-to-Image) | 根据文本提示词生成图片，调用 `/v1/images/generations` |
| `gpt-image-2` | 图片编辑 (Image Edit)   | 根据参考图 + 文本提示词生成图片，调用 `/v1/images/edits` |

生成任务为**同步**流程：发送请求 → 直接返回图片结果（base64 或 URL）。

***

## 2. 接口地址

| 方法   | 路径                       | Content-Type          | 作用         |
| ---- | ------------------------ | --------------------- | ---------- |
| POST | `/v1/images/generations` | `application/json`    | 文生图（无参考图）  |
| POST | `/v1/images/edits`       | `multipart/form-data` | 图片编辑（有参考图） |

**环境地址**：

| 环境   | Base URL                 |
| ---- | ------------------------ |
| 生产环境 | `https://api.openai.com` |

下文示例统一以 `$BASE_URL` 表示，实际调用请替换为对应环境地址。

***

## 3. 认证

所有请求均需携带 API Key：

```text theme={null}
Authorization: Bearer <YOUR_API_KEY>
```

***

## 4. 文生图接口（/v1/images/generations）

无参考图时调用此接口，请求体为 JSON 格式。

### 4.1 请求参数

| 字段              | 类型     | 必填 | 说明                                                        |
| --------------- | ------ | -- | --------------------------------------------------------- |
| `model`         | string | 是  | 模型名称，如 `gpt-image-2`                                      |
| `prompt`        | string | 是  | 文本提示词                                                     |
| `n`             | int    | 可选 | 生成图片数量，默认 `1`                                             |
| `size`          | string | 可选 | 图片尺寸，如 `1024x1024`、`1024x1536`、`1536x1024`；默认 `auto`      |
| `quality`       | string | 可选 | 图片质量：`high` / `medium` / `low` / `auto`                   |
| `moderation`    | string | 可选 | 内容审核级别，默认 `low`                                           |
| `background`    | string | 可选 | 背景模式（仅 gpt-image-\* 生效）：`transparent` / `opaque` / `auto` |
| `output_format` | string | 可选 | 输出格式（仅 gpt-image-\* 生效）：`png` / `jpeg` / `webp`           |

***

## 5. 图片编辑接口（/v1/images/edits）

有参考图时调用此接口，请求体为 `multipart/form-data` 格式，参考图以文件形式上传。

### 5.1 请求参数

| 字段              | 类型      | 必填 | 说明                                                        |
| --------------- | ------- | -- | --------------------------------------------------------- |
| `image`         | file\[] | 是  | 参考图文件（支持多值，同名 `image` 字段多文件上传）                            |
| `model`         | string  | 是  | 模型名称，如 `gpt-image-2`                                      |
| `prompt`        | string  | 是  | 文本提示词                                                     |
| `n`             | int     | 可选 | 生成图片数量，默认 `1`                                             |
| `size`          | string  | 可选 | 图片尺寸；默认 `auto`                                            |
| `quality`       | string  | 可选 | 图片质量：`high` / `medium` / `low` / `auto`                   |
| `moderation`    | string  | 可选 | 内容审核级别，默认 `low`                                           |
| `background`    | string  | 可选 | 背景模式（仅 gpt-image-\* 生效）：`transparent` / `opaque` / `auto` |
| `output_format` | string  | 可选 | 输出格式（仅 gpt-image-\* 生效）：`png` / `jpeg` / `webp`           |

### 5.2 参考图素材要求

* **格式**：JPEG / JPG / PNG / WEBP
* **大小**：无硬性上限，建议 ≤ 10MB / 张
* **数量**：支持多张参考图，同名 `image` 字段多值上传

***

## 6. 请求示例

### 6.1 文生图（generations）

```bash theme={null}
curl -X POST $BASE_URL/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫坐在窗台上，阳光洒在身上，油画风格",
    "n": 1,
    "size": "1024x1536",
    "quality": "high",
    "moderation": "low",
    "background": "auto",
    "output_format": "png"
  }'
```

### 6.2 图片编辑（edits）

```bash theme={null}
curl -X POST $BASE_URL/v1/images/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "prompt=将他们合并在一个图片里重画" \
  -F "n=1" \
  -F "size=1024x1536" \
  -F "quality=low" \
  -F "moderation=low" \
  -F "image=@ref1.png" \
  -F "image=@ref2.png"
```

***

## 7. 响应格式

### 7.1 成功响应

```json theme={null}
{
  "created": 1777282922,
  "data": [
    {
      "b64_json": "",
      "revised_prompt": "跳舞的大象，动漫",
      "url": ""
    }
  ],
  "model": "gpt-image-2",
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 370,
    "input_tokens": 12,
    "output_tokens": 358,
    "input_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 12,
      "audio_tokens": 0,
      "image_tokens": 0
    }
  }
}
```

**顶层字段**：

| 字段        | 类型     | 说明         |
| --------- | ------ | ---------- |
| `created` | int    | 任务创建时间戳    |
| `data`    | array  | 图片结果数组     |
| `model`   | string | 使用的模型名称    |
| `usage`   | object | token 消耗统计 |

**data\[] 元素字段**：

| 字段               | 类型     | 说明                            |
| ---------------- | ------ | ----------------------------- |
| `b64_json`       | string | base64 编码的图片数据（与 `url` 二选一返回） |
| `revised_prompt` | string | 模型修订后的提示词（可能对原始 prompt 做了改写）  |

**usage 字段**：

| 字段                                   | 类型  | 说明                                  |
| ------------------------------------ | --- | ----------------------------------- |
| `prompt_tokens`                      | int | 输入 prompt token 数（兼容旧版字段，通常为 0）     |
| `completion_tokens`                  | int | 输出 completion token 数（兼容旧版字段，通常为 0） |
| `total_tokens`                       | int | 总消耗 token 数                         |
| `input_tokens`                       | int | 输入 token 数                          |
| `output_tokens`                      | int | 输出 token 数                          |
| `input_tokens_details.cached_tokens` | int | 命中缓存的 token 数                       |
| `input_tokens_details.text_tokens`   | int | 文本输入 token 数                        |
| `input_tokens_details.audio_tokens`  | int | 音频输入 token 数                        |
| `input_tokens_details.image_tokens`  | int | 图片输入 token 数                        |

### 7.2 错误响应

```json theme={null}
{
  "error": {
    "code": "InvalidParameter",
    "message": "error description"
  }
}
```

***

## 8. 错误码

| HTTP | code                 | 说明                          |
| ---- | -------------------- | --------------------------- |
| 400  | `InvalidParameter`   | 请求参数错误（如 prompt 为空、图片格式不支持） |
| 401  | `Unauthorized`       | API Key 无效或未提供              |
| 403  | `Forbidden`          | 无权限调用该模型                    |
| 429  | `RateLimitExceeded`  | 触发频率限制                      |
| 500  | `InternalError`      | 服务内部错误                      |
| 503  | `ServiceUnavailable` | 上游服务不可用，建议稍后重试              |

***

## 9. 计费说明

* 计费单位：按 token（`input_tokens` + `output_tokens`）
* 命中缓存的 token 按缓存价格计费，低于正常输入价格
* 任务失败不计费
* 具体价格请查看平台「模型价格」页面

***

## 10. 常见问题

**Q1：gpt-image-2 支持哪些输出格式？** A：支持 `png`（默认）、`jpeg`、`webp`，通过 `output_format` 参数指定。

**Q2：如何生成透明背景图片？** A：设置 `background` 为 `transparent`，输出格式建议使用 `png`（仅 gpt-image-\* 支持）。

**Q3：generations 和 edits 接口如何选择？** A：无参考图（纯文生图）使用 `/v1/images/generations`；有参考图（图片编辑/融合）使用 `/v1/images/edits`。

**Q4：edits 接口如何上传多张参考图？** A：使用同名 `image` 字段多值上传，如 `-F "image=@ref1.png" -F "image=@ref2.png"`。

**Q5：`revised_prompt` 是什么？** A：模型可能对原始 prompt 做了改写或扩展，`revised_prompt` 即为模型实际使用的提示词文本。

**Q6：quality 参数支持哪些值？** A：字符串枚举 `high` / `medium` / `low` / `auto`。

***

## 11. 快速接入清单

* 获取 API Key
* 确认调用环境，可访问 OpenAI API Base URL
* 选择接口：文生图 → `/v1/images/generations`；图片编辑 → `/v1/images/edits`
* 图片编辑场景准备参考图文件，以 `multipart/form-data` 上传
* 发送请求，同步获取图片结果（`b64_json` 或 `url`）
* 解码 base64 数据或下载 URL 保存图片