# PixelBridge Google Gemini 原生 API 调用说明

> 版本：2026-09-12  
> Base URL：`https://nano.own-jarvis.com`  
> 接口格式：Google AI Studio `generateContent` 兼容格式

该接口适合已按 Google Gemini REST 格式组装 `contents` 和 `generationConfig` 的客户。请求会同步等待图片生成，成功后在 `candidates[].content.parts[].inlineData` 中返回 Base64 图片。

> 计费单位为积分：`1 元充值 = 1 积分到账`。每次请求只生成 1 张图片，以下价格均为每张图片的积分消耗。

## 1. 接口地址

```http
POST /v1beta/models/{model}:generateContent
```

例如：

```text
https://nano.own-jarvis.com/v1beta/models/gemini-3.1-flash-lite-image:generateContent
```

## 2. 鉴权

使用 PixelBridge 工作台创建的 API Key：

```http
x-goog-api-key: pbg_YOUR_API_KEY
```

也支持：

```http
Authorization: Bearer pbg_YOUR_API_KEY
```

为避免 API Key 出现在访问日志和 URL 历史中，请不要使用 `?key=...` 查询参数传递密钥。

## 3. 支持的模型

| 模型路径名 | 清晰度 | 每张消耗积分 |
|---|---:|---:|
| `gemini-3.1-flash-lite-image` | 1K | 0.0525 积分/张 |
| `gemini-3.1-flash-image-preview` | 1K | 0.12 积分/张 |
| `gemini-3.1-flash-image-preview-2k` | 2K | 0.135 积分/张 |
| `gemini-3.1-flash-image-preview-4k` | 4K | 0.15 积分/张 |
| `gemini-3-pro-image-preview` | 1K | 0.15 积分/张 |
| `gemini-3-pro-image-preview-2k` | 2K | 0.18 积分/张 |
| `gemini-3-pro-image-preview-4k` | 4K | 0.225 积分/张 |
| `nano_banana_2`（特价渠道） | 1K | 0.072 积分/张 |
| `nano_banana_2-2K`（特价渠道） | 2K | 0.072 积分/张 |
| `nano_banana_2-4K`（特价渠道） | 4K | 0.09 积分/张 |
| `nano_banana_pro-1K`（特价渠道） | 1K | 0.135 积分/张 |
| `nano_banana_pro-2K`（特价渠道） | 2K | 0.135 积分/张 |
| `nano_banana_pro-4K`（特价渠道） | 4K | 0.135 积分/张 |

模型路径也支持备用名：`nano-banana-2[-2k|-4k]` 和 `nano-banana-pro[-2k|-4k]`。

也可在基础模型路径中使用 `generationConfig.imageConfig.imageSize` 选择 `1K`、`2K` 或 `4K`。Nano Banana 2 Lite 只支持 1K。

特价渠道也可直接把精确 SKU 放入 `{model}` 路径，平台会在内部等待第二渠道任务完成，再按同一 Google 兼容响应格式返回。特价渠道最多接收 8 张参考图。

## 4. 文字生图

```bash
curl -X POST \
  'https://nano.own-jarvis.com/v1beta/models/gemini-3.1-flash-lite-image:generateContent' \
  -H 'x-goog-api-key: pbg_YOUR_API_KEY' \
  -H 'Idempotency-Key: google-order-20260807-0001' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "极简风白色陶瓷杯产品摄影，浅灰色背景，柔和侧光"
      }]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "candidateCount": 1,
      "imageConfig": {
        "aspectRatio": "1:1",
        "imageSize": "1K"
      }
    }
  }'
```

## 5. 参考图改图

### Base64 参考图

```json
{
  "contents": [{
    "role": "user",
    "parts": [
      {
        "inlineData": {
          "mimeType": "image/png",
          "data": "BASE64_IMAGE_DATA"
        }
      },
      {
        "text": "保持产品外形和 Logo 不变，改成黑色高级感影棚背景"
      }
    ]
  }],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {
      "aspectRatio": "3:4",
      "imageSize": "2K"
    }
  }
}
```

