OpenRouter 免费额度申请教程：一个 Key 聚合多模型，每天五十次请求

OpenRouter 提供兼容 OpenAI 的接口。把 base_url 指向 https://openrouter.ai/api/v1，就可以继续使用 OpenAI 官方 SDK；切换模型时，只需修改 model 这一个字段。

第一步：配置环境变量

export OPENROUTER_API_KEY="sk-or-v1-在控制台生成的密钥"
export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"

第二步：获取模型名

登录控制台，打开模型列表页，搜索带 :free 后缀的条目；也可以直接请求模型接口，拉取全量列表，再按价格字段为 0 筛出免费档。模型名形如 meta-llama/llama-3.1-8b-instruct:free，必须填写页面显示的完整 ID；如果漏掉后缀，就可能被当成付费模型计费。

第三步：发一次对话补全请求

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://example.com" \
  -H "X-Title: my-site" \
  -d '{
    "model": "meta-llama/llama-3.1-8b-instruct:free",
    "messages": [
      {"role": "system", "content": "你是一个简洁的中文助手。"},
      {"role": "user", "content": "用一句话说明什么是向量数据库"}
    ],
    "max_tokens": 256,
    "temperature": 0.7,
    "stream": false
  }'

关键参数说明：model 填完整模型 ID，必填；messages 是对话数组，支持 system、user、assistant 三种角色，顺序会影响结果；max_tokens 限制回复长度，免费模型建议控制在 512 以内；temperature 控制随机性；stream 设为 true 时按流式逐块返回。HTTP-Referer 与 X-Title 是平台用于统计应用来源的可选请求头，不传也能调用。

第四步：用 Python SDK 调用

import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["OPENROUTER_BASE_URL"],
    api_key=os.environ["OPENROUTER_API_KEY"],
)

resp = client.chat.completions.create(
    model="meta-llama/llama-3.1-8b-instruct:free",
    messages=[{"role": "user", "content": "用一句话说明什么是向量数据库"}],
    max_tokens=256,
)
print(resp.choices[0].message.content)

第五步：额度耗尽与限流的典型表现和排查顺序

最常见的表现是接口返回 429，并提示每分钟速率超限或当日免费次数已用完；如果走的是付费模型且余额不足，则会返回 402。建议按下面的顺序排查：

1. 先看 HTTP 状态码：401 多为密钥无效或请求头漏了 Bearer；404 多为模型 ID 写错；429 是限流或免费额度耗尽；402 是付费模型余额不足。
2. 再读响应体里的错误字段，免费档通常会写明是每分钟速率限制，还是每日免费请求数已达上限。
3. 接着查看响应头中与速率限制相关的字段，确认剩余请求数和重置时间。
4. 然后打开控制台的用量页面，核对调用记录，判断是本地循环重试打满了配额，还是真实业务量超限。
5. 最后再做缓解：加入指数退避重试、把请求改成串行、在模型列表页换用另一个 :free 模型；确有需要时充值 10 美元，把每日上限提升到 1000 次。