OpenRouter 实战指南：统一接口调用 500+ AI 模型

方式 2：直接 API 调用（无依赖）

如果你不想引入额外库，或者场景比较轻量，直接发 HTTP 请求也很简单。

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，适合喜欢原生体验的开发者。

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)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

四、7 个实战案例，覆盖主流应用场景

案例 1：免费模型调用（零成本学习）

OpenRouter 提供多个免费模型，名称通常带 :free 后缀。比如 DeepSeek、Mistral 的部分版本。

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 在实时思考。

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：代码生成与解释

调用专门针对代码优化的模型，比如 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)

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 等参数，可以控制输出的风格和长度。

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：工具调用

通过 MCP（Model Context Protocol）或标准 Tool Calling 机制，可以让 AI 调用外部 API，比如查天气。

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 密钥是否正确且未过期
   • 确认模型名称拼写无误（可在官网 Models 页面查询）
   • 检查账户余额（免费模型也有频率限制）
3. 响应缓慢：尝试切换到其他模型，或者适当减少 max_tokens 的输出长度。

最佳实践建议

1. 环境变量管理：千万别把密钥硬编码在代码里，用 .env 文件存储。
2. 错误处理：加上 try-except 捕获网络异常或认证错误，避免程序崩溃。
3. 模型选择策略：
   • 原型开发：优先用免费模型省钱
   • 生产环境：根据任务复杂度选付费模型
   • 成本敏感：Mistral、DeepSeek 性价比通常不错
4. 对话管理：合理截断对话历史，避免 token 消耗过快。
5. 监控与优化：定期查看控制台统计，根据实际使用情况调整模型参数。

六、进阶方向

掌握基础后，还可以往这些方向深入：

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

总结

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