### 公网图片链接

```json
{
  "contents": [{
    "role": "user",
    "parts": [
      {
        "fileData": {
          "mimeType": "image/jpeg",
          "fileUri": "https://cdn.example.com/product.jpg"
        }
      },
      {"text": "保留商品主体，改成自然光家居场景"}
    ]
  }]
}
```

参考图规则：

- 支持 JPEG、PNG、WebP。
- 每个请求最多 10 张参考图。
- 公网链接必须是可直接访问的 HTTPS 地址。
- 不接受 localhost、内网 IP 或 HTTP 明文链接。

## 6. 成功响应

```json
{
  "candidates": [{
    "content": {
      "parts": [{
        "inlineData": {
          "mimeType": "image/jpeg",
          "data": "/9j/4AAQSkZJRgABAQ..."
        }
      }],
      "role": "model"
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 0,
    "candidatesTokenCount": 0,
    "totalTokenCount": 0
  },
  "modelVersion": "gemini-3.1-flash-lite-image",
  "responseId": "2c5b905d-63a0-4bb6-8b54-e39980b30e61"
}
```

图片读取路径：

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

响应头还会返回：

```http
X-Task-Id: 2c5b905d-63a0-4bb6-8b54-e39980b30e61
X-Billing-Amount: 0.0525
Idempotency-Replayed: false
```

## 7. Python 完整示例

```python
import base64
import requests

API_KEY = "pbg_YOUR_API_KEY"
MODEL = "gemini-3.1-flash-lite-image"
URL = f"https://nano.own-jarvis.com/v1beta/models/{MODEL}:generateContent"

response = requests.post(
    URL,
    headers={
        "x-goog-api-key": API_KEY,
        "Idempotency-Key": "google-order-20260807-0001",
    },
    json={
        "contents": [{
            "role": "user",
            "parts": [{"text": "A pale green ceramic cup, minimal product photo"}],
        }],
        "generationConfig": {
            "responseModalities": ["TEXT", "IMAGE"],
            "imageConfig": {"aspectRatio": "1:1", "imageSize": "1K"},
        },
    },
    timeout=650,
)
response.raise_for_status()
data = response.json()

inline = data["candidates"][0]["content"]["parts"][0]["inlineData"]
extension = "jpg" if inline["mimeType"] == "image/jpeg" else inline["mimeType"].split("/")[-1]
with open(f"result.{extension}", "wb") as file:
    file.write(base64.b64decode(inline["data"]))

print("responseId:", data["responseId"])
```

## 8. 幂等、超时和计费

- 客户端 HTTP 超时请设为至少 650 秒。
- 每次请求只生成 1 张图片，`candidateCount` 只能省略或传 `1`。
- 每个业务请求必须使用唯一且稳定的 `Idempotency-Key`。
- 如果客户端超时、连接中断或未收到完整响应，必须复用原来的幂等 Key。
- 如果接口明确提示“系统已自动退回积分；请使用新的 Idempotency-Key”，说明本次任务已经确认失败；重新生成时应换一个新 Key。
- 幂等重放不会重复生成或重复扣费。
- 请求提交后预扣积分，成功后结算，确认失败后自动退回积分。

## 9. 错误格式

```json
{
  "error": {
    "code": 400,
    "message": "contents 必须是非空数组",
    "status": "INVALID_ARGUMENT"
  }
}
```

| HTTP | `status` | 处理建议 |
|---:|---|---|
| 400 | `INVALID_ARGUMENT` | 检查 contents、parts、模型、比例和清晰度 |
| 401 | `UNAUTHENTICATED` | 检查 `x-goog-api-key` |
| 402/429 | `RESOURCE_EXHAUSTED` | 充值或降低请求频率 |
| 403 | `PERMISSION_DENIED` | 联系管理员检查账号状态 |
| 502/503 | `UNAVAILABLE` | 按错误信息处理；若已自动退回积分，换新幂等 Key 重新生成 |
| 504 | `DEADLINE_EXCEEDED` | 任务仍在处理中，复用原幂等 Key 查询式重试 |