OpenRouter 怎么用：从注册到 API 调用的完整流程
OpenRouter 的核心用法是把它当作一个兼容 OpenAI 接口的代理入口：注册账号并生成 API Key 后，把请求地址指向 https://openrouter.ai/api/v1，模型名换成平台上标注的完整标识，就能用同一套代码调用不同厂商的模型。
下面按实际使用顺序说明准备、调用和排错要点。
先确认你属于哪种使用场景
OpenRouter 适合两类人：一是想比较不同模型输出、又不想分别注册多家平台的开发者；
二是已经在用 OpenAI 兼容客户端，希望快速切换模型做测试的用户。
需要提前了解的限制是：调用会产生费用，需要账户内有可用余额；
不同模型的价格、上下文长度和可用地区不同，以平台模型页显示为准。
如果你只是本地跑开源模型，不需要 OpenRouter，直接用 Ollama 等本地方案更合适。
账号与密钥准备
- 打开 OpenRouter 官网注册账号，完成邮箱验证。
- 进入控制台的 Keys 页面，创建一个新的 API Key，复制并妥善保存。密钥通常只完整显示一次，丢失后只能重新创建。
- 在 Credits 页面查看余额，余额不足时调用会直接返回错误。
- 在 Models 页面找到要用的模型，记下它的完整标识，例如带厂商前缀的写法。模型标识必须逐字一致，少一段前缀就会报模型不存在。
建议给密钥设置用途备注和额度上限，避免把测试密钥直接用于生产环境。
用 curl 跑通第一次请求
先用最简单的命令行请求验证密钥和网络是否正常。
把 你的API_KEY 和模型标识替换成实际值：
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer 你的API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "厂商/模型标识",
"messages": [{"role": "user", "content": "用一句话解释什么是API"}]
}'预期结果是返回一段 JSON，其中 choices[0].message.content 就是模型输出。
如果返回 401，先检查密钥是否复制完整；
返回 402 通常是余额不足；
返回 404 则大概率是模型标识写错。
可选请求头 HTTP-Referer 和 X-Title 用于在平台后台标识调用来源，不影响功能，按需添加即可。
在 Python 中替换请求地址
如果项目已经使用 OpenAI SDK，改动量很小，只需替换 base_url 和 api_key，模型名换成 OpenRouter 的标识：
from openai import OpenAI
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key="你的API_KEY",
)
resp = client.chat.completions.create(
model="厂商/模型标识",
messages=[{"role": "user", "content": "你好，做个自我介绍"}],
)
print(resp.choices[0].message.content)同样的思路适用于大多数支持自定义 Base URL 的客户端和框架：填 OpenRouter 的地址、填密钥、填模型标识，三处对应上就能工作。
容易踩坑的几处细节
- 模型标识不要简写：平台上的模型名通常带厂商前缀，直接写
gpt-4之类的短名可能匹配不到。 - 密钥不要写进前端代码：浏览器端直接暴露密钥会被盗用，应通过自己的后端转发请求。
- 余额和限额分开看：账户余额充足但密钥设置了额度上限时，仍可能被拒绝。
- 超时先排查网络：请求长时间无响应时，先用 curl 确认能否连通接口域名，再检查代理或防火墙设置。
- 流式输出要按客户端支持方式开启：需要逐字返回时在请求中开启流式参数，并确保客户端按流读取，否则会一直等完整结果。
验证调用是否真正成功
判断一次调用是否成功，不要只看程序有没有报错，建议依次确认：返回内容非空、choices 数组存在、用量字段有数值、平台后台的请求记录中能看到这次调用。
后台记录能同时反映计费和模型路由情况，是排查问题最直接的依据。
如果以上都正常，说明 OpenRouter 已经接入成功，下面可以按业务需要切换模型或增加重试与超时控制。
首次接入建议先用低成本模型验证链路，再替换为正式模型。
