Python 接入指南

OpenRouter Python 快速开始：OpenAI SDK、Base URL 与第一次请求

使用 OpenAI Python SDK 调用 OpenRouter：安装 openai，设置 OPENROUTER_API_KEY，将 base_url 设为 https://openrouter.ai/api/v1，再选择当前目录中的准确聊天模型 ID。调用 client.chat.completions.create 时，SDK 会自动追加 /chat/completions；应用归属 headers 为可选项。需要 OpenRouter 专属资源时，也可以使用独立的原生 openrouter 包。

最后复核 2026-09-27 · 编辑复核: KeepRouter Editorial

用 OpenAI Python SDK 完成第一次请求

1. 在运行脚本的 Python 环境中安装：python -m pip install openai。
2. 在该进程的环境变量或部署平台密钥存储中配置 OPENROUTER_API_KEY。必须使用 OpenRouter 签发的 Key，不能混用其他 Gateway 的凭证，也不要打印它。
3. 从 OpenRouter 模型目录选择聊天模型，将 OPENROUTER_MODEL 设为准确 ID。运行前检查该模型的价格和账户访问条件。
4. 将以下代码保存为 openrouter_test.py，在同一个环境中运行 python openrouter_test.py。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
    timeout=30.0,
    max_retries=0,
)
response = client.chat.completions.create(
    model=os.environ["OPENROUTER_MODEL"],
    messages=[{"role": "user", "content": "Return only the word ready"}],
    max_tokens=64,
)
print(response.choices[0].message.content)
print(response.usage.model_dump() if response.usage else "usage missing")

第一次测试关闭 SDK 自动重试，并将输出限制在 64 tokens，避免一次运行在后台变成多次尝试。请求可能按所选模型费率产生费用。本地出现 KeyError，表示 Python 进程读不到必需的环境变量，并不是 API 返回了认证失败。应检查变量名及终端、容器或部署平台使用的环境，不要通过打印变量值排查。

OpenRouter 将 HTTP-Referer 和 X-OpenRouter-Title 标为可选的应用归属 headers，因此最小示例省略它们。需要标识应用时再通过 extra_headers 添加，不要把 API secret 放进其值中。

什么时候使用 OpenRouter 原生 SDK

原生包使用另一套 client 和方法。安装 openrouter 后，可以复用上述环境变量：

import os
from openrouter import OpenRouter

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

固定经过测试的包版本。原生 SDK 的 resource 方法不能与 OpenAI SDK 互换，第一次文本响应也不能代替 async、streaming、tool call 与错误处理的验证。

最终 URL 如何组成

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 兼容契约。

迁移到 KeepRouter 的最小改动

KeepRouter 不把原生 openrouter package 作为客户端契约。保留 OpenAI SDK 方式，更换 Base URL、credential，并从 KeepRouter 实时目录选择兼容模型。将 KEEPROUTER_MODEL 设为该 ID，KEEPROUTER_KEY 设为允许它的 KeepRouter Key；付费模型还需要足够余额：

import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model=os.environ["KEEPROUTER_MODEL"],
    messages=[{"role": "user", "content": "Return only the word ready"}],
    max_tokens=64,
)
print(response.choices[0].message.content)

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

先用浏览器本地迁移检查器检查不含凭证的配置，并下载 Python 与 Node 示例包，从 dry-run 开始。实际兼容性仍需按准确线路与工作负载验证。

迁移付费流量前，按迁移检查表比较固定工作负载。API 费用计算器按当前 KeepRouter 目录费率估算用量；OpenRouter 基线需要按其费率和实际用量单独计算。已有 Key 只允许免费模型时，先完成免费转付费 Key 配置。

排查常见失败

生产验证

先运行确定性非流式请求，再测 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。

参考的一手资料

来源复核日期 2026-09-23

1. [1] OpenRouter quickstart and client SDK examples
2. [2] OpenRouter Python SDK
3. [3] OpenRouter OpenAI SDK integration
4. [4] OpenRouter provider routing
5. [5] OpenAI Python SDK
6. [6] KeepRouter OpenAPI

继续阅读

• api cost calculator
• 从 OpenRouter 迁移到 KeepRouter：核对 URL、模型 ID 与路由字段
• KeepRouter API Key 配置：从免费模型走到一次受控付费请求
• openai sdk
• 什么是 OpenAI 兼容 API？
• KeepRouter 对比 OpenRouter
• Vercel AI Gateway 对比 OpenRouter
• OpenAI 兼容 API 迁移清单
• errors
• models