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

# 图像生成 (OpenAI 风格)

> 使用 OpenAI 兼容接口调用 Gemini 图像生成模型

本文档介绍如何通过 OpenAI 风格的 `/v1/images/generations` 和 `/v1/images/edits` 接口调用 Gemini 图像生成模型。

## 支持的模型

| 模型                           | 说明      | 最大分辨率          | 特点              |
| ---------------------------- | ------- | -------------- | --------------- |
| `gemini-3-pro-image-preview` | 高质量图像生成 | 4K (4096×4096) | 支持复杂提示词理解、参考图编辑 |
| `gemini-2.5-flash-image`     | 快速图像生成  | 1K (1024×1024) | 低延迟，适合原型验证      |

***

## 文生图 `/v1/images/generations`

### 基础请求

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/generations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "一只熊猫在图书馆看书，电影级光影",
    "n": 1,
    "size": "1K",
    "aspect_ratio": "1:1",
    "response_format": "b64_json"
  }'
```

### 请求参数

| 参数                | 类型      | 必填 | 说明                               |
| ----------------- | ------- | -- | -------------------------------- |
| `model`           | string  | ✅  | 模型名称                             |
| `prompt`          | string  | ✅  | 图像描述文本                           |
| `n`               | integer | ❌  | 生成数量，默认 1（仅支持 1）                 |
| `size`            | string  | ❌  | 分辨率，见下方说明                        |
| `response_format` | string  | ❌  | `b64_json` 或 `url`，默认 `b64_json` |
| `aspect_ratio`    | string  | ❌  | 宽高比，如 `1:1`、`16:9`、`9:16`        |

### 分辨率与计费档位

`size` 参数支持两种格式：

1. **档位格式（推荐）**：`"1K"`、`"2K"`、`"4K"`
2. **数字格式**：如 `"1024x1024"`，用于兼容历史写法（仅作为推断档位和宽高比的“提示”，最终像素由上游按栅格表决定）

系统会根据 `size` 以及 `aspect_ratio` 自动计算标准分辨率档位（1K / 2K / 4K），并映射到上游 Gemini 的 `imageConfig.imageSize`：

| 档位 | 含义                 | 建议用途            |
| -- | ------------------ | --------------- |
| 1K | 约 1K 级别像素（最长边约 1K） | 预览、小图、移动端壁纸     |
| 2K | 约 2K 级别像素          | 高清插画、桌面壁纸       |
| 4K | 约 4K 级别像素          | 超高清、精修图、打印或大屏展示 |

各宽高比在不同档位下的具体像素栅格（例如 1K/2K/4K 下 16:9、9:16、2:3 等对应的精确分辨率），请参考《[Gemini 图像生成](/gemini/images)》文档中的 **“分辨率与宽高比”** 小节。

<Note>
  `gemini-2.5-flash-image` 最高仅支持 1K 分辨率。
</Note>

### 宽高比设置

两种方式控制图像比例：

```json theme={null}
// 方式 1：只通过 size（数字）推断
{"size": "1024x1024"}  // 自动推断为 1K + 1:1

// 方式 2：推荐写法——档位 + 显式指定 aspect_ratio（优先级更高）
{"size": "2K", "aspect_ratio": "16:9"}
```

当前支持的宽高比包括：

`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`

### 响应结构

```json theme={null}
{
  "created": 1700000000,
  "data": [
    {
      "b64_json": "<BASE64_IMAGE_DATA>",
      "revised_prompt": "优化后的提示词（如有）"
    }
  ]
}
```

### Python SDK 示例

```python theme={null}
from openai import OpenAI

client = OpenAI(
    base_url="https://models.kapon.cloud/v1",
    api_key="oh-xxxxxxxxxxxxxxxx",
)

resp = client.images.generate(
    model="gemini-3-pro-image-preview",
    prompt="赛博朋克风格的未来城市，霓虹灯倒映在雨水中",
    size="2048x2048",
    response_format="b64_json",
)

# 获取 base64 图片数据
image_b64 = resp.data[0].b64_json
```

***

## 参考图编辑 `/v1/images/edits`

通过上传参考图实现图像编辑、风格迁移等功能。

### 基础请求

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gemini-3-pro-image-preview" \
  -F "prompt=将这张图片转换为油画风格" \
  -F "response_format=b64_json" \
  -F "image=@/path/to/image.png"
```

### 多参考图请求

```bash theme={null}
curl -X POST "$BASE_URL/v1/images/edits" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gemini-3-pro-image-preview" \
  -F "prompt=保持第一张图的构图，参考第二张的色调" \
  -F "response_format=b64_json" \
  -F "size=2048x2048" \
  -F "image=@/path/base.png" \
  -F "image[]=@/path/ref1.png" \
  -F "image[]=@/path/ref2.png"
```

### 请求参数

| 参数                | 类型      | 必填 | 说明                                                   |
| ----------------- | ------- | -- | ---------------------------------------------------- |
| `model`           | string  | ✅  | 模型名称                                                 |
| `prompt`          | string  | ✅  | 编辑指令                                                 |
| `image`           | file    | ✅  | 基准图（主图）                                              |
| `image[]`         | file\[] | ❌  | 参考图，最多 14 张                                          |
| `size`            | string  | ❌  | 输出分辨率，默认自动从基准图推断（支持 `1K`、`2K`、`4K` 或 `widthxheight`） |
| `aspect_ratio`    | string  | ❌  | 显式指定宽高比，如 `1:1`、`16:9`、`9:16`                        |
| `response_format` | string  | ❌  | `b64_json` 或 `url`                                   |
| `mask`            | file    | ❌  | 蒙版图（局部编辑时使用）                                         |

### 自动分辨率推断

当未指定 `size` 时，系统会自动从基准图推断输出分辨率：

* 读取基准图（`image` 字段）的实际尺寸
* 按模型最大能力限制输出（如 `gemini-2.5-flash-image` 最大 1024）
* 保持原图宽高比

<Note>
  - 自动推断功能仅对 `gemini-3-pro-image-preview` 生效；
  - 当显式传入 `aspect_ratio` 时，会优先使用该宽高比，并结合 `size`（或基准图尺寸推断的档位）映射到上游的 `imageConfig.aspectRatio` 与 `imageConfig.imageSize`。
</Note>

***

## 计费说明

采用混合计费模式：

| 计费项  | 说明                     |
| ---- | ---------------------- |
| 文本输入 | 按提示词的 tokens 数量计费      |
| 图像输出 | 每张图片 1290 image tokens |

示例计算（Gemini 3 Pro Image 1K）：

```
输入：50 tokens × 输入价格
输出：1 张 × 1290 tokens × 输出价格
```

***

## 错误处理

| 错误码 | 说明   | 解决方案              |
| --- | ---- | ----------------- |
| 400 | 参数错误 | 检查 prompt、size 格式 |
| 413 | 图片过大 | 压缩参考图至 10MB 以内    |
| 429 | 超出限额 | 检查配额或等待重试         |

***

## 与原生 API 对比

如需使用 Gemini 原生协议（`generateContent`），请参阅 [Gemini 原生图像 API](/gemini/images-native)。

| 特性    | OpenAI 风格        | 原生 API |
| ----- | ---------------- | ------ |
| 学习成本  | 低（兼容 OpenAI SDK） | 中      |
| 功能完整度 | 覆盖常用场景           | 完整     |