Gemini 绘画（nano-banana系列）

# Gemini 绘画 API 文档（Nano-banana 系列）

> 统一网关：`/v1/images/generations`

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

## 1. 概述

Nano-banana 系列是基于 Gemini 图像能力优化的绘画模型，支持：

- 文生图（Text-to-Image）
- 图生图（Image-to-Image）
- 多图参考生成（Multi-Image-to-Image）
- OpenAI DALL·E 风格返回格式（`data[].url`）
- 失败空图不扣费（以平台计费规则为准）

---

## 2. 模型列表

| 模型名 | 能力 | 说明 |
|---|---|---|
| `nano-banana` | 文生图/图生图/多图生图 | 标准版，通用场景推荐 |
| `nano-banana-hd` | 文生图/图生图/多图生图 | 高清版，适合高质量出图 |
| `nano-banana-2` | 文生图/图生图/多图生图 | 增强版，基于 gemini-3-pro-image 优化 |
| `nano-banana-2-2k` | 文生图/图生图/多图生图 | 支持 `image_size` 控制 1K/2K/4K（默认 1K） |

---

## 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 | 是 | 模型名，如 `nano-banana` |
| `prompt` | string | 是 | 生成/编辑提示词 |
| `size` | string | 否 | 输出尺寸，如 `1024x1024`（部分模型生效） |
| `image_size` | string | 否 | 仅 `nano-banana-2-2k` 推荐：`1k`/`2k`/`4k` |
| `image` | string/array | 否 | 图生图输入（可传单张 URL/base64，或多图数组，按你的网关实现） |

> 说明：
> - 纯文生图可不传 `image`。
> - 图生图/多图生图需传 `image`（具体支持 URL 或 base64，建议在你网关侧统一并在控制台说明）。

---

## 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": "nano-banana",
    "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": "nano-banana-2",
    "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": "nano-banana-2",
    "prompt": "参考第1张的建筑体块、第2张的材质与配色、第3张的草原氛围，生成统一写实风格效果图",
    "image": [
      "https://your-cdn.com/ref1.png",
      "https://your-cdn.com/ref2.jpg",
      "https://your-cdn.com/ref3.webp"
    ],
    "size": "1024x1024"
  }'
```

---

### 5.4 `nano-banana-2-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`：上游返回异常/空图
- 鉴权错误：请检查 `Authorization` 的 Key 是否正确、是否过期

---

## 8. 最佳实践

1. **提示词明确分工**：多图场景中写清“图1结构、图2材质、图3氛围”。
2. **及时保存结果图**：返回 URL 可能为临时链接。
3. **高质量场景优先 `nano-banana-hd` 或 `nano-banana-2-2k`**。
4. **重试策略**：遇到 5xx 或 `no images generated` 可指数退避重试 1~2 次。
5. **安全**：API Key 仅放后端，勿暴露前端。

---

使用nano-banana模型图像生成效果
![](https://img.cxhao.com/2026032123323422581)

上一篇：体验中心 API 如何设置下一篇：Gemini 绘画（官方原生系列）