# 本站 API 端点与能力矩阵

先在模型广场确认精确模型与已开放端点，再按本页选择协议；路由存在只表示网关认识该路径，不表示每个模型或渠道都支持。

## 小白先看：路径、模型和渠道是三件事

API 路径决定请求的协议形状，模型 ID 决定要调用的能力，渠道决定请求最终发往哪里。三者必须同时匹配。最稳妥的顺序是：先在[模型广场](https://api.tu-zi.com/pricing)找到精确模型并查看已开放端点，再选择下面的路径，最后用最小请求验证。不要因为某个厂商支持图像，就假定该厂商的所有图像型号都能走本站聊天端点。

| 能力 | 本站主要入口 | 传输与结果 |
| --- | --- | --- |
| 模型发现 | `GET /v1/models` | JSON 列表，只代表令牌当前可见模型 |
| 文本对话 | `POST /v1/chat/completions`、`POST /v1/responses` | JSON 或 SSE |
| Claude 协议 | `POST /v1/messages` | JSON 或 Claude SSE |
| Gemini 协议 | `POST /v1beta/models/{model}:generateContent` | JSON；流式路径语义不同 |
| 向量与重排 | `POST /v1/embeddings`、`POST /v1/rerank` | 同步 JSON |
| 图像 | `POST /v1/images/generations`、`POST /v1/images/edits` | URL/Base64，部分渠道内部异步 |
| 音频 | `POST /v1/audio/speech`、`transcriptions`、`translations` | JSON、multipart 或二进制 |
| 视频 | `POST /v1/videos`、`POST /v1/video/generations` | 创建任务后查询终态 |
| 实时 | `GET /v1/realtime` | WebSocket，不是 SSE |
| 通用异步 | `POST /async/*`、`GET /get-async?id=...` | /async 已停用（鉴权后 410），/get-async 已移除（404）；使用模型原生任务协议 |

## 最小发现请求

先用与正式调用相同的本站令牌查询模型。返回列表中存在模型，仍不保证每种路径都适配；随后应发一个低成本的真实请求。

```bash
curl "$BASE_URL/v1/models"   -H "Authorization: Bearer $API_KEY"
```

## 已注册但不可用的路径

`/v1/files`、`/v1/images/variations`、旧 fine-tunes 路径当前明确返回未实现。它们被注册是为了给出确定错误，而不是能力承诺。文档和 SDK 不应把 HTTP 路由存在、上游官方能力和本站渠道适配混为一谈。

## 进阶：如何确认一次调用

保存请求路径、精确模型、Request-ID、HTTP 状态、响应对象类型和 usage。遇到 404 时依次检查路径拼写、模型可见性和端点适配；遇到 400 则核对请求 schema；遇到 401/403 核对本站令牌；429 要区分请求频率、token 压力、日配额或余额限制。

## 专家：建立端点契约

生产系统应维护允许列表，而不是任意拼接路径。每条能力记录 HTTP 方法、Content-Type、同步/异步、是否流式、终态、最大请求体、结果保存期、可重试错误和计费单位。上线时用真实模型做合约测试；新增渠道或切换协议后重新验证，不能只替换 Base URL。
## MiniMax M3 视频输入

`POST /v1/media/video` 上传 MP4/MOV/AVI/MKV（最多 50,000,000 字节）并返回公网 URL，供 M3 聊天视频理解使用。`POST /v1/media/video/delete` 使用删除凭证清理上传文件。使用本站令牌鉴权，须先配置临时存储；完整示例见[文件与媒体](https://api.tu-zi.com/docs/use-cases/files-media)。这两个扩展接口不会启用 `/v1/files`。

## 适用场景

- 文本、媒体、检索接口选路
- 识别未实现接口与渠道边界

## API 路径

- /v1/models
- /v1/chat/completions
- /v1/responses
- /v1/messages
- /v1/embeddings
- /v1/rerank
- /v1/images/generations
- /v1/audio/speech
- /v1/videos
- /v1/videos/{video_id}/remix
- /v2/video_generation
- /v2/video_regeneration
- /v2/h3_context_ir
- /v2/query/video_generation/{task_id}
- /v1/media/video
- /v1/media/video/delete

## 关联指南

- [AI API 快速入门：从 API Key 到第一次调用](https://api.tu-zi.com/docs/use-cases/getting-started): 调用 AI API 需要匹配的 Base URL、API Key、模型名和端点；先用最小 curl 请求跑通，再处理错误、费用与密钥安全。
- [SSE 流式响应与 WebSocket 实时连接](https://api.tu-zi.com/docs/use-cases/streaming): SSE 是单次 HTTP 响应的事件流，WebSocket 是双向长连接；客户端必须按协议事件判断完成，不能把 HTTP 200 或连接关闭当成业务成功。
- [异步媒体任务：提交、查询与结果验收](https://api.tu-zi.com/docs/use-cases/async-tasks): 使用模型原生任务接口；通用 /async 已停用（410），/get-async 已移除（404）。提交成功后按对应协议查询到终态并验证媒体。
- [文件与媒体输入、输出及生命周期](https://api.tu-zi.com/docs/use-cases/files-media): 本站 `/v1/files` 当前未实现；文件必须按目标模型和端点支持的方式随请求提交，所有输入与结果 URL 都应视为有权限和生命周期的外部资源。

## 常见问题

### 看到路由就能直接调用吗？

不能。还要同时满足模型存在、令牌分组可见、渠道启用且适配该端点。模型广场是当前实例可用性和价格的运行时真相源。

### 为什么能力页不再直接列厂商总端点？

同一厂商的文本、图像、视频、音频和检索可能使用不同协议；复制总端点会让媒体模型看起来支持聊天接口。

### `/v1/files` 可以使用吗？

当前路由会返回未实现。文件应按目标端点使用 URL、Base64、data URL 或 multipart，具体方法以对应协议和模型为准。

## 参考来源

- OpenAI API Reference: https://developers.openai.com/api/reference/overview
- Claude Messages API: https://platform.claude.com/docs/en/api/messages
- Gemini API Reference: https://ai.google.dev/api

## 文档来源

来源: https://api.tu-zi.com/docs/use-cases/endpoint-matrix

核验日期: 2026-11-02

本文为文档接入参考。厂商原生接口与本站接口可能不同；请结合对应 API Reference 和模型广场确认本站地址、鉴权、模型 ID、分组与参数。本文不表示所有模型或上游服务均已通过实时调用验收。仅包含文档与示例，不包含当前用户的密钥或请求记录。