OpenRouter 实战指南：单 API 接入 500+ 模型

方式 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 入门书籍"}]
}

# 发送 POST 请求
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 阶段，但功能上更贴合其生态。

pip install openrouter

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)

# 运行
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)

asyncio.run(free_model_demo())

案例 2：流式响应（实时显示结果）

在聊天应用中，逐字显示 AI 回复能显著提升用户体验。注意开启 stream=True。

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)

asyncio.run(streaming_demo())

案例 3：多轮对话（上下文记忆）

通过维护 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)

asyncio.run(multi_turn_demo())

案例 4：代码生成与解释

调用擅长代码的模型生成 Python 代码时，建议降低 temperature 以提高准确性。

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)

asyncio.run(code_generation_demo())

案例 5：模型对比测试（一行代码切换模型）

快速对比不同模型的输出差异，是选型时的常用手段。

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 字符

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)

asyncio.run(parameter_tuning_demo())

案例 7：工具调用（连接外部 API）

通过 Function Calling 机制，可以让模型主动调用外部工具，比如查询天气。

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 的逻辑
        # 然后将结果返回给模型继续生成回复

asyncio.run(tool_calling_demo())

常见问题与最佳实践

常见问题

1. 免费模型无法使用：检查隐私设置是否启用了免费模型数据政策。
2. API 调用失败：
   • 检查 API 密钥是否正确
   • 确认模型名称是否正确（可在 https://openrouter.ai/models 查询）
   • 检查余额是否充足（免费模型有调用频率限制）
3. 响应缓慢：尝试切换到其他模型，或调整 max_tokens 减少输出长度。

最佳实践

1. 环境变量管理：使用 dotenv 存储 API 密钥，避免硬编码。
2. 错误处理：添加 try-except 捕获 API 调用异常，防止程序崩溃。
3. 模型选择策略：
   • 原型开发：使用免费模型
   • 生产环境：根据任务选择最合适的付费模型
   • 成本敏感：选择性价比高的模型如 Mistral、DeepSeek
4. 对话管理：合理维护上下文，避免对话历史过长导致 token 消耗过多。
5. 监控与优化：使用 OpenRouter 控制台查看调用统计，优化模型选择和参数设置。

进阶方向

1. 批量处理：同时处理多个请求，提高效率
2. 自定义路由：根据任务类型自动选择最优模型
3. 缓存机制：缓存常见查询结果，减少 API 调用
4. 多模态：调用支持图像生成的模型（如 DALL-E、Stable Diffusion）
5. 应用部署：将 OpenRouter 集成到 Web 应用、桌面程序或移动应用中

总结

OpenRouter 让 AI 开发变得前所未有的简单，你只需专注于应用逻辑，无需关心底层模型的复杂性。通过上述七个案例，你已经掌握了从基础调用到高级功能的核心技能。现在，开始用一个 API 探索 500+AI 模型的无限可能吧！