# 如何用 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 · [编辑复核](https://keeprouter.com/editorial-policy#editorial-team)_

## 复制代码前先选客户端

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

```python
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

```python
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 实时目录](/models)选择兼容模型：

```python
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](/models)为准，不能依赖静态教程。[OpenAI SDK Base URL 指南](/use-cases/openai-sdk)提供 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。

## 参考的一手资料

1. [OpenRouter quickstart and client SDK examples](https://openrouter.ai/docs/quickstart)
2. [OpenRouter Python SDK](https://openrouter.ai/docs/client-sdks/python/overview)
3. [OpenRouter OpenAI SDK integration](https://openrouter.ai/docs/guides/community/openai-sdk)
4. [OpenRouter provider routing](https://openrouter.ai/docs/guides/routing/provider-selection)
5. [OpenAI Python SDK](https://github.com/openai/openai-python)
6. [KeepRouter OpenAPI](https://keeprouter.com/api/openapi.json)

## 继续阅读

- [openai sdk](https://keeprouter.com/use-cases/openai-sdk.md)
- [什么是 OpenAI 兼容 API？](https://keeprouter.com/zh/answers/what-is-an-openai-compatible-api.md)
- [KeepRouter 对比 OpenRouter](https://keeprouter.com/zh/compare/openrouter.md)
- [Vercel AI Gateway 对比 OpenRouter](https://keeprouter.com/zh/compare/vercel-ai-gateway-vs-openrouter.md)
- [OpenAI 兼容 API 迁移清单](https://keeprouter.com/zh/blog/openai-compatible-api-migration-checklist.md)
- [errors](https://keeprouter.com/docs/errors.md)
- [models](https://keeprouter.com/models.md)

## 测试可迁移路径

从有边界的 OpenAI 形态 chat 请求开始，删除产品专属路由字段，映射一个准确目标模型，再比较响应、usage、错误与扣费。

[创建免费 Key](https://keeprouter.com/login?returnTo=%2Fconsole%2Fkeys%3Fmodel%3Dfree) · [实时模型与价格](https://keeprouter.com/models.md)