# Gemini API 调用教程：generateContent、OpenAI Python SDK 与流式

> 通过 Passion8 调用 Gemini API：原生 generateContent curl、OpenAI 兼容 Python SDK 与流式示例，说明 API Key、模型和两种 Base URL 的区别。

URL: https://docs.passion8.cc/docs/gemini/api
Language: zh-CN
Publisher: Passion8
Last updated: 2026-10-11

Gemini 可以通过原生 Gemini 协议或 OpenAI 兼容协议接入本站。两者都使用 Passion8 Key 与控制台开放的模型，不需要申请 Google 账号或 Google API Key。

## 选择协议

| 客户端 | 地址 | 请求格式 |
| --- | --- | --- |
| Gemini CLI / 原生 Gemini 请求 | `https://passion8.cc` | `/v1beta/models/{model}:generateContent` |
| Cline OpenAI Compatible / OpenAI SDK | `https://passion8.cc/v1` | `/chat/completions` |

Google 官方 OpenAI 兼容入口使用自己的路径，但本站兼容入口就是 `/v1`，不要把 Google 示例地址拼接到本站。

## 准备环境变量

macOS / Linux：

```bash
export PASSION8_API_KEY="replace-with-your-Passion8-key"
export PASSION8_GEMINI_MODEL="replace-with-an-enabled-Gemini-model-ID"
```

Windows PowerShell：

```powershell
$env:PASSION8_API_KEY="replace-with-your-Passion8-key"
$env:PASSION8_GEMINI_MODEL="replace-with-an-enabled-Gemini-model-ID"
```

从控制台复制完整模型 ID。SDK 中的环境变量是本文约定，不会自动修改 Gemini CLI；CLI 的变量名见 [安装配置](https://docs.passion8.cc/docs/gemini)。

## 原生 Gemini：一次最小请求

macOS / Linux 使用：

```bash
curl --fail-with-body \
  "https://passion8.cc/v1beta/models/${PASSION8_GEMINI_MODEL}:generateContent" \
  -H "x-goog-api-key: $PASSION8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Reply only OK."}]}]}'
```

正常文本位于响应的 `candidates[].content.parts[].text`。如果没有文本，先检查错误正文或 finish reason，不要把空候选结果当成连接成功。

## OpenAI 兼容：Python SDK

在自己的项目虚拟环境中安装 SDK：

```bash
python -m pip install --upgrade openai
```

保存下面代码为 `gemini_smoke.py`，然后执行 `python gemini_smoke.py`：

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["PASSION8_API_KEY"],
    base_url="https://passion8.cc/v1",
)

response = client.chat.completions.create(
    model=os.environ["PASSION8_GEMINI_MODEL"],
    messages=[{"role": "user", "content": "Reply only OK."}],
)
print(response.choices[0].message.content)
```

此请求使用 OpenAI 兼容协议，不读取 Gemini CLI 配置。先确认普通请求返回，再测试流式、图片或工具；兼容协议并不保证覆盖所有原生 Gemini 字段。

### 流式输出

将请求部分替换为：

```python
stream = client.chat.completions.create(
    model=os.environ["PASSION8_GEMINI_MODEL"],
    messages=[{"role": "user", "content": "Explain this project in three sentences."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
print()
```

生产程序需要按实际 SDK 错误类型处理鉴权、限流和超时。`401` 时检查 Key，`429` 时查看错误说明和重试指引；不要持续重试错误模型 ID。

## 验证结果与功能边界

在 Passion8 控制台核对请求时间、模型和计费。图片、结构化输出、函数调用、搜索与缓存是不同功能，需逐项验证。Google 托管 Grounding / 搜索的官方文档不能直接作为本站每个渠道的功能承诺。

编程插件接入见 [VS Code 使用 Gemini](https://docs.passion8.cc/docs/gemini/vscode)，实际任务见 [编程工作流](https://docs.passion8.cc/docs/gemini/workflow)。

## API 接入问答

### Gemini 原生 API 和 OpenAI 兼容 API 的 Key 可以一样吗？

两种协议都填写本站 Key，不需要 Google API Key；能否使用同一令牌访问所选模型，仍以令牌权限为准。原生请求用 `x-goog-api-key` 和 `https://passion8.cc/v1beta/models/{model}:generateContent`；OpenAI SDK 用 Bearer 鉴权和 `https://passion8.cc/v1` Base URL。不要混用路径和请求体。

### 用 OpenAI SDK 能直接复制所有 Google 官方示例吗？

不能直接复制原生 `contents`、`parts` 请求体到 Chat Completions。OpenAI 兼容请求使用 `messages`；原生请求使用 `contents`。图片、工具、搜索和缓存应按当前协议与本站渠道分别确认。

## 核对来源

核对日期：2026-10-11。

- [Gemini OpenAI compatibility](https://ai.google.dev/gemini-api/docs/openai)
- [Gemini generateContent API](https://ai.google.dev/api/generate-content)
- [Gemini CLI configuration](https://geminicli.com/docs/reference/configuration/)