01 / ACCOUNT
准备账户与 API Key
只想先体验模型?可以从 OpenRouter 官方在线对话开始。要把模型接入客户端或自己的应用,再按下面的步骤准备 API Key。
- 打开 OpenRouter 官方网站,按页面提示注册或登录自己的账户。
- 进入 API Keys 设置创建密钥,使用便于识别用途的名称,并妥善保管。
- 到 官方模型目录选择模型,检查模型价格、输入能力与可用性;使用付费模型前检查账户余额和密钥额度。
本站不提供 OpenRouter 账户,不收集 API Key,也不会代你发出模型请求。免费模型同样受可用性与账户限制约束,具体见 免费模型与额度指南。
02 / CONFIGURATION
客户端里,先填对这三项
如果客户端内置 OpenRouter,优先使用对应选项;如果它支持自定义 OpenAI 兼容接口,则按客户端说明填写以下配置。不同客户端的字段名称和地址拼接方式可能不同。
| 配置项 | 填写内容与注意事项 |
|---|---|
| API Key | 你在 OpenRouter 官方创建的密钥。客户端的密钥输入框通常只需要密钥本身;直接发 HTTP 请求时使用 Authorization: Bearer … 请求头。 |
| Base URL | https://openrouter.ai/api/v1这是接口基础地址,不是官网首页,也不是完整的聊天请求地址。 |
| 模型 ID | 从 官方模型页面复制完整模型 ID。不要只填 Claude、GPT 等模型家族名,也不要原样填写示例中的 MODEL_ID。 |
Base URL 和完整请求地址有什么区别?
SDK 或客户端通常会在基础地址后拼接接口路径。聊天补全的完整请求地址是 https://openrouter.ai/api/v1/chat/completions。把这个完整地址误填为 Base URL,可能导致路径被重复拼接。
若客户端要求的明确是“完整接口地址”,则填写完整地址并遵循该客户端文档。检查请求失败时,优先确认最终请求地址中没有重复的 /v1 或 /chat/completions。
第一次测试,尽量简单
先选一个支持文本对话的可用模型,只发送一句简短文本。确认可以得到回复后,再逐步增加图片、工具调用、长上下文或其他参数;这些能力取决于具体模型与提供商。
03 / FIRST REQUEST
发出第一次 API 请求
下面两种写法调用同一个聊天补全接口。运行前,在本地终端或服务器环境中设置 OPENROUTER_API_KEY 和 MODEL_ID:前者是你的密钥,后者是从官方目录复制的完整模型 ID。环境变量名不是要填入接口的字面值。
curl 示例适用于 Linux、macOS 或 WSL 的 POSIX shell,不适用于直接粘贴到 PowerShell。Node.js 示例使用 Node.js 18+ 的内置 fetch,代码可放在 request.mjs 中并用 node request.mjs 运行,无需安装 SDK。
# POSIX shell: configure both environment variables first.
: "${OPENROUTER_API_KEY:?Set OPENROUTER_API_KEY first}"
: "${MODEL_ID:?Set MODEL_ID to a real model ID}"
curl --silent --show-error --include --max-time 90 \
https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer ${OPENROUTER_API_KEY}" \
-H "Content-Type: application/json" \
--data "{
\"model\": \"${MODEL_ID}\",
\"messages\": [
{\"role\": \"user\", \"content\": \"Say hello in Chinese.\"}
]
}"
// Node.js 18+; run on a trusted machine, not in a browser.
const { OPENROUTER_API_KEY, MODEL_ID } = process.env;
async function main() {
if (!OPENROUTER_API_KEY || !MODEL_ID || MODEL_ID === 'MODEL_ID') {
throw new Error('Set OPENROUTER_API_KEY and a real MODEL_ID.');
}
const response = await fetch(
'https://openrouter.ai/api/v1/chat/completions',
{
method: 'POST',
headers: {
Authorization: `Bearer ${OPENROUTER_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
model: MODEL_ID,
messages: [{ role: 'user', content: 'Say hello in Chinese.' }],
}),
signal: AbortSignal.timeout(90_000),
}
);
const data = await response.json();
const apiError = data.error
?? data.choices?.find((choice) => choice.error)?.error;
if (!response.ok || apiError) {
throw new Error(
`Request failed (${apiError?.code ?? response.status}): `
+ (apiError?.message ?? response.statusText)
);
}
const reply = data.choices?.[0]?.message?.content;
if (typeof reply !== 'string' || !reply.trim()) {
throw new Error('No text returned; inspect the response and model settings.');
}
console.log(reply);
}
main().catch((error) => {
console.error(error.message);
process.exitCode = 1;
});
curl 的 --include 会显示 HTTP 响应头和正文。请求成功时,文本回复通常位于 choices[0].message.content;不要只看 HTTP 状态,还要检查正文是否含 error。
这些是入门示例,不会在本站运行。真实调用可能产生费用;上线应用前还需要根据业务补充用量控制、日志脱敏和错误处理。更多 SDK 与流式请求示例见 官方接入文档。
04 / TROUBLESHOOTING
调用失败,从哪里查起?
先保留 HTTP 状态、错误消息和请求时间,再判断属于配置问题、账户限制还是提供商暂时不可用。向他人求助前,删除密钥、个人信息和敏感对话内容。
需要按具体错误继续定位?阅读 401、402、429、502 / 503 与无文本响应的详细排查,区分应该修正配置还是等待重试。
| 现象 | 优先检查 |
|---|---|
| 鉴权失败 | 检查密钥是否正确、有效且未撤销;确认使用的是 OpenRouter 密钥,并正确发送 Authorization: Bearer …。 |
| 402 / 额度不足 | 检查账户余额和 API Key 的额度限制。网页产品的会员不等于 OpenRouter API 额度。 |
| 429 / 请求受限 | 降低并发与请求频率。如响应包含 Retry-After,按指示等待;不要连续快速重试。 |
| 模型不存在或不可用 | 核对完整模型 ID、当前模型目录与路由条件。模型下线、提供商负载或筛选条件过严都可能影响可用性。 |
| 请求参数错误 | 检查 JSON、接口路径、消息格式和模型支持的参数。先用最小文本请求验证,再逐个添加功能。 |
| 成功状态但没有文本 | 检查响应体中的错误、结束原因及模型输出类型。不要把 HTTP 200 直接当作获得了完整回答。 |
具体错误含义与处理方式以 官方错误与调试文档为准;免费模型和账户限制参见 官方额度与速率限制说明。本文未对实际 API 服务进行付费调用测试。
接下来,选一个适合任务的模型
接通接口只是第一步。再比较输入能力、上下文长度、响应质量和输入输出价格,避免仅凭热度选择。