---
title: "模型与协议"
description: "pirouter 上的每个模型有一个 vendor/model 形式的 ID，并接受三种协议中的一种或几种。本页说明 ID 怎么写、模型接受哪些协议，以及协议不匹配时返回什么。"
canonical: "https://pirouter.ai/zh/docs/models"
last-updated: "2026-10-13"
lang: "zh"
source: "content/docs/zh/(start)/models.mdx"
---

# 模型与协议

pirouter 上的每个模型有一个 vendor/model 形式的 ID，并接受三种协议中的一种或几种。本页说明 ID 怎么写、模型接受哪些协议，以及协议不匹配时返回什么。

pirouter 上的每个模型有一个 ID，并接受一种或几种协议。调用时两样都要对上：ID 写对，协议选对。

## 模型 ID

模型 ID 的写法是 `vendor/model`，由厂商名和模型名组成，中间一个斜杠。

取全部模型的列表不需要 key：

```bash
$ curl https://api.pirouter.ai/v1/models
```

你应该看到一个 `data` 数组，每一项的 `id` 就是调用时要写的模型 ID。

网关不认识的名字返回 `404` 和错误码 `model_not_found`。

### 别名

一个模型可以有别名，通常是不带厂商前缀的名字。别名和完整 ID 的效果相同。

网关先按完整 ID 查找，找不到再按别名查找。别名必须和登记的写法完全一致：区分大小写，不做前缀补全，也不做模糊匹配。无论用哪个名字调用，日志和账单里记的都是完整 ID。

一个模型有哪些别名，看 `GET /v1/models/{vendor}/{model}/endpoints` 返回的 `aliases`。

## 三种协议

| 协议        | 端点                                                                                                |
| --------- | ------------------------------------------------------------------------------------------------- |
| OpenAI    | `POST /v1/chat/completions`、`POST /v1/responses`、`POST /v1/images/generations`                    |
| Anthropic | `POST /v1/messages`                                                                               |
| Gemini    | `POST /v1beta/models/{model}:generateContent`、`POST /v1beta/models/{model}:streamGenerateContent` |

所有端点都在 `https://api.pirouter.ai` 下。

OpenAI 和 Anthropic 协议把模型 ID 写在请求体的 `model` 字段里，用 `stream` 字段开启流式。Gemini 协议把模型 ID 写在路径里，用 `streamGenerateContent` 这个动作表示流式。

## 每个模型接受哪些协议

网关不做协议转换。一个模型只能用它接受的协议调用。有的模型只接受一种协议，有的同时接受 OpenAI 协议和厂商自己的协议。下面是几个例子：

| 模型 ID                         | OpenAI | Anthropic | Gemini |
| ----------------------------- | ------ | --------- | ------ |
| `openai/gpt-6-sol`            | 支持     | 不支持       | 不支持    |
| `anthropic/claude-sonnet-5.5` | 支持     | 支持        | 不支持    |
| `google/gemini-3.5-flash`     | 支持     | 不支持       | 支持     |
| `google/gemini-3-pro-image`   | 不支持    | 不支持       | 支持     |
| `bytedance/seed-2.1-pro`      | 不支持    | 支持        | 不支持    |

- [浏览全部模型](https://pirouter.ai/zh/models): 每个模型的详情页列出它接受的协议、价格和上游。

用 API 查某个模型，看 `GET /v1/models/{vendor}/{model}/endpoints` 返回的 `protocols`。

一种协议下有多个端点，模型不一定每个都提供。生图模型提供 `POST /v1/images/generations` 和 Gemini 协议的 `generateContent`，不提供 chat 端点。同一个响应里的 `supported_endpoints` 列出该模型提供的端点；列表为空表示它接受的协议下每个端点都能调用。

## 协议不匹配

用一个模型不接受的协议调用它，或者调用它不提供的端点，返回 `422` 和错误码 `validation_failed`，`message` 里列出这个模型提供的端点。请求在网关就被拒绝，不会转发给任何 provider，也不计费。

```json
{
  "error": {
    "message": "This model is not served on the endpoint you called. Call it on POST /v1/images/generations or POST /v1beta/models/{model}:generateContent.",
    "type": "invalid_request_error",
    "code": "validation_failed"
  }
}
```

遇到这个错误，换到 `message` 列出的端点，或者换一个提供当前端点的模型。

## 每种协议怎么调

三组示例各用了一个接受该协议的模型，可以直接运行。

### OpenAI 协议

SDK 的 base URL 填 `https://api.pirouter.ai/v1`。

cURL:

```bash
curl https://api.pirouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $PIROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-6-sol",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'
```

Python:

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.pirouter.ai/v1",
    api_key=os.environ["PIROUTER_API_KEY"],
)

