9Router 技能入口指南用 OpenAI 兼容 REST 网关连接 40 AI 提供商的完整实战手册【免费下载链接】9routerUnlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40 providers. Auto-fallback, RTK -40% tokens, never hit limits.项目地址: https://gitcode.com/GitHub_Trending/9r/9router导读skills/9router/SKILL.md 是 9Router 项目面向 AI Agent 的入口技能文档它定义了一套一个 Key、多个提供商、自动故障转移的标准化接入方式只需设置NINEROUTER_URL与NINEROUTER_KEY两个环境变量即可通过{NINEROUTER_URL}/v1/...这一 OpenAI 兼容 REST 接口调用聊天、图像生成、语音、嵌入、Web 搜索与网页抓取等能力。读完本文你将掌握 9Router 网关的初始化配置、模型发现机制、八类能力子技能SKILL的索引用法以及常见错误码的排查方法并理解这些接口在仓库源码中的实际落地路径。一、9Router 是什么本地/远程 AI 网关的定位根据 skills/9router/SKILL.md 的定义9Router 是一个本地/远程部署的 AI 网关AI Gateway对外暴露 OpenAI 兼容的 REST API核心理念是One key, many providers, auto-fallback一个密钥接入众多提供商并自动故障转移。从仓库结构看这一能力由open-sse/目录承载open-sse/index.js 是核心导出入口集中导出了提供商注册表PROVIDERS、模型注册表PROVIDER_MODELS、请求/响应翻译器translateRequest/translateResponse、账户故障转移服务checkFallbackError、filterAvailableAccounts以及 OAuth 令牌刷新refreshTokenByProvider等模块open-sse/handlers/chatCore.js、open-sse/handlers/embeddingsCore.js、open-sse/handlers/imageGenerationCore.js、open-sse/handlers/ttsCore.js、open-sse/handlers/sttCore.js、open-sse/handlers/videoCore.js 分别对应聊天、嵌入、图像、语音合成、语音识别与视频生成的核心处理逻辑提供商注册表位于 open-sse/providers/registry/内含 40 个提供商条目openai、anthropic、gemini、claude、codex、cursor、copilot、antigravity、tavily、exa、firecrawl、elevenlabs、deepgram 等覆盖聊天、图像、TTS、STT、嵌入、搜索、抓取等多种能力类型。对使用者而言无论后端接入多少提供商暴露出来的都只是一个统一、稳定的 OpenAI 兼容端点这正是无需编写提供商样板代码without writing provider boilerplate的含义。二、Setup三分钟完成环境配置与连通性验证技能文档给出的初始化配置极简只需两个环境变量export NINEROUTER_URLhttp://localhost:20128 # or VPS / tunnel URL export NINEROUTER_KEYsk-... # from Dashboard → Keys (only if requireApiKeytrue)参数说明NINEROUTER_URL网关基址。本地默认为http://localhost:20128也可以替换为 VPS 部署地址或隧道tunnel地址NINEROUTER_KEY从 Dashboard → Keys 页面生成的 API 密钥。仅在服务端开启了requireApiKeytrue时才需要设置若关闭鉴权则可省略Authorization头。配置完成后所有请求统一发往${NINEROUTER_URL}/v1/...并在请求头携带Authorization: Bearer ${NINEROUTER_KEY}关闭鉴权时省略。连通性验证curl $NINEROUTER_URL/api/health → {ok:true}该健康检查端点在仓库中确实存在实现于 src/app/api/health/route.js。而requireApiKey这一配置项也贯穿了网关的鉴权链路——从源码搜索看它被 src/app/api/v1beta/models/[...path]/route.js 以及src/sse/handlers/下的 chat、embeddings、fetch、imageGeneration、search、stt、tts、videoGeneration 等全部 SSE 处理器引用例如通过isValidApiKey校验请求密钥说明鉴权是网关所有能力统一执行的入口级逻辑。三、Discover models按能力类型发现可用模型9Router 将模型按能力kind划分可通过/v1/models系列端点分别查询。技能文档给出的完整命令如下curl $NINEROUTER_URL/v1/models # chat/LLM (default) curl $NINEROUTER_URL/v1/models/image # image-gen curl $NINEROUTER_URL/v1/models/tts # text-to-speech curl $NINEROUTER_URL/v1/models/embedding # embeddings curl $NINEROUTER_URL/v1/models/web # web search fetch (entries have kind field) curl $NINEROUTER_URL/v1/models/stt # speech-to-text curl $NINEROUTER_URL/v1/models/image-to-text # vision使用规则将响应中的data[].id直接作为请求体里的model字段值组合模型Combo会以owned_by: combo标记出现——它们是多个提供商的自动故障转移组合例如vip、mycodex、search-combo、fetch-combo组合模型会自动在多个提供商之间链式回退即使某个上游账户不可用也能保持服务连续。标准响应结构与 OpenAI/v1/models兼容{ object: list, data: [ { id: openai/gpt-5, object: model, owned_by: openai, created: 1735000000 }, { id: tavily/search, object: model, kind: webSearch, owned_by: tavily, created: 1735000000 } ]}注意 Web 类模型带有kind字段webSearch/webFetch用于区分搜索与抓取两种子能力视频生成模型则标记为kind: video并被排除在聊天模型列表与聊天回退组合之外见 skills/9router-video/SKILL.md。查询单个模型的元数据除列表外还可以查看单个模型的参数细节上下文窗口、参数约束、能力声明等curl $NINEROUTER_URL/v1/models/info?idopenai/gpt-4o # chat 模型元数据 curl $NINEROUTER_URL/v1/models/info?idtavily/search # 搜索提供商参数searchTypes、maxResults、必填项如 cx curl $NINEROUTER_URL/v1/models/info?idopenai/dall-e-3 # 图像模型的 size/quality 枚举 curl $NINEROUTER_URL/v1/models/info?idopenai/text-embedding-3-small # 嵌入模型维度 curl $NINEROUTER_URL/v1/models/info?idel/eleven_multilingual_v2 # TTS 模型参数与 voicesUrl curl $NINEROUTER_URL/v1/models/info?idopenai/whisper-1 # STT 模型的 language/response_format 支持 curl $NINEROUTER_URL/v1/models/info?idfirecrawl/fetch # 抓取提供商的参数从源码看模型注册表集中在 open-sse/config/providerModels.js导出PROVIDER_MODELS、getProviderModels、isValidModel等能力类型与各提供商支持情况则由 open-sse/providers/capabilities.js 与 open-sse/providers/registry/index.js 统一管理——这也解释了为什么/v1/models能按 kind 分类返回且能给出每模型的参数元数据。四、Capability skills八大能力子技能索引技能文档的核心价值之一是入口即索引当用户需要某个具体能力时Agent 应去获取对应子技能的SKILL.md并按其中规范执行。原文以表格给出了能力与文档的映射这里将其中的原始链接统一转换为仓库内相对路径方便在本地仓库直接查阅能力子技能文档仓库相对路径聊天 / 代码生成Chat / code-genskills/9router-chat/SKILL.md图像生成Image generationskills/9router-image/SKILL.md视频生成xAI Grok Imagineskills/9router-video/SKILL.md文本转语音Text-to-speechskills/9router-tts/SKILL.md语音转文本Speech-to-textskills/9router-stt/SKILL.md嵌入向量Embeddingsskills/9router-embeddings/SKILL.mdWeb 搜索Web searchskills/9router-web-search/SKILL.mdWeb 抓取URL 转 MarkdownWeb fetchskills/9router-web-fetch/SKILL.md每个子技能文档都遵循同一套结构端点 → 模型发现 → 参数表 → curl/JS 示例 → 响应结构 → 提供商差异provider quirks表。这一整套技能体系还配有总览文档 skills/README.md说明其使用方式就是把链接粘贴给你的 AIRead this skill and use it: https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md然后正常提问如生成一张猫的图片、转录这个 URL即可。各子能力关键端点速览为便于整体把握下表汇总了各子技能定义的核心端点均以$NINEROUTER_URL为基址能力端点主要参数聊天POST /v1/chat/completionsOpenAI 格式或POST /v1/messagesAnthropic 格式model、messages、stream、max_tokens图像生成POST /v1/images/generationsmodel、prompt、n、size、quality、response_format视频生成POST /v1/videos/generations异步任务流model、prompt、duration、aspect_ratio、resolution、image文本转语音POST /v1/audio/speechmodel 声音 ID、input、?response_formatmp3/json语音转文本POST /v1/audio/transcriptionsmultipart/form-datamodel、file、language、prompt、response_format、temperature嵌入POST /v1/embeddingsmodel、input字符串或数组、encoding_format、dimensionsWeb 搜索POST /v1/searchmodel/provider、query、max_results、search_type、country等Web 抓取POST /v1/web/fetchmodel/provider、url、format、max_characters这些端点均由src/sse/handlers/目录下的同名处理器实现chat.js、imageGeneration.js、videoGeneration.js、tts.js、stt.js、embeddings.js、search.js、fetch.js它们在上游提供商返回的异构格式与 OpenAI 兼容格式之间做了统一翻译——这正是 open-sse/translator/ 目录含translateRequest/translateResponse与 format 注册表的职责。五、实战示例一次完整的聊天调用在 skills/9router-chat/SKILL.md 中聊天是网关最核心的能力支持两种请求格式。以下示例完整展示了从发现模型到流式输出的闭环1. 发现模型并查看元数据curl $NINEROUTER_URL/v1/models | jq .data[].id curl $NINEROUTER_URL/v1/models/info?idopenai/gpt-4o2. OpenAI 格式curlcurl -X POST $NINEROUTER_URL/v1/chat/completions \ -H Authorization: Bearer $NINEROUTER_KEY \ -H Content-Type: application/json \ -d {model:openai/gpt-5,messages:[{role:user,content:Hi}],stream:false}3. OpenAI 格式官方 SDK流式import OpenAI from openai; const client new OpenAI({ baseURL: ${process.env.NINEROUTER_URL}/v1, apiKey: process.env.NINEROUTER_KEY }); const res await client.chat.completions.create({ model: openai/gpt-5, messages: [{ role: user, content: Hi }], stream: true, }); for await (const chunk of res) process.stdout.write(chunk.choices[0]?.delta?.content || );因为网关暴露的是 OpenAI 兼容端点所以任何 OpenAI SDK 客户端只需改baseURL即可接入无需为每个上游提供商分别适配 SDK。4. Anthropic 格式curlcurl -X POST $NINEROUTER_URL/v1/messages \ -H Authorization: Bearer $NINEROUTER_KEY \ -H anthropic-version: 2023-06-01 \ -H Content-Type: application/json \ -d {model:cc/claude-opus-4-7,max_tokens:1024,messages:[{role:user,content:Hi}]}5. 响应结构OpenAI 格式/v1/chat/completions{ id: chatcmpl-..., object: chat.completion, model: openai/gpt-5, choices: [{ index: 0, message: { role: assistant, content: Hello! }, finish_reason: stop }], usage: { prompt_tokens: 8, completion_tokens: 2, total_tokens: 10 } }流式stream:true时以 SSE 事件逐块返回data: {choices:[{delta:{content:...}}]}\n\n…… 最终以data: [DONE]\n\n结束。Anthropic 格式/v1/messages{ id: msg_..., type: message, role: assistant, model: cc/claude-opus-4-7, content: [{ type: text, text: Hello! }], stop_reason: end_turn, usage: { input_tokens: 8, output_tokens: 2 } }从源码层面看聊天链路的核心实现在 open-sse/handlers/chatCore.js流式管线则由 open-sse/utils/streamHandler.js 提供createStreamController、pipeWithDisconnect等基础设施请求/响应翻译逻辑由 open-sse/translator/index.js 的translateRequest/translateResponse完成保证 OpenAI 与 Anthropic 两种格式之间的双向互转。六、Errors常见错误码与排查方法技能文档给出了三类最常见错误的排查指引这里结合源码机制展开说明错误含义与处理401鉴权失败。请在 Dashboard → Keys 重新生成或刷新NINEROUTER_KEY。网关侧通过isValidApiKey校验见 src/app/api/v1beta/models/[...path]/route.js若为 OAuth 类提供商还可借助 open-sse/services/tokenRefresh.js 的refreshTokenByProvider自动刷新过期令牌401 会触发一次 401→刷新→单次重试。400Invalid model format请求的model字段格式非法或不存在。请先在/v1/models/kind对应能力端点下确认模型 ID 存在再检查data[].id是否被原样用作model。源码侧isValidModelopen-sse/config/providerModels.js负责格式校验。503All accounts unavailable该提供商的所有账户当前均不可用如配额耗尽、账户冷却。处理方式等待响应头retry-after指定的时间后重试或在 Dashboard 中再添加一个提供商账户。源码侧由 open-sse/services/accountFallback.js 实现其导出的checkFallbackError、isAccountUnavailable、getUnavailableUntil、filterAvailableAccounts分别负责错误识别、不可用判定、冷却截止时间查询与可用账户过滤。视频生成的附加注意点在 skills/9router-video/SKILL.md 中还强调了几条异步任务的特殊约束适合作为网关异常处理的补充知识视频任务是异步的POST /v1/videos/generations立即返回request_id随后轮询GET /v1/videos/{request_id}直到done或failed任务与上游账户绑定轮询时必须回传创建响应头x-9router-connection-id作为x-connection-id否则可能查询到错误账户的任务创建类 POST绝不自动重试重试可能产生两次计费仅执行 401→刷新令牌→单次重试上游返回403/permission_denied表示当前订阅账户没有视频生成配额这由 xAI 侧控制9Router 不代为校验。七、延伸阅读与源码索引如果你希望深入了解各能力的参数细节与提供商差异可在仓库中继续查阅能力总览skills/README.md各能力子技能skills/9router-chat/SKILL.md、skills/9router-image/SKILL.md、skills/9router-tts/SKILL.md、skills/9router-stt/SKILL.md、skills/9router-embeddings/SKILL.md、skills/9router-web-search/SKILL.md、skills/9router-web-fetch/SKILL.md、skills/9router-video/SKILL.md核心导出与模块组织open-sse/index.js提供商注册表open-sse/providers/registry/index.js 与 open-sse/providers/registry/模型与能力定义open-sse/config/providerModels.js、open-sse/providers/capabilities.js翻译器格式互转open-sse/translator/index.js账户故障转移与令牌刷新open-sse/services/accountFallback.js、open-sse/services/tokenRefresh.js健康检查与路由实现src/app/api/health/route.js、src/app/api/v1beta/models/[...path]/route.js整体来看9Router 的接入心智模型非常清晰一条 OpenAI 兼容 REST 链路 按 kind 分类的模型发现 一组可被 Agent 直接消费的能力技能文档。入口技能 skills/9router/SKILL.md 承担了设置、发现、索引、排错四件事而各子技能则负责把每个能力讲到可直接运行的程度——这也是 Agent 或开发者接入 9Router 时最值得优先阅读的一份文档。【免费下载链接】9routerUnlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40 providers. Auto-fallback, RTK -40% tokens, never hit limits.项目地址: https://gitcode.com/GitHub_Trending/9r/9router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考