---
description: "Gemini 原生 generateContent 与流式接口的透明代理，支持参考图与流式输出。"
---

# Gemini 原生接口

> 端点: `POST https://oneapi.zaiwenai.com/v1beta/models/{model}:generateContent`
>
> 端点: `POST https://oneapi.zaiwenai.com/v1beta/models/{model}:streamGenerateContent`
>
> 在问 OneAPI 对 Gemini 原生协议做透明代理，原样转发请求与响应，支持所有 `generateContent` 格式的 Gemini 模型（文本、图像、语音均可）。

与 OpenAI 兼容的 `POST /v1/images/generations` 按次计费不同，Gemini 图像生成通过原生接口按 **Token 计费**，并支持参考图、流式等完整能力。

| 能力 | 推荐端点 | 模型示例 |
|------|----------|----------|
| 文生图 | `POST /v1beta/models/{model}:generateContent` | `gemini-3.1-flash-image`、`gemini-2.5-flash-image`、`gemini-3-pro-image` |
| 图生图 / 参考图 | 同上（`parts` 中附加 `inlineData`） | `gemini-3.1-flash-image` |
| 流式生成 | `POST /v1beta/models/{model}:streamGenerateContent` 或 `?alt=sse` | 同上 |
| 文本 / 语音 | 同上 | `gemini-3-flash`、`gemini-3.1-flash-tts-preview` 等 |

## 认证

三种写法等价，填写的始终是在问 API Key，不是 Google API Key：

```bash
# 1. 标准 Bearer（推荐）
-H "Authorization: Bearer $YOUR_API_KEY"

# 2. Google 风格请求头
-H "x-goog-api-key: $YOUR_API_KEY"

# 3. 查询参数
https://oneapi.zaiwenai.com/v1beta/models/gemini-3.1-flash-image:generateContent?key=$YOUR_API_KEY
```

## 文生图

最简请求只需 `contents[].parts[].text` + `generationConfig.responseModalities`：

```bash
curl -X POST \
  "https://oneapi.zaiwenai.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "Generate an image: a cute orange cat sitting on a windowsill, photorealistic, 16:9"}]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE", "TEXT"]
    }
  }'
```

**关键参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `contents` | array | 是 | 对话内容，`role: user`，`parts: [{text}]` |
| `contents[].parts[].text` | string | 是 | 提示词，支持中英文 |
| `generationConfig.responseModalities` | array | 是 | 必须包含 `"IMAGE"`，建议 `["IMAGE","TEXT"]`，否则只返回文本 |
| `generationConfig.responseModalities` | array | - | 如需文本辅助说明，保留 `TEXT` |
| `safetySettings` / `generationConfig.temperature` 等 | - | 否 | Gemini 原生可选参数，原样透传 |

**响应：**

```json
{
  "candidates": [{
    "content": {
      "parts": [
        {"text": ""},
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQEBLAEsAAD..."
          },
          "thoughtSignature": "..."
        }
      ],
      "role": "model"
    },
    "finishReason": "STOP"
  }],
  "usageMetadata": {
    "promptTokenCount": 271,
    "candidatesTokenCount": 1554,
    "totalTokenCount": 1825
  },
  "modelVersion": "gemini-3.1-flash-image"
}
```

图像在 `candidates[0].content.parts[].inlineData.data`，为 Base64 编码，需自行解码保存；`mimeType` 通常为 `image/jpeg` 或 `image/png`。

### Python 示例（文生图）

```python
import base64
import json
import urllib.request
from pathlib import Path

url = "https://oneapi.zaiwenai.com/v1beta/models/gemini-3.1-flash-image:generateContent"
headers = {
    "Authorization": "Bearer $YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "contents": [{"role": "user", "parts": [{"text": "一只橘猫坐在窗台上，写实摄影，16:9"}]}],
    "generationConfig": {"responseModalities": ["IMAGE", "TEXT"]},
}

req = urllib.request.Request(url, data=json.dumps(payload).encode(), headers=headers)
with urllib.request.urlopen(req, timeout=90) as resp:
    data = json.loads(resp.read())
    part = next(p for p in data["candidates"][0]["content"]["parts"] if "inlineData" in p)
    Path("output.jpg").write_bytes(base64.b64decode(part["inlineData"]["data"]))
    print("已保存 output.jpg", data["usageMetadata"])
```

或使用 `httpx` / `requests` 同理，平台仅做字节级透传，不改写 JSON。

## 参考图 / 图生图

在 `parts` 中追加一个 `inlineData` 即可实现参考图生成（图生图、风格迁移、局部重绘均同此格式）：

