Gemini-Nano-Banana-2.1 图像生成 API

# Gemini-Nano-Banana-2.1 图像生成 API 对接文档

> **用途**：第三方软件 / 自有应用对接「Nano Banana 2.1」图像生成能力
> **平台**：云灵API（https://api.cxsee.com）
> **适用对象**：平台注册会员（需有可用令牌与余额）
> **协议**：**双接口支持** —— Gemini 原生 `/v1beta/models/{model}:generateContent` **与** OpenAI 兼容 `/v1/images/generations`
> **模型**：`gemini-nano-banana-2.1`

---

## ⚠️ 四个必须先知道的点

1. **本模型只输出 1K 图**（实际尺寸 **1376×768**）。传入 `size`（1K/2K/4K 或任意尺寸）**不会改变输出分辨率**，一律按 **1K 计费（$0.18/张）**。
2. **`size` 参数可选**。不传也能正常出图；传了也按 1K 处理（**不会因为传 4K 而多扣费**，也不报错）。
3. **两个接口都返回 base64 图片（`b64_json`）**，需自行解码保存；本模型**不返回图片 URL**。
4. **输出为宽幅 1376×768**（非正方形）。如需其他比例/更高分辨率，请选用其它图像模型。

---

## 1. 快速开始

### 1.1 方式 A：OpenAI 兼容接口（推荐，接入最简单）

```bash
curl -X POST "https://api.cxsee.com/v1/images/generations" \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-nano-banana-2.1",
    "prompt": "一只白色背景上的红苹果，产品摄影",
    "n": 1
  }'
```

```json
{
  "created": 1791988736,
  "data": [
    {
      "url": "",
      "b64_json": "/9j/4AAQSkZJRgABAQEBLAEsAAD/6xe4...（base64省略）",
      "revised_prompt": ""
    }
  ]
}
```

### 1.2 方式 B：Gemini 原生接口

```bash
curl -X POST "https://api.cxsee.com/v1beta/models/gemini-nano-banana-2.1:generateContent" \
  -H "Authorization: Bearer <你的API令牌>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      { "role": "user", "parts": [ { "text": "一只白色背景上的红苹果，产品摄影" } ] }
    ]
  }'
```

返回（Gemini 原生格式）：

```json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/jpeg",
              "data": "/9j/4AAQSkZJRgABAQEBLA...(base64省略)"
            }
          }
        ]
      }
    }
  ]
}
```

> 两个接口底层调用同一模型，返回的图片内容格式一致（JPEG）。

---

## 2. 参数说明

### 2.1 `/v1/images/generations`（OpenAI 兼容）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `model` | string | ✅ | 固定 `gemini-nano-banana-2.1` |
| `prompt` | string | ✅ | 画面描述（支持中英文） |
| `n` | int | ❌ | 生成张数，默认 1；**每张独立计费 $0.18** |
| `size` | string | ❌ | 可选，**不生效**（无论传什么，输出恒 1376×768，按 1K 计费）。可传 `1K` 语义占位 |

### 2.2 `/v1beta/models/gemini-nano-banana-2.1:generateContent`（Gemini 原生）

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `contents` | array | ✅ | 对话内容数组，`role=user`、`parts[].text=提示词` |
| `size`（顶层） | string | ❌ | 可选，**不生效**（同 OpenAPI 接口） |

请求体最小示例：

```json
{
  "contents": [
    { "role": "user", "parts": [ { "text": "你的提示词" } ] }
  ]
}
```

> 若传 `size`，请放在**请求体顶层**（非 `generationConfig` 内），且无论何值都按 1K 处理。

---

## 3. `size` 的实际行为（重要）

| 你传的 `size` | 实际输出 | 实际计费 |
|---|---|---|
| 不传 | 1376×768 | $0.18 |
| `1K` | 1376×768 | $0.18 |
| `2K` | 1376×768 | $0.18 |
| `4K` | 1376×768 | $0.18 |
| `1024x1024` 等任意值 | 1376×768 | $0.18 |

**结论**：`size` 对本模型**只是兼容性占位参数，不产生任何效果**。请勿依赖它控制分辨率。

---

## 4. 计费

| 项 | 说明 |
|---|---|
| 单价 | **$0.18 / 张**（固定，与尺寸无关） |
| 多张 | `n=3` → 计费 3 × $0.18 = **$0.54** |
| 失败 | 上游失败**不扣费** |
| 展示例 | $1 = 500,000 算力（quota） |

---

## 5. 错误码

| HTTP | 消息 | 原因 / 处理 |
|---|---|---|
| 401 | `无效的令牌` | 令牌错误或已停用，检查 `Authorization: Bearer <key>` |
| 500 | `spec size_fixed: no rule matched for size=...` | 极少见；请联系管理员（正常配置下不会出现） |
| 503 | `当前分组下…无可用渠道` | 该模型在当前分组无渠道，切换分组或联系管理员 |
| 400 | `contents is required` | 原生接口未传 `contents` |

---

## 6. 调用示例（Python）

```python
import requests, base64, time

API_KEY = "<你的API令牌>"
URL = "https://api.cxsee.com/v1/images/generations"

resp = requests.post(
    URL,
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"model": "gemini-nano-banana-2.1", "prompt": "一只红苹果，白底产品图", "n": 1},
    timeout=180,  # ⭐ 建议 ≥180s，该模型耗时波动较大
)
resp.raise_for_status()
data = resp.json()

img_bytes = base64.b64decode(data["data"][0]["b64_json"])
with open(f"out_{int(time.time())}.jpg", "wb") as f:
    f.write(img_bytes)
print("saved, bytes =", len(img_bytes))
```

---

## 7. 注意事项

- **超时建议 ≥ 180 秒**：实测该模型单张耗时在本平台历史上为 8~82 秒不等，波动较大。
- **返回 base64**：请自行 base64 解码为 `.jpg` 文件（JPEG 格式）。
- **分辨率固定 1376×768**：为宽屏比例。若业务需要正方形 / 竖版 / 2K / 4K，请选用平台其它图像模型（如 `gemini-3-pro-image-preview` 系列）。

---

## 8. FAQ

**Q：为什么我传 `size: "4K"` 出来的图还是 1K？**
A：本模型当前**仅支持 1K 输出**，`size` 为兼容性占位参数，不生效。

**Q：会因为我传 4K 而被多收费吗？**
A：不会。无论 `size` 传什么，一律按 **$0.18/张（1K）** 计费。

**Q：两个接口返回的图有区别吗？**
A：没有。二者调用同一底层模型，输出均为 JPEG（1376×768）。

**Q：能一次生成多张不同尺寸吗？**
A：不能。单次请求尺寸固定；多张请用 `n` 参数，但每张尺寸相同。

---

*文档版本：2026-10-14 ｜ 平台：云灵API（api.cxsee.com）*

上一篇：Gemini Embeddings接口（向量嵌入）下一篇：Gemini 对话（OpenAI 兼容）