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

# Gemini 图片生成 API

> 使用 gemini-3-pro-image-preview 系列模型生成高质量图片

## 模型映射关系

| 内部代号                | 官方/API 名称                        | 特点                 | 文档链接                                                   |
| ------------------- | -------------------------------- | ------------------ | ------------------------------------------------------ |
| **Nano Banana 2**   | `gemini-3.1-flash-image-preview` | 主打速度与主流高质量，目前的默认模型 | [Gemini 3.1 Flash 文档](/api-reference/gemini-3-1-flash) |
| **Nano Banana Pro** | `gemini-3-pro-image-preview`     | 主打极致质量，Pro/高级选项    | 当前文档                                                   |

<Note>
  **注意：** `gemini-3.1-flash-image-preview` (Nano Banana 2) 使用不同的 API 格式，请查看专门的 [Gemini 3.1 Flash 文档](/api-reference/gemini-3-1-flash)。
</Note>

## 支持的模型

<CardGroup cols={3}>
  <Card title="gemini-3-pro-image-preview" icon="image">
    标准分辨率版本
  </Card>

  <Card title="gemini-3-pro-image-preview-2k" icon="image">
    2K 分辨率版本
  </Card>

  <Card title="gemini-3-pro-image-preview-4k" icon="sparkles">
    4K 高清分辨率版本
  </Card>
</CardGroup>

## 文生图

通过文本描述生成图片。

