> ## Documentation Index
> Fetch the complete documentation index at: https://docs.geeknow.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 文本接口概览

> 汇总 Chat Completions、Responses、Claude Messages、Gemini 原生、模型列表和 Realtime 接口。

# 文本接口

文本接口提供多套常见协议，方便已有业务按最接近的 SDK 或请求结构接入。新项目通常优先选择 OpenAI Responses 或 Chat Completions；已有 Claude、Gemini 原生调用代码时，可以直接保留对应协议。

<CardGroup cols={2}>
  <Card title="模型与协议矩阵" icon="table-cells" href="/api-reference/texts/model-matrix">
    按协议、能力和常见模型家族选择接入入口。
  </Card>

  <Card title="Chat Completions" icon="messages-square" href="/api-reference/texts/chat-completions-non-stream">
    `POST /v1/chat/completions`，适合聊天、Agent、长文本生成和多模态输入。
  </Card>

  <Card title="OpenAI Responses" icon="bot" href="/api-reference/texts/openai-responses">
    `POST /v1/responses`，适合结构化输出、工具调用和复杂任务编排。
  </Card>

  <Card title="图像输入" icon="image" href="/api-reference/texts/image-inputs">
    文本模型接收图片时的 URL、base64 和图床上传写法。
  </Card>

  <Card title="Claude 原生" icon="file-text" href="/api-reference/texts/claude-messages">
    `POST /v1/messages`，保留 Anthropic Messages 协议。
  </Card>

  <Card title="Gemini 原生" icon="sparkles" href="/api-reference/texts/gemini-native">
    `POST /v1beta/models/{model}:{action}` 与 `GET /v1beta/models`。
  </Card>
</CardGroup>

## 认证方式

大多数文字接口使用 Bearer Token：

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Claude 原生格式同时兼容：

```http theme={null}
x-api-key: YOUR_API_KEY
anthropic-version: 2023-06-01
```

Gemini 原生格式同时兼容：

```http theme={null}
x-goog-api-key: YOUR_API_KEY
```

## 接口清单

| Method | Path                              | 页面                                                     | 说明                                       |
| ------ | --------------------------------- | ------------------------------------------------------ | ---------------------------------------- |
| `POST` | `/v1/chat/completions`            | [Chat Completions（非流式）](./chat-completions-non-stream) | OpenAI Chat Completions 兼容格式，默认一次性返回完整结果 |
| `POST` | `/v1/chat/completions`            | [Chat Completions（流式）](./chat-completions-stream)      | 同一路由，显式传入 `stream: true` 后以 SSE 返回增量     |
| `POST` | `/v1/completions`                 | [文本补全接口](./completions)                                | Legacy Completions 兼容格式                  |
| `POST` | `/v1/messages`                    | [Claude 消息接口](./claude-messages)                       | Anthropic Messages 原生协议                  |
| `POST` | `/v1/responses`                   | [OpenAI Responses 接口](./openai-responses)              | Responses API 兼容格式                       |
| `POST` | `/v1/responses/compact`           | [OpenAI Responses 接口](./openai-responses#上下文压缩)        | 上下文压缩                                    |
| `GET`  | `/v1/realtime`                    | [Realtime 接口](./realtime)                              | OpenAI Realtime 兼容 WebSocket             |
| `GET`  | `/v1/models`                      | [模型列表](./models)                                       | 查询当前 API Key 可用模型                        |
| `GET`  | `/v1/models/{model}`              | [模型列表](./models)                                       | 单模型查询                                    |
| `GET`  | `/v1beta/models`                  | [Gemini 原生格式](./gemini-native)                         | Gemini 原生模型列表                            |
| `POST` | `/v1beta/models/{model}:{action}` | [Gemini 原生格式](./gemini-native)                         | Gemini 原生推理与图像/视频相关动作                    |
| `GET`  | `/v1beta/openai/models`           | [模型列表](./models)                                       | Gemini 兼容模型列表                            |
| `POST` | `/pg/chat/completions`            | [Chat Completions（非流式）](./chat-completions-non-stream) | Playground 调试路由，使用登录态而非 API Key          |

## 通用错误码

| 状态码   | 说明                             |
| ----- | ------------------------------ |
| `400` | 请求参数错误，例如模型名不存在、消息结构无效、工具定义不合法 |
| `401` | API Key 缺失、无效或过期               |
| `402` | 额度不足                           |
| `413` | 请求体过大                          |
| `429` | 请求频率超限                         |
| `500` | 服务端内部错误                        |
| `503` | 上游不可用或系统临时过载                   |

<Tip>
  如果接口页里标记了“可选”参数，不代表所有模型都支持该字段。最终是否透传、是否生效，仍取决于实际分发到的渠道能力。
</Tip>

## 接入建议

| 场景                                     | 建议                                                                              |
| -------------------------------------- | ------------------------------------------------------------------------------- |
| 新项目、需要工具调用或结构化输出                       | 优先使用 [OpenAI Responses](./openai-responses)                                     |
| 已经使用 OpenAI SDK 或 Chat Completions 请求体 | 使用 [Chat Completions（非流式）](./chat-completions-non-stream)，需要边生成边展示时再打开 `stream` |
| 已经使用 Anthropic SDK                     | 使用 [Claude Messages](./claude-messages)，保留 `system`、`messages`、`tools` 等原生字段    |
| 已经使用 Gemini SDK                        | 使用 [Gemini 原生格式](./gemini-native)，保留 `contents`、`parts` 和 `generationConfig`    |
| 不确定模型名或权限                              | 先请求 [模型列表](./models)                                                            |

## 推荐阅读顺序

1. [文本模型支持矩阵](./model-matrix)
2. [Chat Completions（非流式）](./chat-completions-non-stream)
3. [Chat Completions（流式）](./chat-completions-stream)
4. [图像输入与图床上传](./image-inputs)
5. [OpenAI Responses 接口](./openai-responses)
6. [Claude 消息接口](./claude-messages)
7. [Gemini 原生格式](./gemini-native)
8. [模型列表](./models)
9. [参数测试用例](./parameter-tests)
10. [Realtime 接口](./realtime)