本站 API 端点与能力矩阵

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

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

能力	本站主要入口	传输与结果
模型发现	`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=...`	排队、轮询、结果信封

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

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。

FAQ

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

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

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

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

/v1/files 可以使用吗？

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

关联指南