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

# Gemini 图像生成 API

> 使用 `POST /v1beta/models/{model}:generateContent` 调用 Gemini 图像生成接口，统一覆盖 `gemini-3-pro-image-preview`、`gemini-2.5-flash-image-preview`、`gemini-3.1-flash-image-preview` 和 `gemini-3.1-flash-lite-image`。

# Gemini 图像生成 API

Gemini 图像模型统一使用官方 `generateContent` 格式生图，适合直接复用 `contents` / `parts` 结构。

* 路径为 `POST /v1beta/models/{model}:generateContent`。
* 文生图和图生图都走同一套 `contents[].parts[]` 结构。
* 参考图通过 `parts[].inlineData` 传入。
* `generationConfig.responseModalities` 建议同时请求 `IMAGE` 和 `TEXT`。
* 返回里既可能直接给 `inlineData.data` Base64，也可能给图片 URL。

## 支持模型

* `gemini-3-pro-image-preview`
* `gemini-2.5-flash-image-preview`
* `gemini-3.1-flash-image-preview`
* `gemini-3.1-flash-lite-image`

## 模型差异

| 模型                               | `imageSize` 行为 | 说明                        |
| -------------------------------- | -------------- | ------------------------- |
| `gemini-3-pro-image-preview`     | 支持 `1K`、`2K`   | 会按请求里的 `imageSize` 真实下发   |
| `gemini-2.5-flash-image-preview` | 实际回落为 `1K`     | 即使请求中传 `2K`，最终也会按 `1K` 处理 |
| `gemini-3.1-flash-image-preview` | 实际回落为 `1K`     | 即使请求中传 `2K`，最终也会按 `1K` 处理 |
| `gemini-3.1-flash-lite-image`    | 实际回落为 `1K`     | 即使请求中传 `2K`，最终也会按 `1K` 处理 |

## Body

<ParamField body="contents" type="array<object>" required>
  输入内容列表。每项通常包含 `role` 和 `parts`。
</ParamField>

<ParamField body="contents[].role" type="string">
  角色字段，常用值为 `user`。
</ParamField>

<ParamField body="contents[].parts" type="array<object>" required>
  内容片段数组。提示词和参考图都在这里构造。
</ParamField>

<ParamField body="contents[].parts[].text" type="string">
  文本提示词。
</ParamField>

<ParamField body="contents[].parts[].inlineData" type="object">
  参考图输入。包含 `mimeType` 和 `data` 两个字段。
</ParamField>

<ParamField body="contents[].parts[].inlineData.mimeType" type="string">
  图片 MIME 类型，常见值为 `image/jpeg`、`image/png`、`image/webp`。
</ParamField>

<ParamField body="contents[].parts[].inlineData.data" type="string">
  Base64 编码的图片内容。
</ParamField>

<ParamField body="generationConfig" type="object" required>
  生成配置对象。
</ParamField>

<ParamField body="generationConfig.responseModalities" type="array<string>">
  返回模态列表。建议同时请求 `IMAGE` 和 `TEXT`。
</ParamField>

<ParamField body="generationConfig.imageConfig" type="object" required>
  图像配置对象。
</ParamField>

<ParamField body="generationConfig.imageConfig.aspectRatio" type="string">
  图片比例。常见值包括 `1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`、`21:9`。
</ParamField>

<ParamField body="generationConfig.imageConfig.imageSize" type="string">
  图片清晰度。`gemini-3-pro-image-preview` 支持 `1K` 和 `2K`；`gemini-2.5-flash-image-preview`、`gemini-3.1-flash-image-preview` 与 `gemini-3.1-flash-lite-image` 会实际回落为 `1K`。
</ParamField>

<ParamField body="safetySettings" type="array<object>">
  安全设置。可不传。
</ParamField>

## 图生图请求结构

Gemini 不提供单独的编辑接口。图生图请求会将参考图直接作为输入内容写入 `contents[].parts[]`。

可简化理解为：

* 文生图：`parts[]` 里只有文本。
* 图生图：`parts[]` 里同时包含文本和图片。

也就是说，提示词与参考图会在同一次请求中一并提交给模型。

## 文生图 vs 图生图

| 场景  | `parts[]` 内容                | 说明                |
| --- | --------------------------- | ----------------- |
| 文生图 | 只有 `text`                   | 纯提示词生成            |
| 图生图 | `text` + 一个或多个 `inlineData` | 让模型参考已有图片风格、主体或构图 |

## 图生图字段构造

请求构造可遵循以下规则：

* 第一类内容是提示词：`{ "text": "..." }`
* 第二类内容是参考图：`{ "inlineData": { "mimeType": "...", "data": "BASE64..." } }`

构造请求时通常先放文本提示词，再将每一张参考图转成 Base64，按顺序追加到同一个 `parts[]`。