<Note>
  **配置说明：**

  * 将 `api.xxx.com` 替换为您的实际 API 域名
  * 将 `sk-xxx` 替换为您的 API 密钥（可在控制台获取）
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xxx.com/v1/images/generations" \
    -H "Authorization: Bearer sk-xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3-pro-image-preview",
      "prompt": "请为黑客帝国设计一张高品质的3D海报,需要先检索影视剧/小说信息和著名的片段场景。首先,请利用你的知识库检索这个影视剧/小说的内容,找出一个最具代表性的名场面或核心地点。在画面中央,将这个场景构建为一个精致的轴侧视角3D微缩模型。风格要采用梦工厂动画那种细腻、柔和的渲染风格。你需要还原当时的建筑细节、人物动态以及环境氛围,无论是暴风雨还是宁静的午后,都要自然地融合在模型的光影里。关于背景,不要使用简单的纯白底。请在模型周围营造一种带有淡淡水墨晕染和流动光雾的虚空环境,色调雅致,让画面看起来有呼吸感和纵深感,衬托出中央模型的珍贵。最后是底部的排版,请生成中文文字。居中写上小说名称,字体要有与原著风格匹配的设计感。在书名下方,自动检索并排版一句原著中关于该场景的经典描写或台词,字体使用优雅的衬线体。整体布局要像一个高级的博物馆藏品铭牌那样精致平衡。",
      "size": "1x1",
      "n": 1
    }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.xxx.com/v1/images/generations"
  headers = {
      "Authorization": "Bearer sk-xxx",
      "Content-Type": "application/json"
  }

  data = {
      "model": "gemini-3-pro-image-preview",
      "prompt": "请为黑客帝国设计一张高品质的3D海报,需要先检索影视剧/小说信息和著名的片段场景。首先,请利用你的知识库检索这个影视剧/小说的内容,找出一个最具代表性的名场面或核心地点。在画面中央,将这个场景构建为一个精致的轴侧视角3D微缩模型。风格要采用梦工厂动画那种细腻、柔和的渲染风格。你需要还原当时的建筑细节、人物动态以及环境氛围,无论是暴风雨还是宁静的午后,都要自然地融合在模型的光影里。关于背景,不要使用简单的纯白底。请在模型周围营造一种带有淡淡水墨晕染和流动光雾的虚空环境,色调雅致,让画面看起来有呼吸感和纵深感,衬托出中央模型的珍贵。最后是底部的排版,请生成中文文字。居中写上小说名称,字体要有与原著风格匹配的设计感。在书名下方,自动检索并排版一句原著中关于该场景的经典描写或台词,字体使用优雅的衬线体。整体布局要像一个高级的博物馆藏品铭牌那样精致平衡。",
      "size": "1x1",
      "n": 1
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(json.dumps(result, indent=2, ensure_ascii=False))
  ```

  ```json Response theme={null}
  {
    "model": "gemini-3-pro-image-preview",
    "created": 1765250822,
    "data": [
      {
        "url": "https://...",
        "size": "1024x1024"
      }
    ],
    "usage": {
      "generated_images": 1
    }
  }
  ```
</CodeGroup>

## 参数说明

### 常用参数

| 参数名               | 类型           | 必填 | 说明     | 默认值/可选值                                                                                        |
| ----------------- | ------------ | -- | ------ | ---------------------------------------------------------------------------------------------- |
| `model`           | string       | ✅  | 模型名称   | `gemini-3-pro-image-preview`, `gemini-3-pro-image-preview-2k`, `gemini-3-pro-image-preview-4k` |
| `prompt`          | string       | ✅  | 文本提示词  | 支持中英文，建议详细描述                                                                                   |
| `image`           | string/array | ❌  | 输入图片   | 图生图/多图融合时使用，支持 URL 或 Base64                                                                    |
| `size`            | string       | ❌  | 图片尺寸   | `1:1`, `16:9`, `9:16` 等比例格式                                                                    |
| `response_format` | string       | ❌  | 响应格式   | `url`(链接), `b64_json`(Base64), 默认`url`                                                         |
| `n`               | integer      | ❌  | 生成图片数量 | 默认为 1                                                                                          |

## 图生图 (Base64)

基于输入图片生成新图片，支持 Base64 格式上传。

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xxx.com/v1/images/generations" \
    -H "Authorization: Bearer sk-xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3-pro-image-preview",
      "prompt": "将这张图转换为油画风格",
      "size": "1:1",
      "response_format": "url",
      "n": 1,
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
    }'
  ```

  ```python Python theme={null}
  import requests
  import json
  import base64

  # 读取本地图片并转换为 Base64
  def image_to_base64(image_path):
      with open(image_path, "rb") as image_file:
          encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
          return f"data:image/jpeg;base64,{encoded_string}"

  url = "https://api.xxx.com/v1/images/generations"
  headers = {
      "Authorization": "Bearer sk-xxx",
      "Content-Type": "application/json"
  }

  data = {
      "model": "gemini-3-pro-image-preview",
      "prompt": "将这张图转换为油画风格",
      "size": "1:1",
      "response_format": "url",
      "n": 1,
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."  # 或使用 image_to_base64("path/to/image.jpg")
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(json.dumps(result, indent=2, ensure_ascii=False))
  ```

  ```json Response theme={null}
  {
    "model": "gemini-3-pro-image-preview",
    "created": 1765250879,
    "data": [
      {
        "url": "https://...",
        "size": "1024x1024"
      }
    ],
    "usage": {
      "generated_images": 1
    }
  }
  ```
</CodeGroup>

<Info>
  **图片输入格式：** 支持 Base64 编码，格式为 `data:image/jpeg;base64,<base64_data>`
</Info>

## 多图融合 (URL)

融合多张图片的特征生成新图片，支持 URL 格式上传。

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.xxx.com/v1/images/generations" \
    -H "Authorization: Bearer sk-xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3-pro-image-preview",
      "prompt": "将图1的服装换为图2的服装",
      "image": [
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_1.png",
        "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_2.png"
      ],
      "size": "1:1",
      "response_format": "url",
      "n": 1
    }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.xxx.com/v1/images/generations"
  headers = {
      "Authorization": "Bearer sk-xxx",
      "Content-Type": "application/json"
  }

  data = {
      "model": "gemini-3-pro-image-preview",
      "prompt": "将图1的服装换为图2的服装",
      "image": [
          "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_1.png",
          "https://ark-project.tos-cn-beijing.volces.com/doc_image/seedream4_imagesToimage_2.png"
      ],
      "size": "1:1",
      "response_format": "url",
      "n": 1
  }

  response = requests.post(url, headers=headers, json=data)
  result = response.json()
  print(json.dumps(result, indent=2, ensure_ascii=False))
  ```

  ```json Response theme={null}
  {
    "model": "gemini-3-pro-image-preview",
    "created": 1765251003,
    "data": [
      {
        "url": "https://...",
        "size": "1024x1024"
      }
    ],
    "usage": {
      "generated_images": 1
    }
  }
  ```
</CodeGroup>

<Info>
  **多图融合支持：** `image` 参数可以传入数组，支持多张图片的 URL
</Info>

<Note>
  返回的图片URL通常有24小时的有效期，请及时下载保存。
</Note>