completion = client.chat.completions.create(
    model="openai/gpt-6-sol",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(completion.choices[0].message.content)
```

TypeScript:

```ts
import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://api.pirouter.ai/v1',
  apiKey: process.env.PIROUTER_API_KEY,
})

const completion = await client.chat.completions.create({
  model: 'openai/gpt-6-sol',
  messages: [{ role: 'user', content: 'Hello!' }],
})
console.log(completion.choices[0].message.content)
```

要流式输出，在请求体里加 `"stream": true`。请求和返回的样子见[流式输出](https://pirouter.ai/zh/docs/quickstart.md#流式输出)。

### Anthropic 协议

SDK 的 base URL 填 `https://api.pirouter.ai`，不带 `/v1`，SDK 会自己拼上。

cURL:

```bash
curl https://api.pirouter.ai/v1/messages \
  -H "x-api-key: $PIROUTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'
```

Python:

```python
import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.pirouter.ai",
    api_key=os.environ["PIROUTER_API_KEY"],
)

message = client.messages.create(
    model="anthropic/claude-sonnet-5.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)
```

TypeScript:

```ts
import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  baseURL: 'https://api.pirouter.ai',
  apiKey: process.env.PIROUTER_API_KEY,
})

const message = await client.messages.create({
  model: 'anthropic/claude-sonnet-5.5',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }],
})
console.log(message.content[0].text)
```

要流式输出，在请求体里加 `"stream": true`，并给 curl 加 `-N`：

```bash
curl -N https://api.pirouter.ai/v1/messages \
  -H "x-api-key: $PIROUTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "stream": true,
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'
```

你应该看到 SSE 事件成对到达，一行 `event: `，一行 `data: `。第一个事件是 `message_start`，最后一个是 `message_stop`。

### Gemini 协议

SDK 的 base URL 填 `https://api.pirouter.ai`，SDK 会自己拼上 `/v1beta`。创建客户端时还要通过 `http_options`（TypeScript 是 `httpOptions`）的 `headers` 加上 `Authorization: Bearer` 请求头，否则请求返回 `401`。原因见[鉴权与 API key](https://pirouter.ai/zh/docs/authentication.md#在请求里带上-key)。

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

要流式输出，把 `generateContent` 换成 `streamGenerateContent`。请求体不变，不需要 `stream` 字段：

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

你应该看到 SSE 事件，每个事件是一行 `data: `，在 `candidates` 里带一段回答。最后一个事件带 `finishReason` 和 `usageMetadata` 里的 token 用量，之后没有单独的结束标记。

## 能力标记

每个模型带一组能力标记，说明它支持什么。常用的几个：

| 能力    | 标记                                                       | 含义                                            |
| ----- | -------------------------------------------------------- | --------------------------------------------- |
| 工具调用  | `supports_function_calling`                              | 可以调用工具和函数                                     |
| 结构化输出 | `supports_structured_outputs`、`supports_response_schema` | 按 JSON schema 约束输出；JSON 格式的 `response_format` |
| 视觉    | `supports_vision`                                        | 接受图像输入                                        |
| 缓存    | `supports_prompt_caching`                                | 支持提示词缓存                                       |
| 推理    | `supports_reasoning`                                     | 支持扩展思考，产生推理 token                             |

一个模型有哪些标记，看 `GET /v1/models/{vendor}/{model}/endpoints` 返回的 `capabilities`。

## 下一步

- [定价与计费](https://pirouter.ai/zh/docs/billing.md): 每类 token 怎么计价，钱包怎么扣费。
- [API 参考](https://pirouter.ai/zh/docs/api.md): 每种协议背后的端点。