# 协议 (/docs/zh-CN/api/protocols)

任何对话模型都可以通过四种对话协议中的任意一种调用。所以用 OpenAI SDK 调 Claude、用 Google Gen AI SDK 调 GPT，都只需改模型 ID。你的 SDK 或工具已经在用哪种协议，就选哪种：

| 你在用 | 调用 | 页面 |
|---|---|---|
| OpenAI SDK、Vercel AI SDK、LangChain、opencode、Cursor | `POST /v1/chat/completions` | [Chat Completions](/docs/zh-CN/api/chat-completions) |
| Codex、OpenAI SDK 的 `client.responses` | `POST /v1/responses` | [Responses](/docs/zh-CN/api/responses) |
| Anthropic SDK、Claude Code | `POST /v1/messages` | [Messages](/docs/zh-CN/api/messages) |
| Google Gen AI SDK | `POST /v1/models/{model}:generateContent` | [Gemini](/docs/zh-CN/api/gemini) |

同一个模型，两种协议：

```bash
curl https://api.ohmygpt.com/v1/chat/completions \
  -H "Authorization: Bearer $OHMYGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-haiku-4-5", "max_tokens": 256,
       "messages": [{"role": "user", "content": "Explain QUIC in two sentences."}]}'

curl https://api.ohmygpt.com/v1/messages \
  -H "x-api-key: $OHMYGPT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-haiku-4-5", "max_tokens": 256,
       "messages": [{"role": "user", "content": "Explain QUIC in two sentences."}]}'
```

第一个请求返回 `chat.completion` 对象，第二个返回 Anthropic 的 `message`。

## 原生协议 [#原生协议]

每个模型都有一种原生协议：Claude 是 Messages，Gemini 模型是 Gemini，GPT、DeepSeek、Qwen 和其他大多数模型是 Chat Completions。`GET /v1/models` 用 `"native": true` 标出原生协议：

```bash
curl -s https://api.ohmygpt.com/v1/models \
  | jq -r '.data[] | select(.id == "anthropic/claude-haiku-4-5") | .protocols[] | [.path, (.native // false)] | @tsv'
```

```text
/v1/chat/completions	false
/v1/responses	false
/v1/messages	true
/v1/models/{id}:generateContent	false
```

在原生协议上，模型收到的请求体与你发送的完全一致，所以厂商特有字段和 beta 功能都按厂商文档的说明生效。OhMyGPT 只处理以下字段：

| 字段 | OhMyGPT 的处理 |
|---|---|
| `model` | 把你的模型 ID 解析为厂商的模型 ID |
| `stream` | 保持你的设置 |
| `stream_options` | Chat Completions 的流总会以一个用量数据块结尾 |
| `provider` | 在 Chat Completions 和 Responses 中读取你的[路由偏好](/docs/zh-CN/provider-routing) |
| `safetySettings` | 不带此字段的 Gemini 请求，四个可调类别会设为 `OFF`；见 [Gemini](/docs/zh-CN/api/gemini#安全设置) |
| `anthropic-version` | 在 Messages 中，如果没有发送，则设为 `2023-06-01`；其他 `anthropic-*` 请求头（例如 `anthropic-beta`）原样透传 |

## 其他协议 [#其他协议]

在其他协议上，OhMyGPT 会把你的请求转换成模型的原生协议，再把回答转换回来。消息、系统提示词、图片、工具、工具选择、token 上限、结构化输出和[推理控制](/docs/zh-CN/api/thinking)都会完整保留；模型有对应项的采样与输出参数也一样。响应按你所用协议的格式返回，结束原因也用该协议的取值。

模型没有对应项的采样或输出参数（例如发给 Claude 的 `seed` 或 `logprobs`）不会发送，模型按自己的默认行为作答。各模型系列支持哪些参数，见[参数](/docs/zh-CN/api/parameters)。Chat Completions 的 `enable_thinking` 和 `thinking_budget`（请改用[推理控制](/docs/zh-CN/api/thinking)），以及 Responses 的 `max_tool_calls`、`truncation`、`top_logprobs` 也一样。

有少数字段携带只有模型原生协议才能送达的输入，例如上游保存的上下文、服务端工具或提示词模板。请在原生协议上发送：

| 协议 | 需在原生协议上发送的字段 |
|---|---|
| Chat Completions | `functions` 和 `function_call`（或改用 `tools` 和 `tool_choice`，所有模型都支持） |
| Responses | `background`、`conversation`、`prompt` |
| Messages | `container`、`mcp_servers`，以及 `web_search_20250305` 等服务端工具 |
| Gemini | `cachedContent` |

如果这些字段通过其他协议发给模型，请求会在到达模型之前返回 400，因此不会产生费用，你也不会拿到一个悄悄漏掉了部分输入的回答：

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_parameter",
    "param": "background",
    "message": "The model `mock` does not support the `background` parameter."
  }
}
```

值为 `null`、`false`、`""`、`[]` 或 `{}` 的字段视为未设置，所以 SDK 的默认值不会触发这个错误。

## 错误 [#错误]

错误按你调用的协议格式返回，所以 SDK 的错误类型无需任何改动即可使用。

<Tabs items={['OpenAI', 'Anthropic', 'Gemini']}>
<Tab value="OpenAI">
```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "unsupported_endpoint",
    "param": "model",
    "message": "The model `ohmygpt/mock` does not support this endpoint. `GET /v1/models` lists the endpoints each model supports."
  }
}
```
</Tab>
<Tab value="Anthropic">
```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "The `Authorization` and `x-api-key` headers contain different API keys. Send only one, or make them match."
  }
}
```
</Tab>
<Tab value="Gemini">
```json
{
  "error": {
    "code": 404,
    "status": "NOT_FOUND",
    "message": "The model `google/gemini-0-nonexistent` does not exist. List available models with `GET /v1/models`.",
    "details": [
      { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "MODEL_NOT_FOUND", "domain": "ohmygpt.com" }
    ]
  }
}
```
</Tab>
</Tabs>

OpenAI 格式的错误中，`code` 是稳定的取值，可以据此做分支判断。[错误](/docs/zh-CN/errors)列出了所有 code，以及每种状态码的处理方法。