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

# Gemini 图像接口

> 通过 Gemini 原生 generateContent 调用图像输出模型

使用 Gemini 原生 `generateContent` API 调用图像输出模型，适用于 Gemini 图像模型与使用 Gemini 原生 `generateContent` API 调用图像输出模型，适用于 Gemini 图像模型与已使用 Gemini 官方 SDK 的项目。

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://gogogotoken.ai/v1beta/models/gemini-2.5-flash-image:generateContent" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [{
        "parts": [{ "text": "A watercolor painting of a coastal village at sunset" }]
      }],
      "generationConfig": {
        "responseModalities": ["TEXT", "IMAGE"]
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "candidates": [
      {
        "content": {
          "parts": [
            { "text": "Here is the image." },
            {
              "inlineData": {
                "mimeType": "image/png",
                "data": "<base64>"
              }
            }
          ]
        }
      }
    ]
  }
  ```
</ResponseExample>

## 接口说明

Gemini 图像模型通常通过 `inlineData` 返回 base64 图片数据。前端展示前需要拼接为 `data:image/png;base64,...`，或解码为 Blob 再渲染。

<Info>
  如需稳定获得图片输出，建议在 `generationConfig.responseModalities` 中包含 `"IMAGE"`。
</Info>

## 路径参数

<ParamField path="image-model" default="gemini-2.5-flash-image" type="string" required>
  Gemini 图像模型 ID，例如 `gemini-2.5-flash-image`。完整模型 ID 以 `GET /v1/models` 与模型广场为准。
</ParamField>

## 请求头

<ParamField header="Authorization" type="string" required>
  API Key 鉴权信息，格式为 `Bearer YOUR_API_KEY`。
</ParamField>

<ParamField header="Content-Type" type="string" required>
  固定为 `application/json`。
</ParamField>

## 请求体

<ParamField body="contents" default={[{parts:[{text:"A watercolor painting of a coastal village at sunset"}]}]} type="object[]" required>
  生成请求内容数组。

  <ParamField body="parts" type="object[]" required>
    内容片段数组，通常包含图片描述文本，也可以包含参考图等多模态输入。
  </ParamField>
</ParamField>

<ParamField body="generationConfig.responseModalities" default={["TEXT","IMAGE"]} type="string[]">
  响应模态。图像生成建议包含 `IMAGE`，需要文字说明时可同时包含 `TEXT`。
</ParamField>

<ParamField body="generationConfig.temperature" type="number">
  采样温度。数值越高，结果越发散。
</ParamField>

## 响应体

<ResponseField name="candidates" type="object[]">
  模型候选输出数组。
</ResponseField>

<ResponseField name="content.parts" type="object[]">
  输出内容片段数组，可能同时包含文本和图片。
</ResponseField>

<ResponseField name="inlineData.mimeType" type="string">
  图片 MIME 类型，例如 `image/png`。
</ResponseField>

<ResponseField name="inlineData.data" type="string">
  base64 编码的图片内容。
</ResponseField>

## 调用方式对比

| 方式        | 端点                                       | 适用场景                       |
| --------- | ---------------------------------------- | -------------------------- |
| Gemini 原生 | `/v1beta/models/{model}:generateContent` | 已使用 Gemini 官方 SDK、需多模态原生能力 |
| OpenAI 兼容 | `/v1/images/generations`                 | 已使用 OpenAI SDK、想统一图像调用入口   |

<Note>
  OpenAI 兼容转发需渠道侧已配置 Gemini 图像桥接，使用前请先确认。
</Note>

## 错误码

| 状态码   | 含义                  | 处理建议            |
| ----- | ------------------- | --------------- |
| `401` | API Key 无效或未传       | 检查请求头与令牌状态      |
| `403` | 无权限访问目标 Gemini 图像模型 | 检查 API Key 分组权限 |
| `429` | 触发限速                | 降低请求频率或调整套餐     |
| `5xx` | 上游或网关异常             | 稍后重试，并查看控制台日志   |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://gogogotoken.ai/v1beta/models/gemini-2.5-flash-image:generateContent" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [{
        "parts": [{ "text": "A watercolor painting of a coastal village at sunset" }]
      }],
      "generationConfig": {
        "responseModalities": ["TEXT", "IMAGE"]
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "candidates": [
      {
        "content": {
          "parts": [
            { "text": "Here is the image." },
            {
              "inlineData": {
                "mimeType": "image/png",
                "data": "<base64>"
              }
            }
          ]
        }
      }
    ]
  }
  ```
</ResponseExample>

## 接口说明

Gemini 图像模型通常通过 `inlineData` 返回 base64 图片数据。前端展示前需要拼接为 `data:image/png;base64,...`，或解码为 Blob 再渲染。

<Info>
  如需稳定获得图片输出，建议在 `generationConfig.responseModalities` 中包含 `"IMAGE"`。
</Info>

## 路径参数

<ParamField path="image-model" default="gemini-2.5-flash-image" type="string" required>
  Gemini 图像模型 ID，例如 `gemini-2.5-flash-image`。完整模型 ID 以 `GET /v1/models` 与模型广场为准。
</ParamField>

## 请求头

<ParamField header="Authorization" type="string" required>
  API Key 鉴权信息，格式为 `Bearer YOUR_API_KEY`。
</ParamField>

<ParamField header="Content-Type" type="string" required>
  固定为 `application/json`。
</ParamField>

## 请求体

<ParamField body="contents" default={[{parts:[{text:"A watercolor painting of a coastal village at sunset"}]}]} type="object[]" required>
  生成请求内容数组。

  <ParamField body="parts" type="object[]" required>
    内容片段数组，通常包含图片描述文本，也可以包含参考图等多模态输入。
  </ParamField>
</ParamField>

<ParamField body="generationConfig.responseModalities" default={["TEXT","IMAGE"]} type="string[]">
  响应模态。图像生成建议包含 `IMAGE`，需要文字说明时可同时包含 `TEXT`。
</ParamField>

<ParamField body="generationConfig.temperature" type="number">
  采样温度。数值越高，结果越发散。
</ParamField>

## 响应体

<ResponseField name="candidates" type="object[]">
  模型候选输出数组。
</ResponseField>

<ResponseField name="content.parts" type="object[]">
  输出内容片段数组，可能同时包含文本和图片。
</ResponseField>

<ResponseField name="inlineData.mimeType" type="string">
  图片 MIME 类型，例如 `image/png`。
</ResponseField>

<ResponseField name="inlineData.data" type="string">
  base64 编码的图片内容。
</ResponseField>

## 调用方式对比

| 方式        | 端点                                       | 适用场景                       |
| --------- | ---------------------------------------- | -------------------------- |
| Gemini 原生 | `/v1beta/models/{model}:generateContent` | 已使用 Gemini 官方 SDK、需多模态原生能力 |
| OpenAI 兼容 | `/v1/images/generations`                 | 已使用 OpenAI SDK、想统一图像调用入口   |

<Note>
  OpenAI 兼容转发需渠道侧已配置 Gemini 图像桥接，使用前请先确认。
</Note>

## 错误码

| 状态码   | 含义                  | 处理建议            |
| ----- | ------------------- | --------------- |
| `401` | API Key 无效或未传       | 检查请求头与令牌状态      |
| `403` | 无权限访问目标 Gemini 图像模型 | 检查 API Key 分组权限 |
| `429` | 触发限速                | 降低请求频率或调整套餐     |
| `5xx` | 上游或网关异常             | 稍后重试，并查看控制台日志   |