统一 AI API 快速上手:一个 Key 调用所有模型

如果你现在要同时对接不止一家模型供应商,应该已经体会过这份"重复劳动税":每家一个 SDK、每家一种鉴权头格式、月底还要把好几张账单拼在一起对账。统一 AI API 把这些全部收拢成一个 base URL、一把 key、一种 OpenAI 兼容的请求格式——切换模型时只改 model 字段,接入代码本身不用动。

这是一篇动手向的快速上手教程。三步之内,你会从一个全新账号走到第一次成功调用,再往下延伸到流式响应和用量读取——这两块是真正跑起来之后才会在意的细节。

"统一 AI API" 具体指什么

说白了,统一 AI API 就是一个说 OpenAI 协议的入口,背后自动把每个请求路由到对应的上游模型。你不需要维护 N 套 SDK、N 组凭证、N 个各自独立的用量后台,只需要维护一份:

• 一个 base URL —— {gateway}/v1,和 api.openai.com/v1 是同一种形态。
• 一把 key —— 一个 sk-… 凭证就能认证目录里的所有模型。
• 一张账单 —— 各家模型的用量落在同一本流水里,按真实 token 数计费。

只要你现有代码已经是 OpenAI 协议的调用方式——官方 openai SDK、LangChain、LlamaIndex,或者一次原生的 fetch/requests 请求——切换成本就是改一行:把 base URL 指向网关,换上新 key。

第一步:注册账号,创建 API Key

注册后打开控制台 → API Keys,创建一个 key。明文 key(sk-…)只在创建那一刻显示一次,本站不会以可还原的形式保存它——务必当场把它存到安全的地方。

新账号注册后会自动获得试用额度,无需绑定信用卡,足够你先把下面的示例跑通再决定要不要正式投入。单个 key 还可以单独设置消费上限和可调用模型的白名单,超出范围的请求会被直接拒绝,而不是悄悄计费。

第二步:把 base URL 指向网关

这里有两个完全独立的面,值得先分清楚:

• 网关(数据面)——这是你的应用代码真正对话的对象。它是 OpenAI 兼容的 API:/chat/completions、/models,用你的 sk-… key 认证。
• 控制台(控制面)——这是你管理 key、查看用量、充值的地方。它不会代理 /v1 流量,你的 API 请求不会经过控制台中转。

在 SDK 暴露 base URL 的地方设置一次即可:

• JavaScript SDK:baseURL
• Python SDK:base_url
• 原生 HTTP:请求路径统一加上网关主机名前缀

对大多数代码库来说,这就是整个迁移工作:改一个配置值,其余的重试逻辑、超时设置、流式处理全部原样保留。

第三步:调用任意模型

key 和 base URL 都设置好之后,一个最小可用的 chat completion 请求长这样(curl):

curl https://api.apiko.example/v1/chat/completions \
  -H "Authorization: Bearer $APIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

不同模型之间唯一要改的就是 model 字段。可用的模型 id 以目录页为准(或者用自己的 key 请求 GET /v1/models)——目录会随着新渠道接入持续扩充,发起请求前建议先核对一下当前 key 能调用哪些 id。

直接用 OpenAI SDK

因为网关本身说的就是 OpenAI 协议,你不需要换一个新的客户端库,把现有客户端重新指向网关即可。

JavaScript:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.apiko.example/v1",
  apiKey: process.env.APIKO_API_KEY,
});

const res = await client.chat.completions.create({
  model: "claude-sonnet-4-5-20250929",
  messages: [{ role: "user", content: "Hello" }],
});

Python:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.apiko.example/v1",
    api_key=os.environ["APIKO_API_KEY"],
)

res = client.chat.completions.create(
    model="claude-sonnet-4-5-20250929",
    messages=[{"role": "user", "content": "Hello"}],
)

把 model 换成目录里的任意 id,其余调用方式完全不变——同样的鉴权头、同样的请求结构、同样的响应格式。这才是统一 AI API 真正的收益所在:一次接入工作,覆盖你以后会加的每一个模型,而不只是当下这一个。

流式响应,以及真实用量数字从哪来

把 "stream": true 传进去,拿到的就不是一整块 JSON,而是一连串 server-sent events——每个分片是一行 data:,以 data: [DONE] 收尾。对于聊天界面这类需要尽快看到首个响应片段的长耗时场景,这是保住响应体感的关键。

值得专门说一下的细节:带上 stream_options.include_usage,最后一个分片会携带真实的 token 用量——正是计费所用的那个数字。这很重要,因为请求发起时的估算和最终真实用量并不总是完全一致,直接从流里读这个数字就不用再猜。

curl -N https://api.apiko.example/v1/chat/completions \
  -H "Authorization: Bearer $APIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

Python 版本的同一套逻辑:

stream = client.chat.completions.create(
    model="claude-sonnet-4-5-20250929",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
    if chunk.usage:  # final chunk carries real token usage
        print(chunk.usage)

不管是否使用流式,计费都遵循同一套三段式机制:请求发出时先按估算预扣一部分余额,响应结束后按供应商返回的真实 token 用量结算,如果上游调用直接失败,预扣部分会自动退款——一次没有成功的请求不会计入你的账单。

排错时不用靠猜

错误响应遵循标准的 OpenAI 错误格式({"error": {"message", "type", "code"}}),现有的错误处理代码基本可以直接复用。以下几个状态码值得单独写处理逻辑:

| 状态码 | 常见原因 | 处理方式 | |---|---|---| | 401 | key 缺失或无效 | 检查 Authorization: Bearer 头,确认 key 没有被吊销 | | 402 / 403 | 余额不足 | 去控制台充值后重试 | | 404 | 未知的模型 id | 对照目录页和当前 key 的模型白名单核对 id | | 429 | 触发限流 | 指数退避重试,把突发请求分散开 | | 5xx | 上游故障 | 网关会自动跨渠道重试;如果仍然失败,预扣会自动退款,不计费 |

最后一行是最容易被忽略的一点:这里的 5xx 不代表你要为一次失败调用买单。重试发生在你调用的这同一个入口背后,失败即退款,不计费。

从上手到生产环境

第一次请求跑通之后,几个小习惯能让用量增长时的行为保持可预期:

1. 直接从 API 读用量,不要只看控制台面板。 流式响应的最后一个分片(或非流式响应的响应体)本身就带着真实 token 数——如果需要用程序对账,把这些数字和自己的请求 ID 一起记下来即可。
2. 按用途拆分 key。 因为一个 key 可以单独设置消费上限和模型白名单,给测试环境和生产环境、或者不同的内部服务分别发一把 key,比所有场景共用一把更稳妥。
3. 把模型 id 当配置项,而不是写死的常量。 既然切换模型只是改一行代码,从一开始就把它放进环境变量或配置文件——测试新模型、或者临时切换回另一个模型,都不需要改代码上线。
4. 调用前先查一下 /models。 目录反映的是当下真正可调用的内容,构建一个依赖某个模型的功能之前,先确认它确实在列表里。

以上都不需要额外的基础设施——都是第三步里那套请求结构,只是持续按这个方式使用而已。

现在就试试

判断统一 AI API 适不适合你的技术栈,最快的办法就是把上面三步跑一遍:创建一个 key,把现有的 OpenAI 兼容客户端指向网关,发起一次真实调用。新账号会自动获得试用额度,第一次请求前不需要额外配置任何东西。跑通之后,可以去 /pricing 查看当前各模型的实时 token 价格,或者直接去 /sign-up 创建一个 key。