OpenRouter 实战：用一个接口调用多家 AI 模型

2）直接发 HTTP 请求

不想引入 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

官方也有自己的 SDK，不过现在还是 Beta。接口体验会更贴近平台本身，但如果你已经在用 OpenAI SDK，它的优势没那么大，是否切过去主要看项目习惯。

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 个常见场景，基本够你起步

免费模型先跑通

先用 :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())

流式响应

聊天类应用里，流式输出比一次性返回更像'真的在生成'。用户不会盯着空白页等半天，这个体验差异很明显。

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())

多轮对话

大模型本身不记事，连续对话靠你在代码里维护 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())

代码生成和解释

如果是写业务逻辑、补注释、解释一段实现，代码模型通常更合适。这里 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)

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

一行切换模型做对比

这是 OpenRouter 最好用的地方之一。你不用改请求结构，只要替换 model，就能看到不同模型在同一问题上的差异。做选型时，这比看宣传页靠谱得多。

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())

参数调优

temperature 和 max_tokens 基本是最常调的两个参数。前者控制发散程度，后者控制长度；如果还想更收敛一点，再配合 top_p。

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())

工具调用

如果模型要接外部能力，比如查天气、查订单、读内部接口，工具调用就派上用场了。OpenRouter 可以走 MCP 或标准 Function Calling，写法和你熟悉的 OpenAI 工具调用差别不大。

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())

常见坑和我会怎么处理

常见问题

1. 免费模型不可用，先查隐私设置，别急着怀疑代码。
2. API 调用失败时，优先看三件事：密钥、模型名、余额或频率限制。模型名可以去 https://openrouter.ai/models 查。
3. 响应慢的时候，通常不是 OpenRouter 本身'坏了'，更多是模型本身慢，或者输出太长。先缩短 max_tokens，再考虑换模型。

实际上更稳的做法

1. dotenv 管密钥，不要硬编码。
2. 请求外面包一层 try-except，失败时至少能把错误信息打出来。
3. 原型阶段先用免费模型；生产里按任务选模型，别默认永远最贵，也别为了省钱把体验打没了。
4. 对话历史别无限堆，长了就是 token 成本。
5. 多看控制台里的调用统计，很多时候问题不是'模型不行'，而是你选型没对上任务。

还能继续往哪走

OpenRouter 跑通以后，后面可以做的事其实不少：批量请求、自定义路由、缓存常见结果、多模态模型接入，或者把它挂到 Web、桌面、移动端应用里。真正有价值的不是'接入了多少模型'，而是你能不能把模型选择变成可控的工程决策。

总结

OpenRouter 的价值很朴素：把原本分散的模型接口收拢成一套，少写适配，方便切换，也方便比较。它特别适合原型验证、模型选型和成本控制；如果你的项目后面还会换模型，这种统一入口会省很多事。