## 图生图示例

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "保留参考图的主体氛围，重做成更高级的海报" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_IMAGE"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    }
  }
}
```

## 方法与路径

```http theme={null}
POST /v1beta/models/{model}:generateContent
```

## 请求示例

<CodeGroup>
  ```bash theme={null}
  curl -X POST https://www.geeknow.top/v1beta/models/gemini-3-pro-image-preview:generateContent \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [
        {
          "role": "user",
          "parts": [
            { "text": "一张未来感 AI 工作台场景，冷色氛围，电影级布光" }
          ]
        }
      ],
      "generationConfig": {
        "responseModalities": ["TEXT", "IMAGE"],
        "temperature": 1.0,
        "topP": 0.95,
        "maxOutputTokens": 8192,
        "imageConfig": {
          "aspectRatio": "16:9",
          "imageSize": "2K"
        }
      }
    }'
  ```

  ```python theme={null}
  import requests

  resp = requests.post(
      "https://www.geeknow.top/v1beta/models/gemini-3-pro-image-preview:generateContent",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Accept": "application/json",
          "Content-Type": "application/json",
      },
      json={
          "contents": [
              {
                  "role": "user",
                  "parts": [
                      {"text": "一张未来感 AI 工作台场景，冷色氛围，电影级布光"}
                  ],
              }
          ],
          "generationConfig": {
              "responseModalities": ["TEXT", "IMAGE"],
              "temperature": 1.0,
              "topP": 0.95,
              "maxOutputTokens": 8192,
              "imageConfig": {
                  "aspectRatio": "16:9",
                  "imageSize": "2K",
              },
          },
      },
      timeout=60,
  )
  print(resp.json())
  ```

  ```javascript theme={null}
  const response = await fetch(
    "https://www.geeknow.top/v1beta/models/gemini-3-pro-image-preview:generateContent",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        Accept: "application/json",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        contents: [
          {
            role: "user",
            parts: [{ text: "一张未来感 AI 工作台场景，冷色氛围，电影级布光" }],
          },
        ],
        generationConfig: {
          responseModalities: ["TEXT", "IMAGE"],
          temperature: 1.0,
          topP: 0.95,
          maxOutputTokens: 8192,
          imageConfig: {
            aspectRatio: "16:9",
            imageSize: "2K",
          },
        },
      }),
    }
  );

  console.log(await response.json());
  ```
</CodeGroup>

## 图生图示例

```json theme={null}
{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "融合参考图风格，输出一张高清横版海报" },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_IMAGE_1"
          }
        },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "BASE64_IMAGE_2"
          }
        }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "2K"
    }
  }
}
```

## 图生图字段解释

| 字段                            | 图生图里的作用                  |
| ----------------------------- | ------------------------ |
| `parts[].text`                | 告诉模型“你要怎么改、保留什么、输出成什么风格” |
| `parts[].inlineData.mimeType` | 声明参考图格式                  |
| `parts[].inlineData.data`     | 参考图的 Base64 内容           |
| `imageConfig.aspectRatio`     | 约束最终出图比例                 |
| `imageConfig.imageSize`       | 约束最终出图清晰度                |

## 参考图数量

多参考图可以按顺序追加多个 `inlineData`：

* 支持 1 张参考图
* 也支持多张参考图
* 多张时就是连续放多个 `inlineData`

## 返回值说明

Gemini 生图返回的图片通常在：

* `candidates[0].content.parts[].inlineData.data`

这个字段可能有两种情况：

1. 直接是 Base64 图片数据
2. 直接是图片 URL

因此文档示例中用 `BASE64_OR_URL` 表示这两种可能的返回形式。

## 响应示例

<ResponseExample>
  ```json 200 theme={null}
  {
    "candidates": [
      {
        "content": {
          "role": "model",
          "parts": [
            {
              "inlineData": {
                "mimeType": "image/png",
                "data": "BASE64_OR_URL"
              }
            }
          ]
        },
        "finishReason": "STOP"
      }
    ],
    "usageMetadata": {
      "promptTokenCount": 123,
      "candidatesTokenCount": 456,
      "totalTokenCount": 579,
      "trafficType": "ON_DEMAND"
    },
    "modelVersion": "gemini-3-pro-image-preview",
    "createTime": "2026-05-21T00:00:00Z"
  }
  ```
</ResponseExample>

## Response

<ResponseField name="candidates[].content.parts[].inlineData.mimeType" type="string">
  返回图片 MIME 类型。
</ResponseField>

<ResponseField name="candidates[].content.parts[].inlineData.data" type="string">
  图片数据。可能是 Base64，也可能直接是图片 URL。
</ResponseField>

<ResponseField name="usageMetadata" type="object">
  Token 统计信息。
</ResponseField>

## 异步调用

Gemini 图像模型也支持通过统一图像异步入口提交任务：

```http theme={null}
POST /v1/images/generations/async
```

异步入口使用 OpenAI Images 兼容 JSON，而不是本页的 Gemini 原生 `contents[].parts[]` 请求体。`model` 可以传 `gemini-3-pro-image-preview`、`gemini-2.5-flash-image-preview`、`gemini-3.1-flash-image-preview` 或 `gemini-3.1-flash-lite-image`。提交成功后读取返回的 `id` / `task_id`，再通过 `GET /v1/images/generations/async/{taskId}` 查询状态和结果。

## 相关接口

* [图像模型支持矩阵](/api-reference/images/model-matrix)
* [图像异步生成 API](/api-reference/images/gpt-image-async/generation)
* [图像异步任务查询](/api-reference/images/gpt-image-async/query)
* [gpt-image-2 生成图像 API](/api-reference/images/gpt-image-2/generation)
* [Doubao Seedream 生成图像 API](/api-reference/images/doubao-seedream/generation)