OpenRouter 入门：统一接口调用 500+AI 模型实战
一、OpenRouter 是什么？
OpenRouter 本质上是一个AI 模型 API 聚合平台。你可以把它想象成一个'万能插座'，通过一个 API 密钥和统一接口，就能调用来自 OpenAI、Anthropic、Google、Mistral 等 50+ 提供商的500+ 主流 AI 模型，其中还包含 50+ 个可免费使用的模型。
它的核心价值在于：
- 统一接口：无需为不同厂商适配各自的 API 格式
- 灵活切换：一行代码即可更换模型，方便对比测试效果
- 成本优化：自动选择最经济的模型方案
- 自动故障转移：主模型不可用时自动切换备用模型
二、准备工作：注册与 API 密钥获取
1. 注册账号
访问官网 https://openrouter.ai，点击 "Sign Up" 注册。支持 Google 账号快速登录或邮箱注册，完成验证后即可使用。
2. 启用免费模型（关键步骤）
很多开发者反馈无法使用免费模型，通常是因为隐私设置未开启。请务必操作：
- 点击右上角头像 → Settings（设置）→ Privacy（隐私）
- 勾选 "Agree to the free models data policy"（同意免费模型数据政策）
- 保存设置
3. 创建 API 密钥
- 点击右上角头像 → API Keys（密钥）
- 点击 "Create Key" 创建新密钥
- 输入密钥名称，可选设置额度限制
- 复制密钥并妥善保存（仅显示一次，丢失后需重新生成）
三、三种核心调用方式（Python）
方式 1：使用 OpenAI SDK（推荐，兼容性最好）
OpenRouter 提供 OpenAI 兼容接口，这意味着我们可以直接复用现有的 OpenAI SDK 代码，只需修改 base_url 和 api_key。
import os
from openai import OpenAI
from dotenv import load_dotenv
# 加载环境变量
load_dotenv()
# 配置 OpenRouter 客户端
client = OpenAI(
base_url="https://openrouter.ai/api/v1",
api_key=os.getenv("OPENROUTER_API_KEY"),
default_headers={
"HTTP-Referer": "https://your-website.com", # 可选，用于排行榜展示
"X-Title": "Your App Name" # 可选，应用名称
}
)
async def main():
# 发送请求
completion = await client.chat.completions.create(
model="openai/gpt-3.5-turbo",
messages=[{"role": "user", "content": "用一句话解释什么是人工智能？"}]
)
# 输出结果
print(completion.choices[0].message.content)
if __name__ == "__main__":
import asyncio
asyncio.run(main())
方式 2：直接 API 调用（无依赖，适合轻量场景）
如果你不想引入额外的 SDK 依赖，直接使用 requests 库也是完全可行的，这在脚本工具中很常见。
import requests
import os
import json
from dotenv import load_dotenv
load_dotenv()
url = "https://openrouter.ai/api/v1/chat/completions"
headers = {
"Authorization": f"Bearer {os.getenv('OPENROUTER_API_KEY')}",
"Content-Type": "application/json",
"HTTP-Referer": "https://your-website.com", # 可选
"X-Title": "Your App Name" # 可选
}
data = {
"model": "deepseek/deepseek-r1-distill-llama-70b:free", # 免费模型
"messages": [{"role": "user", "content": "推荐 3 本 Python 入门书籍"}]
}
response = requests.post(url, headers=headers, data=json.dumps(data))
result = response.json()
print(result["choices"][0]["message"]["content"])
方式 3：使用 OpenRouter Python SDK（Beta 版）
官方也提供了专用的 SDK，虽然目前处于 Beta 阶段，但能提供更原生的体验。
from openrouter import OpenRouter
import os
from dotenv import load_dotenv
load_dotenv()
client = OpenRouter(
api_key=os.getenv("OPENROUTER_API_KEY"),
base_url="https://openrouter.ai/api/v1"
)
async def main():
response = await client.chat.completions.create(
model="mistralai/mistral-7b-instruct:free", # 免费模型
messages=[{"role": "user", "content": "什么是大语言模型？"}]
)
print(response.choices[0].message.content)
if __name__ == "__main__":
import asyncio
asyncio.run(main())
四、7 个实战案例，覆盖主流应用场景
案例 1：免费模型调用（零成本学习）
OpenRouter 提供多个免费模型，名称通常带 ":free" 后缀。这非常适合学习和原型开发。
async def free_model_demo():
completion = await client.chat.completions.create(
model="mistralai/mistral-7b-instruct:free", # 选择免费模型
messages=[{"role": "user", "content": "写一首关于程序员的短诗"}]
)
print("免费模型结果：")
print(completion.choices[0].message.content)
if __name__ == "__main__":
import asyncio
asyncio.run(free_model_demo())
案例 2：流式响应（实时显示结果）
在聊天应用中，流式响应（Streaming）能显著提升用户体验，让 AI 回复逐字呈现。
async def streaming_demo():
print("AI 正在思考，将实时显示结果：")
stream = await client.chat.completions.create(
model="openai/gpt-3.5-turbo",
messages=[{"role": "user", "content": "解释什么是流式响应？"}],
stream=True # 启用流式
)
async for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)
if __name__ == "__main__":
import asyncio
asyncio.run(streaming_demo())
案例 3：多轮对话（上下文记忆）
LLM 本身是无状态的，我们需要在代码层面维护 messages 列表来实现连续对话。
async def multi_turn_demo():
# 初始化对话历史
messages = [
{"role": "system", "content": "你是一个友好的助手，擅长解释技术概念"},
{"role": "user", "content": "什么是 OpenRouter？"}
]
# 第一轮对话
response = await client.chat.completions.create(
model="anthropic/claude-3-haiku",
messages=messages
)
assistant_msg = response.choices[0].message
print("AI:", assistant_msg.content)
# 添加 AI 回复到对话历史
messages.append(assistant_msg)
# 第二轮对话（基于上下文）
messages.append({"role": "user", "content": "它和直接调用 OpenAI API 有什么区别？"})
response2 = await client.chat.completions.create(
model="anthropic/claude-3-haiku",
messages=messages
)
print("AI:", response2.choices[0].message.content)
if __name__ == "__main__":
import asyncio
asyncio.run(multi_turn_demo())
案例 4：代码生成与解释
调用擅长代码的模型（如 DeepSeek Coder），可以辅助编写业务逻辑。
async def code_generation_demo():
prompt = """
写一个 Python 函数，实现以下功能：
1. 接收一个列表作为输入
2. 计算列表中所有偶数的平方和
3. 返回结果
4. 添加详细注释
"""
response = await client.chat.completions.create(
model="deepseek/deepseek-coder-6.7b-instruct:free", # 免费代码模型
messages=[{"role": "user", "content": prompt}],
temperature=0.3 # 降低随机性，提高代码准确性
)
print("生成的代码：")
print(response.choices[0].message.content)
if __name__ == "__main__":
import asyncio
asyncio.run(code_generation_demo())
案例 5：模型对比测试（一行代码切换模型）
OpenRouter 最大的优势之一就是可以快速对比不同模型的输出差异。
async def model_comparison_demo():
prompt = "解释量子计算的基本原理，用简单易懂的语言"
models = ["openai/gpt-3.5-turbo", "anthropic/claude-3-haiku", "mistralai/mistral-7b-instruct:free"]
for model in models:
print(f"\n===== {model} =====")
response = await client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": prompt}]
)
print(response.choices[0].message.content[:200] + "...") # 显示前 200 字符
if __name__ == "__main__":
import asyncio
asyncio.run(model_comparison_demo())
案例 6：参数调优（控制输出风格）
通过调整 temperature 和 max_tokens 等参数，可以精细控制 AI 回复的长度和创造性。
async def parameter_tuning_demo():
messages = [{"role": "user", "content": "写一个关于太空探索的故事"}]
# 高随机性（创意故事）
print("=== 高随机性（temperature=0.9）===")
response1 = await client.chat.completions.create(
model="openai/gpt-3.5-turbo",
messages=messages,
temperature=0.9, # 0-2，越高越随机
max_tokens=200 # 限制最大长度
)
print(response1.choices[0].message.content)
# 低随机性（结构化输出）
print("\n=== 低随机性（temperature=0.1）===")
response2 = await client.chat.completions.create(
model="openai/gpt-3.5-turbo",
messages=messages,
temperature=0.1,
max_tokens=200,
top_p=0.1 # 核采样，0-1，越小越集中
)
print(response2.choices[0].message.content)
if __name__ == "__main__":
import asyncio
asyncio.run(parameter_tuning_demo())
案例 7：工具调用（连接外部 API）
通过 MCP（Model Context Protocol）或标准 Function Calling，可以让 AI 调用外部工具，比如查询天气。
async def tool_calling_demo():
# 定义可用工具
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取指定城市的天气信息",
"parameters": {
"type": "object",
"properties": {
"city": {"type": "string", "description": "城市名称"}
},
"required": ["city"]
}
}
}]
response = await client.chat.completions.create(
model="openai/gpt-3.5-turbo",
messages=[{"role": "user", "content": "北京今天的天气怎么样？"}],
tools=tools,
tool_choice="auto" # 自动选择工具
)
# 处理工具调用请求
tool_calls = response.choices[0].message.tool_calls
if tool_calls:
print("需要调用工具：", tool_calls[0].function.name)
# 这里可以添加调用外部天气 API 的逻辑
# 然后将结果返回给模型继续生成回复
if __name__ == "__main__":
import asyncio
asyncio.run(tool_calling_demo())
五、常见问题与最佳实践
常见问题
- 免费模型无法使用：检查隐私设置是否启用了免费模型数据政策。
- API 调用失败：
- 检查 API 密钥是否正确
- 确认模型名称是否正确（可在 https://openrouter.ai/models 查询）
- 检查余额是否充足（免费模型有调用频率限制）
- 响应缓慢：尝试切换到其他模型，或调整
max_tokens减少输出长度。
最佳实践
- 环境变量管理：使用
dotenv存储 API 密钥，避免硬编码在代码中。 - 错误处理：添加
try-except捕获 API 调用异常，防止程序崩溃。 - 模型选择策略：
- 原型开发：使用免费模型
- 生产环境：根据任务选择最合适的付费模型
- 成本敏感：选择性价比高的模型如 Mistral、DeepSeek
- 对话管理：合理维护上下文，避免对话历史过长导致 token 消耗过多。
- 监控与优化：使用 OpenRouter 控制台查看调用统计，优化模型选择和参数设置。
六、进阶方向
掌握了基础用法后，还可以探索更多可能性：
- 批量处理：同时处理多个请求，提高效率
- 自定义路由：根据任务类型自动选择最优模型
- 缓存机制：缓存常见查询结果，减少 API 调用
- 多模态：调用支持图像生成的模型（如 DALL-E、Stable Diffusion）
- 应用部署：将 OpenRouter 集成到 Web 应用、桌面程序或移动应用中
总结
OpenRouter 让 AI 开发变得前所未有的简单，你只需专注于应用逻辑，无需关心底层模型的复杂性。通过上述实战案例，你已经掌握了从基础调用到高级功能的核心技能。现在，开始用一个 API 探索 500+AI 模型的无限可能吧！
