OpenRouter 接入教程

先准备账户,再弄清三个配置项。不写代码也能使用支持自定义接口的客户端;开发者可以继续完成第一次 API 请求。

核对日期:官方 Quickstart ↗

01 / ACCOUNT

准备账户与 API Key

只想先体验模型?可以从 OpenRouter 官方在线对话开始。要把模型接入客户端或自己的应用,再按下面的步骤准备 API Key。

  1. 打开 OpenRouter 官方网站,按页面提示注册或登录自己的账户。
  2. 进入 API Keys 设置创建密钥,使用便于识别用途的名称,并妥善保管。
  3. 到 官方模型目录选择模型,检查模型价格、输入能力与可用性;使用付费模型前检查账户余额和密钥额度。

本站不提供 OpenRouter 账户,不收集 API Key,也不会代你发出模型请求。免费模型同样受可用性与账户限制约束,具体见 免费模型与额度指南。

02 / CONFIGURATION

客户端里,先填对这三项

如果客户端内置 OpenRouter,优先使用对应选项;如果它支持自定义 OpenAI 兼容接口,则按客户端说明填写以下配置。不同客户端的字段名称和地址拼接方式可能不同。

OpenRouter API 基础配置
配置项填写内容与注意事项
API Key你在 OpenRouter 官方创建的密钥。客户端的密钥输入框通常只需要密钥本身;直接发 HTTP 请求时使用 Authorization: Bearer … 请求头。
Base URLhttps://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 服务进行付费调用测试。

接下来,选一个适合任务的模型

接通接口只是第一步。再比较输入能力、上下文长度、响应质量和输入输出价格,避免仅凭热度选择。

阅读模型与价格指南 →查看相关服务 →