CoreRouter API 文档接口与能力总览
CoreRouter 的接口不是只有一种。接入前先判断你的客户端要调用哪种协议，再选择对应的 Base URL、Endpoint 和模型能力。
一句话判断
| 你要做什么 | 优先使用 | Base URL | 是否通用 |
|---|---|---|---|
| 普通聊天、多轮对话、函数调用、视觉理解 | /v1/chat/completions | https://api.corerouter.tech/v1 | 常用通用入口 |
| 旧版文本补全 | /v1/completions | https://api.corerouter.tech/v1 | 仅旧应用需要 |
| Codex、Agent、Responses 工作流 | /v1/responses | https://api.corerouter.tech/v1 | 条件支持，要求模型绑定 Responses 能力 |
| Agent 独立搜索 | /v1/alpha/search | https://api.corerouter.tech/v1 | 条件支持，要求搜索兼容渠道和模型 |
| Claude Code、Anthropic 风格应用 | /v1/messages | https://api.corerouter.tech | 条件支持，要求客户端使用 Anthropic Messages 格式 |
| Gemini 风格应用 | /v1beta/models/{model}:generateContent | https://api.corerouter.tech | 条件支持，要求客户端使用 Gemini 请求格式 |
| Embeddings / RAG | /v1/embeddings | https://api.corerouter.tech/v1 | 要求 Embeddings 模型 |
| Rerank / 重排 | /v1/rerank | https://api.corerouter.tech/v1 | 要求 Rerank 模型或渠道 |
| Moderations / 内容审核 | /v1/moderations | https://api.corerouter.tech/v1 | 要求审核模型或可用默认审核模型 |
| 图片生成和图片编辑 | /v1/images/generations、/v1/images/edits | https://api.corerouter.tech/v1 | 要求图片模型 |
| 语音识别、翻译、TTS | /v1/audio/... | https://api.corerouter.tech/v1 | 要求音频或 TTS 模型 |
| Realtime WebSocket | /v1/realtime | wss://api.corerouter.tech/v1/realtime | 条件支持，要求 Realtime 模型 |
| 视频任务 | /v1/videos、/v1/video/generations | https://api.corerouter.tech/v1 | 条件支持，要求视频任务模型和任务渠道 |
| Midjourney 风格图片任务 | /mj/submit/... | https://api.corerouter.tech | 条件支持，要求对应图片任务渠道 |
| 通用异步任务 | /v1/tasks/{key} | https://api.corerouter.tech/v1 | 高级接口，通常由插件或已对接客户端使用 |
Endpoint 清单
| Endpoint | 方法 | 请求格式 | 说明 |
|---|---|---|---|
/v1/models | GET | 无请求体 | 查询当前 API Key 可见模型。结果可能受用户分组、Key 限制和计费配置影响。 |
/v1/models/{model} | GET | 无请求体 | 查询单个模型。 |
/v1beta/models | GET | 无请求体 | Gemini 风格模型列表，返回当前 API Key 可见的 Gemini 兼容模型。 |
/v1beta/openai/models | GET | 无请求体 | Gemini 场景下的 OpenAI 风格模型列表兼容路径。 |
/v1/chat/completions | POST | OpenAI Chat Completions JSON | 最常用的聊天入口。 |
/v1/completions | POST | OpenAI legacy Completions JSON | 旧应用兼容入口，新应用优先用 Chat Completions。 |
/v1/responses | POST | OpenAI Responses JSON | Agent / Codex 常用，只有支持 Responses 的 Model ID 才可用。 |
/v1/responses/{response_id} | GET | 无请求体 | 查询后台 Responses 结果。 |
/v1/responses/compact | POST | Responses 压缩请求 | 高级能力，通常由 Agent 工具自动调用；需要渠道支持压缩能力。 |
/v1/alpha/search | POST | 客户端原生搜索 JSON | 独立搜索兼容入口，只有配置了对应搜索能力的渠道和模型可用。 |
/v1/messages | POST | Anthropic Messages JSON | Claude Code 和 Anthropic 风格客户端使用。 |
/v1beta/models/{model}:generateContent | POST | Gemini JSON | Gemini 风格生成接口。 |
/v1beta/models/{model}:streamGenerateContent | POST | Gemini JSON | Gemini 风格流式接口。 |
/v1beta/models/{model}:embedContent | POST | Gemini Embedding JSON | Gemini 风格单条向量接口。 |
/v1beta/models/{model}:batchEmbedContents | POST | Gemini Embedding JSON | Gemini 风格批量向量接口。 |
/v1/embeddings | POST | OpenAI Embeddings JSON | RAG 和向量检索使用。 |
/v1/rerank | POST | Rerank JSON | 对候选文档按相关性重排。 |
/v1/moderations | POST | OpenAI Moderations JSON | 内容审核。 |
/v1/images/generations | POST | JSON | 图片生成。 |
/v1/images/edits | POST | multipart/form-data 或 JSON | 图片编辑。 |
/v1/edits | POST | JSON | 旧版图片编辑兼容路径，优先使用 /v1/images/edits。 |
/v1/audio/transcriptions | POST | multipart/form-data | 音频转文字。 |
/v1/audio/translations | POST | multipart/form-data | 音频翻译成英文或模型默认目标语言。 |
/v1/audio/speech | POST | JSON | 文字转语音。 |
/v1/realtime?model={model} | GET WebSocket | WebSocket event JSON | 实时语音/文本交互，不是普通 HTTP 接口。 |
/v1/videos | POST | JSON 或 multipart/form-data | OpenAI 风格视频任务提交。 |
/v1/videos/{task_id} | GET | 无请求体 | OpenAI 风格视频任务查询。 |
/v1/videos/{task_id}/content | GET / HEAD | 无请求体 | 获取视频任务产物，是否可用取决于任务渠道。 |
/v1/video/generations | POST | JSON | 兼容视频任务提交路径。 |
/v1/video/generations/{task_id} | GET | 无请求体 | 兼容视频任务查询路径。 |
/v1/videos/{video_id}/remix | POST | JSON | 基于已有视频二次生成，要求渠道支持。 |
/v1/tasks/{key} | POST | JSON 或 multipart/form-data | 通用任务提交，key 是任务插件或任务类型标识。 |
/v1/tasks/{task_id} | GET | 无请求体 | 通用任务查询。 |
/v1/tasks/{task_id}/artifacts | GET | 无请求体 | 查询任务产物列表。 |
/v1/tasks/{task_id}/artifacts/{artifact_key}/content | GET / HEAD | 无请求体 | 下载或探测任务产物内容。 |
/mj/submit/imagine | POST | Midjourney 风格 JSON | 图片任务提交，prompt 必填。 |
/mj/task/{id}/fetch | GET | 无请求体 | 查询图片任务状态和结果。 |
不要混用请求格式
不同协议的 JSON 结构不同，不能只换 URL 不换请求体。
| 协议 | 用户消息字段 |
|---|---|
| Chat Completions | messages: [{ "role": "user", "content": "..." }] |
| Responses | input: "..." 或结构化 input 数组 |
| Anthropic Messages | messages、max_tokens，工具字段使用 Anthropic 格式 |
| Gemini | contents: [{ "parts": [{ "text": "..." }] }] |
| Embeddings | input: "..." 或字符串数组 |
| Rerank | query 和 documents |
常见错误怎么判断
| 现象 | 常见原因 | 处理 |
|---|---|---|
| Chat 可以，Responses 不行 | 当前 Model ID 只支持 Chat Completions | 换用控制台标记支持 Responses 的模型 |
客户端路径出现 /v1/v1 | Base URL 和客户端自动拼接路径冲突 | 把 Base URL 改成根地址或带 /v1 的地址，二选一 |
/v1/models 有结果，调用模型报错 | Key 能看到模型列表，但目标模型权限、渠道或能力不匹配 | 换模型或检查 Key 限制和账户分组 |
messages is required | Chat Completions 请求体缺少 messages | 使用 Chat 格式，不要传 Responses 的 input |
input is required | Responses、Embeddings 或 Moderations 缺少 input | 按对应接口补齐 input |
query is empty 或 documents is empty | Rerank 请求缺少查询或候选文档 | 补齐 query 和非空 documents |
| Realtime 直接用 curl POST | Realtime 是 WebSocket，不是 HTTP JSON POST | 使用 WebSocket 客户端连接 wss://.../v1/realtime?model=... |
| 独立搜索返回不支持 | 当前渠道或模型没有搜索兼容能力 | 改用支持搜索的模型，或在 Responses 工作流中使用客户端支持的搜索工具 |
推荐接入顺序
- 用
/v1/models确认 API Key 可用。 - 用
/v1/chat/completions验证基础聊天。 - 按实际场景验证目标接口，例如 Responses、Embeddings、Rerank、音频或视频。
- 再把同一组 Base URL、API Key 和 Model ID 填进 SDK、客户端或插件。
不建议承诺支持的接口
下面这些 OpenAI 旧接口或管理接口不是通用中转调用入口。即使客户端里出现相关功能，也不要默认承诺可用：
| 接口类型 | 说明 |
|---|---|
/v1/files | 文件上传、文件内容读取等文件管理接口不作为通用模型调用入口。 |
/v1/fine-tunes | 旧版微调接口不作为常规接入能力。 |
/v1/assistants、/v1/threads、/v1/runs | Assistants 旧式资源和线程接口没有作为通用中转入口开放。 |
/v1/batches、/v1/vector_stores | 批处理和向量库管理接口没有作为通用中转入口开放。 |
POST /v1/messages/count_tokens | Anthropic token 计数辅助接口当前不作为公共接入能力。 |
/v1/images/variations | 图片变体接口不等同于图片生成或图片编辑，接入前需要单独确认。 |
DELETE /v1/models/{model} | 模型删除属于官方管理接口语义，不适合作为中转站用户能力。 |
如果某个客户端强依赖这些接口，建议先确认它是否允许关闭相关功能，或换用只依赖 Chat Completions、Responses、Anthropic Messages、Gemini、Embeddings、Rerank、图片、音频、视频任务这些已说明接口的客户端。