---
title: "生成内容"
description: "生成内容（Gemini 协议，单次响应）。"
canonical: "https://pirouter.ai/zh/docs/api/generate-content"
last-updated: "2026-10-13"
lang: "zh"
---

# 生成内容

生成内容（Gemini 协议，单次响应）。

`POST https://api.pirouter.ai/v1beta/models/{model}:generateContent`

兼容 Gemini 的 generateContent。模型和是否流式都由路径决定，请求体里两者都不写。一个模型只能用它登记接受的协议调用；用它不接受的协议调用，返回 `validation_failed`（422）。该路径始终返回单个 JSON 响应体；请求体里的 `stream` 键不会被读取。平台只读取请求 schema 里列出的字段；其他字段（`generationConfig`、`tools` 等）全部原样转发给上游 provider。

key 放在 `Authorization` 或 `X-Api-Key` 请求头里。平台不读取 `x-goog-api-key` 请求头和 `key` 查询参数。

## 鉴权

用下面任一请求头传 API key。

| 请求头 | 值 | 说明 |
| --- | --- | --- |
| `Authorization` | `Bearer sk-pi-…` | 平台签发的 API key，以 `sk-pi-` 开头，作为 Bearer token 发送。 |
| `X-Api-Key` | `sk-pi-…` | 同一个平台签发的 `sk-pi-` key，放在 `X-Api-Key` 请求头里发送。只有 `Authorization` 缺失或为空时才读取这个请求头；两个都带时，以 `Authorization` 为准。两个请求头都接受不带 `Bearer ` 前缀的裸 key。 |

## 路径参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 平台的模型 ID，格式为 `vendor/model`。斜杠是值的一部分，不做转义直接发送：这一段从 `/v1beta/models/` 之后开始，到动作前的冒号为止。对不带厂商前缀的模型名，平台不会猜测厂商。 |

## 请求体

`application/json`

Gemini generateContent 请求，流式路径和单次响应路径共用。模型和是否流式由路径决定，所以请求体里两者都不写；协议的其余字段原样转发给上游。

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `contents` | object[] | 是 | 对话内容，结构由协议定义。原样转发。 |

## 响应

`200` `application/json`

生成结果，结构由 Gemini 协议定义；响应体来自上游，原样透传。

## 错误

| 状态码 | 错误码 | 说明 |
| --- | --- | --- |
| `401` | `invalid_api_key`, `api_key_not_found`, `api_key_revoked`, `api_key_expired` | API key 缺失或格式错误（`invalid_api_key`）、不存在（`api_key_not_found`）、已吊销（`api_key_revoked`）或已过期（`api_key_expired`）。 |
| `402` | `insufficient_balance` | 钱包余额不足以支付这次调用（`insufficient_balance`）。 |
| `404` | `model_not_found`, `no_eligible_provider` | 所请求的模型 ID 不存在或未启用（`model_not_found`）；或者请求的 `provider` 偏好与工作区路由设置合并后，没有 provider 能提供该模型（`no_eligible_provider`，`error.metadata` 里带有路由筛选漏斗）。 |
| `422` | `validation_failed` | 请求未通过校验（`validation_failed`）：该模型不在本端点提供（错误信息会列出它提供的端点），或者某个路由字段（`provider`、`models`、`route`、`preset`）不符合规则。错误信息会指出原因。 |
| `429` | `rate_limited` | 请求因限流被拒绝（`rate_limited`）。 |
| `500` | `internal_error` | 其他失败：没有健康的上游可以处理请求时返回 `provider_unavailable`（503）；平台侧出现意外故障时返回 `internal_error`（500）。 |
| `503` | `provider_unavailable` | 其他失败：没有健康的上游可以处理请求时返回 `provider_unavailable`（503）；平台侧出现意外故障时返回 `internal_error`（500）。 |

错误体

```json
{
  "error": {
    "message": "No such model. Model names are vendor-qualified (vendor/model), so a name copied from a provider's own docs needs its vendor prefix added. Call GET /v1/models for the slugs this gateway serves.",
    "type": "not_found_error",
    "code": "model_not_found"
  }
}
```

## 响应头

每个响应头后面列出它会出现在哪些状态码的响应里。

| 响应头 | 出现于 | 说明 |
| --- | --- | --- |
| `X-Pi-Trace-Id` | `200`, `401`, `402`, `404`, `422`, `429`, `default` | 平台请求 id，由网关生成。推理端点的每个响应都带；反馈问题时请附上它。 |
| `Access-Control-Allow-Origin` | `200`, `401`, `402`, `404`, `422`, `429`, `default` | 恒为 `*`。凭证是携带 API key 的请求头，从不是 cookie。 |
| `Access-Control-Expose-Headers` | `200`, `401`, `402`, `404`, `422`, `429`, `default` | 列出每一个 `X-Pi-*` 响应头，外加 `Retry-After` 与 `Content-Encoding`，让浏览器里的代码能读到它们。 |
| `X-Pi-Provider` | `200`, `default` | 处理这次响应的 provider，取值与 `provider.order`、`GET /v1/models/{vendor}/{model}/endpoints` 同一套词表。只有上游 provider 作出应答时才有（一次补全或一次上游错误）；发生 fallback 后是接手的那个 provider。 |
| `X-Pi-Model` | `200`, `default` | 处理这次响应的模型 slug，与响应体里的 `model` 是同一个值。由 fallback 模型接手时就是那个模型。只有上游 provider 作出应答时才有。 |
| `X-Pi-Upstream-Model` | `200`, `default` | 上游 provider 在它自己的响应里报告的完整模型 id，原样透传（流式时取自第一个数据事件）。上游响应没有给出模型时不带这个头；不会用平台自己的记录补上。 |
| `X-Pi-Upstream-Request-Id` | `200`, `default` | 上游 provider 自己的请求 id，原样透传，用于在 provider 一侧查这次调用。provider 没有返回时不带这个头。 |

## 请求示例

cURL

```bash
curl "https://api.pirouter.ai/v1beta/models/google/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer $PIROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "Hello!" }] }]
  }'
```

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)
```

## 响应示例

`200` `application/json`

```json
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "thoughtSignature": "AY89a1+yAqWtkVQA...",
            "text": "Hello! How can I help you today?"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP"
    }
  ],
  "modelVersion": "google/gemini-3.5-flash",
  "responseId": "D6PMaqCYJd2nq8YP95ikiAg",
  "usageMetadata": {
    "promptTokenCount": 2,
    "candidatesTokenCount": 9,
    "thoughtsTokenCount": 184,
    "totalTokenCount": 195
  }
}
```