Gemini 绘画（官方原生系列）

# Gemini 绘画（官方原生系列）API 文档

> 官方原生图像模型：`gemini-3.1-flash-image-preview-2k`
> 统一网关：`/v1/images/generations`

体验地址：https://try.cxsee.com/image/gemini

---

## 1. 概述

Gemini 绘画（官方原生系列）基于 Google Gemini 官方原生图像能力，当前推荐模型：

- `gemini-2.5-flash-image、gemini-3.1-flash-image-preview、gemini-3.1-flash-image-preview-2k等模型`

支持能力：

- 文生图（Text-to-Image）
- 图生图（Image-to-Image）
- 多图参考生成（Multi-Image-to-Image）
- OpenAI Images 风格响应（`data[].url`）
- 支持高分辨率图像输出（2K 场景友好）

---

## 2. 模型信息

| 模型名 | 能力 | 说明 |
|---|---|---|
| `gemini-3.1-flash-image-preview-2k` | 文生图/图生图/多图生图 | Gemini 官方原生图像预览模型，2K 输出场景推荐 |

---

## 3. 接口说明

### URL
`POST /v1/images/generations`

完整地址：
`https://api.cxsee.com/v1/images/generations`

### Header
- `Authorization: Bearer sk-xxxx`
- `Content-Type: application/json`

---

## 4. 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `model` | string | 是 | 固定传：`gemini-3.1-flash-image-preview-2k` |
| `prompt` | string | 是 | 图片描述词（建议清晰描述主体、风格、光线、镜头） |
| `size` | string | 否 | 输出尺寸，如 `1024x1024`、`1536x1024` |
| `image_size` | string | 否 | 输出等级控制（如网关支持可用：`1k`/`2k`） |
| `image` | string / array | 否 | 图生图输入；支持单图或多图（URL/base64 由网关能力决定） |

> 说明：
> - 文生图：仅需 `model + prompt`
> - 图生图/多图生图：需额外传 `image`

---

## 5. 调用示例

### 5.1 文生图

```bash
curl -X POST "https://api.cxsee.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview-2k",
    "prompt": "未来主义生态住宅，玻璃幕墙与垂直花园融合，黄昏柔和光线，鸟瞰视角，写实渲染",
    "size": "1024x1024"
  }'
```

---

### 5.2 图生图（单图参考）

```bash
curl -X POST "https://api.cxsee.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview-2k",
    "prompt": "保留主体建筑结构，替换为雨后街景，电影级光影，超写实风格",
    "image": "https://your-cdn.com/input/building.png",
    "size": "1024x1024"
  }'
```

---

### 5.3 多图生图（3 张参考）

```bash
curl -X POST "https://api.cxsee.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image-preview-2k",
    "prompt": "参考第1张构图、第2张材质颜色、第3张环境氛围，生成统一写实风格建筑效果图",
    "image": [
      "https://your-cdn.com/ref1.png",
      "https://your-cdn.com/ref2.jpg",
      "https://your-cdn.com/ref3.webp"
    ],
    "image_size": "2k"
  }'
```

---

## 6. 成功返回

```json
{
  "created": 1772732465,
  "data": [
    {
      "url": "https://webstatic.aiproxy.vip/output/20260306/2335/d9601be5-8768-4213-a152-dafec3667022.png",
      "b64_json": "",
      "revised_prompt": ""
    }
  ]
}
```

### 返回字段说明
- `created`：Unix 时间戳
- `data`：结果数组
- `data[].url`：图片链接（推荐直接下载保存）
- `data[].b64_json`：Base64 图片内容（返回 URL 时可能为空）
- `data[].revised_prompt`：修订提示词（可能为空字符串）

---

## 7. 错误返回示例

```json
{
  "error": {
    "message": "no images generated",
    "type": "server_error",
    "code": "bad_response_body"
  }
}
```

### 常见错误码/错误场景
- `no images generated`：模型未成功生成
- `bad_response_body`：上游响应异常或空图
- `unauthorized`/`invalid_api_key`：鉴权失败

---

## 8. 使用建议

1. 多图提示词建议明确：`图1负责构图，图2负责材质，图3负责氛围`。
2. 返回 `url` 建议立即下载，避免链接过期。
3. 生产环境建议加入重试（指数退避，1~2 次即可）。
4. API Key 仅后端保存，避免前端泄露。

---
生成效果
![](https://img.cxhao.com/2026032123405527316?imageMogr2/thumbnail/1024x/format/jpg/blur/1x0/quality/95|imageslim)

上一篇：Gemini 绘画（nano-banana系列）下一篇：Gemini 视频模型格式