Python 接入指南

如何用 Python 调用 OpenRouter：原生 SDK 与 OpenAI SDK

OpenRouter 当前有两条直接的 Python 接入路径：安装原生 `openrouter` 包，通过 `client.chat.send` 使用类型化 OpenRouter resources；或保留官方 `openai` 包，把 `base_url` 设为 `https://openrouter.ai/api/v1`。第二种更便于在 OpenAI 兼容 Gateway 之间迁移，但 OpenRouter 专属 provider routing、模型 fallback、headers 与扩展仍需产品专属代码。

最后复核 2026-08-26 · 编辑复核: KeepRouter Editorial

复制代码前先选客户端

OpenRouter 同时维护原生 Python SDK，也把 OpenAI Python SDK 作为另一种正式接入方式。两者都能发送聊天请求，但抽象边界不同。

Python 方案	安装	Client 与方法	适合情况
OpenRouter 原生 SDK	`pip install openrouter`	`OpenRouter(...).chat.send(...)`	需要类型化 OpenRouter resources，并计划使用其专属 API
OpenAI Python SDK	`pip install openai`	`OpenAI(base_url=...).chat.completions.create(...)`	已有 OpenAI 形态代码，或希望保持较小兼容边界
Raw HTTP	`pip install requests` 或现有 HTTP client	POST `/api/v1/chat/completions`	希望显式控制请求响应，不增加 SDK 依赖

方案一：OpenRouter 原生 Python SDK

import os
from openrouter import OpenRouter

with OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"]) as client:
    response = client.chat.send(
        model="openai/gpt-4",
        messages=[
            {"role": "user", "content": "Return only the word ready"}
        ],
        stream=False,
    )
    print(response)

官方 SDK 还暴露单次 chat 之外的 resources。应用明确绑定 OpenRouter 时，这种方式更自然。应固定 SDK 版本，并分别测试 async、streaming、tools 与错误对象，不能用第一次文本请求代替完整验证。

方案二：OpenAI Python SDK

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

response = client.chat.completions.create(
    model="openai/gpt-4",
    messages=[
        {"role": "user", "content": "Return only the word ready"}
    ],
    extra_headers={
        "HTTP-Referer": "https://example.com",
        "X-OpenRouter-Title": "Example app",
    },
)

print(response.choices[0].message.content)

OpenRouter quickstart 把这两个 attribution headers 标为可选。不要把 secret 放进 header value。API Key 应放在环境变量或 secret manager，不能写进源码或浏览器代码。

最终 URL 如何组成

部分	值
SDK Base URL	`https://openrouter.ai/api/v1`
SDK 追加的 chat operation	`/chat/completions`
最终请求 URL	`https://openrouter.ai/api/v1/chat/completions`

Base URL 缺少 /api/v1 时，SDK 会调用未记录为正式 API 的路径。如果应用自己追加 /chat/completions，SDK 又追加一次，就会形成重复路径。排查 404 时可以记录 host 与 path，但不要记录 credential。

OpenRouter 专属字段不会自动迁移

OpenRouter 支持 provider preferences、fallback model list、routing variants、attribution headers 与其他扩展。使用 OpenAI SDK 时，其中一些通过 extra_body 或 extra_headers 传入。这些字段不属于通用 OpenAI 兼容契约。

字段或行为	能否在兼容 Gateway 间直接迁移	迁移动作
`messages` 与基本 chat roles	已实现 chat route 时通常可以	重放代表性请求
Base URL 与 API Key	不可以	全部替换
Model slug	不可以	映射到目标目录的准确 ID
Provider order、only、ZDR、路由排序	不可以	删除，或按目标产品公开控制重建
OpenRouter attribution headers	不可以	目标未记录对等字段时删除
Streaming 与 tools	语法可能相似，行为可能不同	测试事件顺序、arguments、续轮、错误与取消

迁移到 KeepRouter 的最小改动

KeepRouter 不把原生 openrouter package 作为客户端契约。保留 OpenAI SDK 方式，更换 Base URL、credential，并从 KeepRouter 实时目录选择兼容模型：

client = OpenAI(
    base_url="https://keeprouter.com/v1",
    api_key=os.environ["KEEPROUTER_KEY"],
)

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=[{"role": "user", "content": "Return only the word ready"}],
)

删除 OpenRouter 专属 extra_body 与 attribution headers，除非目标 API 明确记录对等项。确认所选 KeepRouter 模型支持 Chat Completions。当前可用性和价格以 /models为准，不能依赖静态教程。OpenAI SDK Base URL 指南提供 KeepRouter 侧 Python 与 Node 排错。

排查常见失败

现象	优先检查
401 或认证错误	环境变量存在，Key 没有引号或空格，请求抵达预期 host
404	OpenRouter Base URL 正好包含 `/api/v1`，operation path 没有重复
Model not found	使用当前 OpenRouter model slug 或目标 Gateway 当前 ID，命名空间不共享
不加 provider rule 能成功，加上后失败	合格 provider 集、数据政策、ZDR、最高价格与 fallback 限制
Stream 在 tool call 后中断	Tool-result 续轮、事件解析、模型支持与 SDK 版本
迁移后能编译但输出变化	模型版本、线路、system prompt、tool schema、采样参数与 fallback 路径

生产验证

先运行确定性非流式请求，再测 streaming，最后跑一次真实 tool round trip。记录返回模型或线路证据、token usage、error body 与实际扣费。限制 retry 次数，不要自动重放可能触发外部副作用的请求。

常见问题

OpenRouter 有官方 Python SDK 吗？

有。当前 package 名为 openrouter，其类型化 client 提供同步与异步 resources。OpenRouter 也把 OpenAI Python SDK 记录为另一种接入。

OpenAI SDK 使用什么 OpenRouter Base URL？

使用 https://openrouter.ai/api/v1。OpenAI SDK 会继续追加 /chat/completions 等 operation path。

HTTP-Referer 与 X-OpenRouter-Title 是必需的吗？

不是。OpenRouter quickstart 把它们标为可选 attribution headers，不能把 API secret 放入任一 value。

OpenRouter 原生 SDK 能调用 KeepRouter 吗？

这不是 KeepRouter 客户端契约。应使用 OpenAI 兼容 client 或特定路由 HTTP client，并遵循所选 KeepRouter 模型公开的 endpoint。

为什么同一模型在一个 Gateway 能用，在另一个不能？

目录命名空间、模型版本、合格 provider、endpoint 支持、policy filter 与账户权限都属于具体产品。应映射准确 ID 和 route，不能直接复制 slug。