企业官网建设流程全解析

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_URL="http://localhost:20128" # or VPS / tunnel URL export NINEROUTER_KEY="sk-..." # from Dashboard → Keys (only if requireApiKey=true)

参数说明：

• NINEROUTER_URL：网关基址。本地默认为http://localhost:20128，也可以替换为 VPS 部署地址或隧道（tunnel）地址；
• NINEROUTER_KEY：从 Dashboard → Keys 页面生成的 API 密钥。仅在服务端开启了requireApiKey=true时才需要设置，若关闭鉴权则可省略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?id=openai/gpt-4o" # chat 模型元数据 curl "$NINEROUTER_URL/v1/models/info?id=tavily/search" # 搜索提供商参数（searchTypes、maxResults、必填项如 cx） curl "$NINEROUTER_URL/v1/models/info?id=openai/dall-e-3" # 图像模型的 size/quality 枚举 curl "$NINEROUTER_URL/v1/models/info?id=openai/text-embedding-3-small" # 嵌入模型维度 curl "$NINEROUTER_URL/v1/models/info?id=el/eleven_multilingual_v2" # TTS 模型参数与 voicesUrl curl "$NINEROUTER_URL/v1/models/info?id=openai/whisper-1" # STT 模型的 language/response_format 支持 curl "$NINEROUTER_URL/v1/models/info?id=firecrawl/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并按其中规范执行。原文以表格给出了能力与文档的映射，这里将其中的原始链接统一转换为仓库内相对路径，方便在本地仓库直接查阅：

每个子技能文档都遵循同一套结构：端点 → 模型发现 → 参数表 → curl/JS 示例 → 响应结构 → 提供商差异（provider quirks）表。这一整套技能体系还配有总览文档 skills/README.md，说明其使用方式就是"把链接粘贴给你的 AI"：

Read this skill and use it: https://raw.githubusercontent.com/decolua/9router/refs/heads/master/skills/9router/SKILL.md

然后正常提问（如"生成一张猫的图片"、"转录这个 URL"）即可。

各子能力关键端点速览

为便于整体把握，下表汇总了各子技能定义的核心端点（均以$NINEROUTER_URL为基址）：

这些端点均由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?id=openai/gpt-4o"

2. OpenAI 格式（curl）

curl -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 格式（curl）

curl -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：常见错误码与排查方法

技能文档给出了三类最常见错误的排查指引，这里结合源码机制展开说明：

视频生成的附加注意点

在 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