用 OpenAI SDK 调用任意模型

2026年10月25日 · Hyperouter · 阅读约 2 分钟

Hyperouter 兼容 OpenAI 的 API。任何 OpenAI SDK 只需改两处即可使用：base URL 和 API 密钥。本指南用 Python 和 TypeScript 分别完成一次对话调用和一次图像调用。

1. 获取密钥

使用 Google 或 GitHub 登录并创建 API 密钥。密钥以 sk-hr-v1- 开头，且只显示一次，请将它保存在环境变量中：

export HYPEROUTER_API_KEY="sk-hr-v1-..."

请求费用从预付余额中扣除：首次调用前，请先在控制台提交充值申请。密钥只应保存在服务器端，切勿放进浏览器或移动端代码。

2. 将 SDK 指向 Hyperouter

base URL 为 https://api.hyperouter.app/v1。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hyperouter.app/v1",
    api_key=os.environ["HYPEROUTER_API_KEY"],
)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.hyperouter.app/v1",
  apiKey: process.env.HYPEROUTER_API_KEY,
});

3. 对话

用 Hyperouter 的模型 id（<provider>/<name>）指定模型。下面的调用使用 xAI 的 Grok 4.3：

res = client.chat.completions.create(
    model="x-ai/grok-4.3",
    messages=[{"role": "user", "content": "Explain idempotency in one sentence."}],
)
print(res.choices[0].message.content)

const res = await client.chat.completions.create({
  model: "x-ai/grok-4.3",
  messages: [{ role: "user", content: "Explain idempotency in one sentence." }],
});
console.log(res.choices[0].message.content);

返回结果就是 OpenAI 的 chat completion，另外多了两个字段：provider 是实际处理请求的服务商，usage.cost 是本次费用（美元）。设置 stream: true 即可像使用 OpenAI 一样接收 server-sent events。

如果希望首选模型的所有服务商都失败时回退到其他模型，把它们列在 models 中。OpenAI SDK 将其作为额外的请求体字段发送：

res = client.chat.completions.create(
    model="x-ai/grok-4.3",
    messages=[{"role": "user", "content": "Hello"}],
    extra_body={"models": ["x-ai/grok-4.20-0309-non-reasoning"]},
)

4. 图像

Images API 的用法相同。下面的调用用 Grok Imagine 生成一张图片：

img = client.images.generate(
    model="x-ai/grok-imagine-image",
    prompt="A lighthouse at dusk",
)
print(img.data[0].url)

const img = await client.images.generate({
  model: "x-ai/grok-imagine-image",
  prompt: "A lighthouse at dusk",
});
console.log(img.data?.[0]?.url);

返回的链接经过签名，有效期 24 小时；GET /v1/generations/{id} 会重新签发一个新链接。qwen/qwen-image-2.0 的调用方式相同。对于同步返回结果的模型，如果图像在 90 秒内仍未完成，请求会返回 503、错误码 timeout 及其 generation_id；等待结果一节说明了如何改为轮询获取结果。

下一步

• GET /v1/models 列出你的账户可调用的所有模型，包括价格和每个模型支持的参数。
• Chat completions 参考介绍了流式输出、工具调用和用于路由的 provider 对象。
• 重试与幂等说明了何时可以安全重试。