---
title: "Google GenAI SDK"
description: "用 Google GenAI 官方 SDK（Python 与 TypeScript）调用 pirouter，base URL 填 https://api.pirouter.ai，并另加 Authorization: Bearer 请求头，因为网关不读 SDK 默认的 x-goog-api-key。本页说明怎么安装、配置、验证，以及常见报错怎么处理。"
canonical: "https://pirouter.ai/zh/docs/integrations/google-genai-sdk"
last-updated: "2026-10-17"
lang: "zh"
source: "content/docs/zh/integrations/google-genai-sdk.mdx"
---

# Google GenAI SDK

用 Google GenAI 官方 SDK（Python 与 TypeScript）调用 pirouter，base URL 填 https://api.pirouter.ai，并另加 Authorization: Bearer 请求头，因为网关不读 SDK 默认的 x-goog-api-key。本页说明怎么安装、配置、验证，以及常见报错怎么处理。

Google GenAI 官方 SDK 不需要插件就能调用 pirouter：创建客户端时改 base URL、另加一个请求头，其余代码不用改。

## 前提

- 一把 pirouter API key。还没有的话，按[快速开始](https://pirouter.ai/zh/docs/quickstart.md)创建一个，并存进环境变量：

```bash
export PIROUTER_API_KEY="sk-pi-..."
```

- Python 3.10 及以上，或 Node.js 20 及以上。
- 安装 SDK：

Python:

```bash
pip install google-genai
```

TypeScript:

```bash
pnpm add @google/genai
```

TypeScript 示例用了顶层 `await`，把文件存成 `.mjs`，或者在 `package.json` 里设 `"type": "module"`。

## 配置

创建客户端时设三项：

- base URL 填 `https://api.pirouter.ai`，不带 `/v1beta`，SDK 会自己拼上。Python 写在 `http_options` 的 `base_url` 里，TypeScript 写在 `httpOptions` 的 `baseUrl` 里。不要设置 `api_version`（TypeScript 是 `apiVersion`），保持 SDK 默认的 `v1beta`。
- 在同一处的 `headers` 里加 `Authorization: Bearer` 请求头，值是你的 pirouter key。
- `api_key`（TypeScript 是 `apiKey`）也传同一把 pirouter key，SDK 要求有这一项。

网关只提供 `/v1beta/models/{model}:generateContent` 和 `:streamGenerateContent` 两个动作。

必须另加 `Authorization` 头，是因为 SDK 默认把 key 放在 `x-goog-api-key` 请求头里发出，网关不读这个头，只认 `Authorization` 和 `x-api-key`。SDK 照样会发 `x-goog-api-key`，网关在入站时把它去掉，不会转发给上游。

Python:

```python
import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["PIROUTER_API_KEY"],
    http_options=types.HttpOptions(
        base_url="https://api.pirouter.ai",
        headers={"Authorization": f"Bearer {os.environ['PIROUTER_API_KEY']}"},
    ),
)

response = client.models.generate_content(
    model="google/gemini-3.5-flash",
    contents="Hello!",
)
print(response.text)
```

TypeScript:

```ts
import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({
  apiKey: process.env.PIROUTER_API_KEY,
  httpOptions: {
    baseUrl: 'https://api.pirouter.ai',
    headers: { Authorization: `Bearer ${process.env.PIROUTER_API_KEY}` },
  },
})

const response = await ai.models.generateContent({
  model: 'google/gemini-3.5-flash',
  contents: 'Hello!',
})
console.log(response.text)
```

模型 ID 直接写 `google/gemini-3.5-flash` 这样的全名。SDK 把它拼进路径，网关取 `models/` 之后、最后一个冒号之前的全部内容作模型 ID，中间的斜杠保留。

能用哪些模型，见[模型与协议](https://pirouter.ai/zh/docs/models.md#每个模型接受哪些协议)的协议表里 Gemini 一列。

请求头没法靠环境变量加上，所以这个 SDK 只用代码里的写法配置。

### 流式输出

Python 用 `generate_content_stream`，TypeScript 用 `generateContentStream`，SDK 把请求发到 `:streamGenerateContent`：

Python:

```python
import os
from google import genai
from google.genai import types

client = genai.Client(
    api_key=os.environ["PIROUTER_API_KEY"],
    http_options=types.HttpOptions(
        base_url="https://api.pirouter.ai",
        headers={"Authorization": f"Bearer {os.environ['PIROUTER_API_KEY']}"},
    ),
)

for chunk in client.models.generate_content_stream(
    model="google/gemini-3.5-flash",
    contents="Hello!",
):
    print(chunk.text or "", end="", flush=True)
print()
```

TypeScript:

```ts
import { GoogleGenAI } from '@google/genai'

const ai = new GoogleGenAI({
  apiKey: process.env.PIROUTER_API_KEY,
  httpOptions: {
    baseUrl: 'https://api.pirouter.ai',
    headers: { Authorization: `Bearer ${process.env.PIROUTER_API_KEY}` },
  },
})

const stream = await ai.models.generateContentStream({
  model: 'google/gemini-3.5-flash',
  contents: 'Hello!',
})
for await (const chunk of stream) {
  process.stdout.write(chunk.text ?? '')
}
console.log()
```

你应该看到回复一段一段地打印出来。

## 验证

把上面的示例存成 `main.py` 或 `main.mjs`，然后运行：

Python:

```bash
python main.py
```

TypeScript:

```bash
node main.mjs
```

你应该看到模型的一句回复。

打开控制台的 **日志**，请求发出后几秒，这次请求出现在列表里，**端点** 一栏是这次调用的路径，以 `:generateContent` 结尾。日志详情里的 **Trace ID** 与这次响应的 `X-Pi-Trace-Id` 响应头是同一个值。

## 排障

### 401 invalid\_api\_key

返回 `401`，错误码 `invalid_api_key`，`message` 是 "You didn't provide an API key. Provide it in an Authorization header using Bearer auth (Authorization: Bearer YOUR\_KEY)."：最常见的原因是漏了 `Authorization` 请求头，只靠 SDK 默认的 `x-goog-api-key`。按上面的配置在 `headers` 里加上它。头里的值不是以 `sk-pi-` 开头的 pirouter key，也是这个返回。

### 400 model is required

返回 `400`，错误码 `invalid_request`，`message` 是 `model is required`：base URL 多半填成了 `https://api.pirouter.ai/v1beta`，或者设了 `api_version`。这时请求的路径不是网关提供的端点，网关从中取不到模型。base URL 填 `https://api.pirouter.ai`，并去掉 `api_version`。

### 422 validation\_failed

返回 `422`，错误码 `validation_failed`，`message` 以 "This model is not served on the endpoint you called." 开头：这个模型不接受 Gemini 协议，例如 `anthropic/claude-sonnet-5.5`。`message` 后半句列出它提供的端点。换一个协议表里 Gemini 一列为「支持」的模型，或者改用 [OpenAI SDK](https://pirouter.ai/zh/docs/integrations/openai-sdk.md)。

## 目前没有验证的用法

- 网关只提供 `generateContent` 与 `streamGenerateContent`。`countTokens` 目前没有，调用返回 `400` 和 `model is required`。
- `embedContent`、`batchGenerateContent`、Files 文件上传与 Live API 目前都没有。