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

# 图像生成 (原生 API)

> 使用 Gemini 原生协议调用图像生成模型

本文档介绍如何使用 Gemini 原生 API 协议（`generateContent`）调用图像生成模型，适用于需要完整参数控制的高级场景。

<Note>
  对于大多数用户，推荐使用更简单的 [OpenAI 兼容接口](/gemini/images-openai)。
</Note>

***

## 接口地址

```
POST /v1beta/models/{model}:generateContent
```

## 支持的模型

| 模型                           | 最大分辨率 | 特点          |
| ---------------------------- | ----- | ----------- |
| `gemini-3-pro-image-preview` | 4K    | 高质量，支持复杂提示词 |
| `gemini-2.5-flash-image`     | 1K    | 快速生成        |

***

## 基础请求

```bash theme={null}
curl -X POST "$BASE_URL/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "一只熊猫在图书馆看书，赛博朋克风格"
      }]
    }],
    "generationConfig": {
      "responseModalities": ["image", "text"],
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "2K"
      }
    }
  }'
```

***

## 请求参数

### `contents` 数组（必填）

每个 content 对象包含 `parts` 数组：

| 部分类型          | 说明                    |
| ------------- | --------------------- |
| `text`        | 文本提示词                 |
| `inline_data` | Base64 编码的参考图（用于图像编辑） |

### `generationConfig` 对象

| 参数                   | 类型        | 说明                     |
| -------------------- | --------- | ---------------------- |
| `responseModalities` | string\[] | 响应模态，图像生成需包含 `"image"` |

### `generationConfig.imageConfig` 对象

| 参数            | 类型     | 默认值     | 说明    |
| ------------- | ------ | ------- | ----- |
| `aspectRatio` | string | `"1:1"` | 宽高比   |
| `imageSize`   | string | `"1K"`  | 分辨率档位 |

***

## 宽高比设置

常用宽高比如下：

| 值             | 输出特点   | 适用场景          |
| ------------- | ------ | ------------- |
| `1:1`         | 正方形    | 头像、图标         |
| `2:3` / `3:2` | 经典插画比例 | 角色立绘、构图较细腻的插画 |
| `3:4` / `4:3` | 略偏竖/偏横 | 移动端/桌面端插画     |
| `4:5` / `5:4` | 接近相纸比例 | 人像、摄影风格图      |
| `16:9`        | 横向宽屏   | 网页横幅、视频封面     |
| `9:16`        | 竖向     | 手机壁纸、社交媒体     |
| `21:9`        | 超宽电影感  | Banner、大屏展示   |

***

## 分辨率档位说明

`imageConfig.imageSize` 支持三个档位：

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

不同宽高比在各档位下的典型像素，可以参考《[Gemini 图像生成](/gemini/images)》中的**分辨率与宽高比**表格，例如：

* Gemini 2.5 Flash（1K 档）：
  * 1:1 → 1024×1024
  * 16:9 → 1344×768
  * 9:16 → 768×1344
* Gemini 3 Pro Image 预览版：
  * 1K / 2K / 4K + 各宽高比（1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9）都有对应的标准分辨率栅格。

<Note>
  - `gemini-2.5-flash-image` 仅支持 `1K`，指定更高档位会自动降级到 1K；
  - `gemini-3-pro-image-preview` 支持 1K / 2K / 4K 三档。
</Note>

***

## 参考图编辑

通过 `inline_data` 传入参考图进行图像编辑：

```json theme={null}
{
  "contents": [{
    "parts": [
      {
        "text": "将这张图片转换为油画风格"
      },
      {
        "inline_data": {
          "mime_type": "image/jpeg",
          "data": "<BASE64_IMAGE_DATA>"
        }
      }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["image", "text"],
    "imageConfig": {
      "aspectRatio": "1:1",
      "imageSize": "2K"
    }
  }
}
```

### 多参考图

可以在 `parts` 数组中添加多个 `inline_data`，最多支持 **15 张参考图**：

```json theme={null}
{
  "contents": [{
    "parts": [
      {"text": "基于第一张图的构图，参考第二张的色调风格"},
      {"inline_data": {"mime_type": "image/jpeg", "data": "<BASE64_BASE_IMAGE>"}},
      {"inline_data": {"mime_type": "image/jpeg", "data": "<BASE64_STYLE_IMAGE>"}}
    ]
  }],
  "generationConfig": {
    "responseModalities": ["image", "text"],
    "imageConfig": {"aspectRatio": "1:1", "imageSize": "2K"}
  }
}
```

***

## 响应结构

```json theme={null}
{
  "candidates": [{
    "content": {
      "parts": [
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "<BASE64_IMAGE_DATA>"
          }
        },
        {
          "text": "生成完成的描述文本（可选）"
        }
      ]
    }
  }],
  "usageMetadata": {
    "promptTokenCount": 50,
    "candidatesTokenCount": 100,
    "totalTokenCount": 150
  }
}
```

| 字段                                        | 说明          |
| ----------------------------------------- | ----------- |
| `candidates[].content.parts[].inlineData` | 生成的图片数据     |
| `usageMetadata.promptTokenCount`          | 输入文本 tokens |
| `usageMetadata.candidatesTokenCount`      | 输出 tokens   |

***

## 计费说明

采用混合计费：

| 计费项  | 说明                                                                                                              |
| ---- | --------------------------------------------------------------------------------------------------------------- |
| 文本输入 | 从 `usageMetadata.promptTokenCount` 获取                                                                           |
| 图像输出 | 优先从 `usageMetadata.candidatesTokensDetails` 中 modality=`image` 的 token 数读取；若上游未细分，则按模型 & 分辨率档位近似折算 image tokens |

大致规则（仅用于缺省情况下的近似计费）：

* Gemini 2.5 Flash（1K 档）：输出每张约 1120 image tokens；
* Gemini 3 Pro Image 预览版：
  * 1K / 2K 档：每张约 1120 image tokens；
  * 4K 档：每张约 2000 image tokens。

***

## 选择建议

| 场景      | 推荐模型                         |
| ------- | ---------------------------- |
| 快速原型验证  | `gemini-2.5-flash-image`     |
| 生产环境高质量 | `gemini-3-pro-image-preview` |
| 复杂语义理解  | `gemini-3-pro-image-preview` |
| 参考图风格迁移 | `gemini-3-pro-image-preview` |

***

## 相关文档

* [OpenAI 兼容接口](/gemini/images-openai) - 更简单的调用方式
* [Gemini 概览](/gemini/overview) - 平台 Gemini 模型总览