```bash
# 1. 将参考图转为 Base64
IMG_B64=$(base64 -i reference.jpg)

curl -X POST \
  "https://oneapi.zaiwenai.com/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\": [{
      \"role\": \"user\",
      \"parts\": [
        {\"text\": \"请参考这张图，生成吉卜力风格插画，保持主体构图，温暖治愈\"},
        {\"inlineData\": {\"mimeType\": \"image/jpeg\", \"data\": \"$IMG_B64\"}}
      ]
    }],
    \"generationConfig\": {\"responseModalities\": [\"IMAGE\", \"TEXT\"]}
  }"
```

```python
import base64
from pathlib import Path

img_b64 = base64.b64encode(Path("reference.jpg").read_bytes()).decode()
payload = {
    "contents": [{
        "role": "user",
        "parts": [
            {"text": "请参考这张图，生成吉卜力风格插画，保持主体"},
            {"inlineData": {"mimeType": "image/jpeg", "data": img_b64}}
        ]
    }],
    "generationConfig": {"responseModalities": ["IMAGE", "TEXT"]},
}
# 同上发送，响应中 inlineData 即为新图
```

支持 `image/jpeg` / `image/png` / `image/webp`，建议单张参考图 < 2MB。多张参考图可在 `parts` 中追加多个 `inlineData`。

## 流式生成

```bash
# 方式一：专用流式端点
curl -X POST \
  "https://oneapi.zaiwenai.com/v1beta/models/gemini-3.1-flash-image:streamGenerateContent" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Generate an image: a blue bird"}]}],"generationConfig":{"responseModalities":["IMAGE","TEXT"]}}'

# 方式二：非流式端点 + alt=sse（兼容 Google SDK）
curl -X POST \
  "https://oneapi.zaiwenai.com/v1beta/models/gemini-3.1-flash-image:generateContent?alt=sse" \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -d '{...}'
```

流式响应为 `Content-Type: text/event-stream`，每行 `data: {...}`，最后一个 `data` 包含 `usageMetadata` 与完整的 `inlineData`。非流式与流式计费口径一致。

### Python 流式示例

```python
import httpx, json, base64

with httpx.stream("POST",
    "https://oneapi.zaiwenai.com/v1beta/models/gemini-3.1-flash-image:streamGenerateContent",
    headers={"Authorization": "Bearer $YOUR_API_KEY", "Content-Type": "application/json"},
    json={"contents":[{"parts":[{"text":"a cat"}]}],"generationConfig":{"responseModalities":["IMAGE","TEXT"]}},
    timeout=90) as r:
    for line in r.iter_lines():
        if line.startswith("data:"):
            data = json.loads(line[5:])
            if "candidates" in data:
                # 最后一个 chunk 包含 inlineData
                pass
```

## 响应与计费

平台强制按 **Token 计费**，依赖上游 `usageMetadata`：

```
input_tokens  = promptTokenCount + toolUsePromptTokenCount
output_tokens = candidatesTokenCount + thoughtsTokenCount
cost = input_tokens * input_price/1M + output_tokens * output_price/1M
```

- 后台建模型时 `billing_unit` 必须为 `token`（`model_type` 可为 `chat` / `image` 任意，通用校验仅检查 `billing_unit`）
- 成功响应必含 `usageMetadata`，缺失会返回 `502 missing_usage_metadata`
- `candidatesTokenCount` 已包含图像 tokens，图文统一口径
- 余额不足返回 `402 insufficient_balance`，上游无可用账号返回 `503`，模型不存在返回 `404`

## 错误码

| HTTP | code | 说明 |
|------|------|------|
| 400 | `invalid_json` | 请求体不是合法 JSON |
| 402 | `insufficient_balance` | 余额不足 |
| 404 | `model_not_found` | 模型未配置或未启用 |
| 500 | `model_billing_misconfigured` | 模型未配置为 `token` 计费 |
| 502 | `missing_usage_metadata` | 上游成功响应缺 `usageMetadata` |
| 503 | `upstream_not_configured` / `No available Gemini accounts` | `GEMINI_RELAY` 未配置或账号池耗尽 |

## 与 OpenAI 图片接口的区别

| 对比 | `POST /v1/images/generations` | `POST /v1beta/models/{model}:generateContent` |
|------|-------------------------------|-----------------------------------------------|
| 协议 | OpenAI 兼容 | Gemini 原生，透明代理 |
| 计费 | 按次 `REQUEST` | 按 Token `TOKEN` |
| 参考图 | `POST /v1/images/edits` 需 `multipart/form-data` | 同一接口 `parts[].inlineData` 追加即可 |
| 流式 | 不支持 | 支持 `streamGenerateContent` / `?alt=sse` |
| 模型 | `gpt-image-2` 等 | `gemini-3.1-flash-image`、`gemini-2.5-flash-image`、`gemini-3-pro-image` 等 |

如需 OpenAI 生态兼容，继续使用 `POST /v1/images/generations`；如需 Gemini 完整能力（参考图、流式、Token 计费），使用本接口。