5 分钟内从 OpenAI 迁移至 TokenLab

更换服务商时，修改基础 URL（base URL）是最简单的部分，而迁移失败往往源于故障路径的处理。要从 OpenAI 迁移至 TokenLab，您只需更改 OpenAI SDK 客户端中的两个值：base_url 和 api_key。本指南的其余部分将介绍围绕此变更需要确认的事项，包括您发送的模型 ID、当前价格、流式传输、工具调用、错误处理、超时设置以及计费。以下事实均来自 TokenLab 文档及实时模型 API，并标注了观察日期。

关键要点

• 核心变更仅涉及两个值：TokenLab 的基础 URL https://api.tokenlab.sh/v1 以及 TokenLab API 密钥（以 sk- 开头）。
• TokenLab 支持 OpenAI SDK 的 Chat Completions 和 Responses。可选参数、工具选项以及仅限 Responses 的字段仍取决于所选模型。
• 在做出任何决定之前，请先从实时 API 读取您所选模型的价格。截至 2026 年 10 月 3 日，gpt-5.5 的价格为每百万 token 输入 1.50 美元，输出 9.00 美元。
• 在迁移生产流量之前，请先运行文末的检查清单。大多数意外情况发生在错误处理、超时和计费环节，而非正常路径中。

从 OpenAI 迁移至 TokenLab 的两项数值变更

首先从密钥开始。根据快速入门（观察于 2026-10-03），您需要创建一个账户，生成一个 API 密钥，并立即保存完整值。该值仅显示一次，且密钥列表中的前缀无法用于验证请求。在进行首次调用前请检查余额，因为请求将按所选模型的当前价格计费。

然后更改客户端。迁移指南（观察于 2026-10-03）描述的方法是：将 base_url / baseURL 设置为 https://api.tokenlab.sh/v1，替换密钥，并从 GET /v1/models 中选择一个模型 ID。

例如，假设某个服务在配置中使用了字符串 gpt-5.5。在完成这两项数值变更后，该字符串依然是一个有效的请求，但我们仍建议先确认该 ID。GET /v1/models 和 GET /v1/models/{model} 是公开的发现端点，无需密钥即可工作。

Python

import os
from openai import OpenAI

# 变更前: client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai';

// 变更前: new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
const client = new OpenAI({
  apiKey: process.env.TOKENLAB_API_KEY,
  baseURL: 'https://api.tokenlab.sh/v1',
  timeout: 30_000,
  maxRetries: 0,
});

const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Hello' }],
});
console.log(completion.choices[0].message.content);

cURL

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Say hello"}]}'

前两个示例中的超时和重试设置参考了快速入门示例（观察于 2026-10-03），即使用 30 秒超时和零 SDK 重试。我们在测试期间将重试次数保持为零，以便让失败的请求显现出来，而不是被静默重试。

请在客户端配置中显式传递基础 URL。SDK 指南（观察于 2026-10-03）建议这样做，而不是依赖旧的环境变量别名。请将密钥保存在服务器端和密钥管理器中，切勿将其放入客户端代码中。

选择模型 ID 并查看其价格

迁移时不应假设模型 ID 或价格。两者均存在于模型 API 中。我们在 2026-10-03 读取了 https://api.tokenlab.sh/v1/models/gpt-5.5 和 https://api.tokenlab.sh/v1/models/laguna-s-2.1。两者的定价均于 2026-10-02T16:53:30.068Z 最后更新。

字段	gpt-5.5	laguna-s-2.1
生命周期阶段	active	active
最大输入/输出 token	1,000,000 / 128,000	1,048,576 / 131,072
接受的请求格式	openai_chat_completions, openai_responses	openai_chat_completions
列出的功能	coding, json-mode, prompt-cache, reasoning, tool-use, vision	tool-use
输入，美元/百万 token	1.5	0.1
输出，美元/百万 token	9	0.2
缓存读取，美元/百万 token	0.15	0.01

来源：gpt-5.5 和 laguna-s-2.1，均观察于 2026-10-03。

为了将这些费率转化为具体金额，以下是计算示例。假设一项任务包含 100 万输入 token 和 10 万输出 token，且没有缓存命中。

• gpt-5.5: 1 × $1.50 + 0.1 × $9.00 = $1.50 + $0.90 = $2.40。
• laguna-s-2.1: 1 × $0.10 + 0.1 × $0.20 = $0.10 + $0.02 = $0.12。

这些是基于所列每 token 费率的估算值。您的最终费用以使用记录（Usage record）为准。Tokenization 方式因模型而异，因此相同的文本在不同模型上会产生不同的 token 计数。

我们在此不宣称节省成本。要与您当前的支出进行比较，请在切换当天将 TokenLab 的费率与您的 OpenAI 发票或 OpenAI 定价页面进行对比。价格会发生变化，计费指南（观察于 2026-10-03）建议不要硬编码复制的价格表，应调用 GET /v1/models/:model/pricing 获取当前值。

其他模型 ID 遵循相同的模式。文档示例在 Chat Completions 中使用了 gpt-5.6-terra 和 gpt-5.6-luna，并在各自的路由上使用了 claude-sonnet-5 和 gemini-3.5-flash。在将流量指向模型之前，请阅读每个模型接受的格式。如需更广泛的比较，请查看模型目录、OpenRouter 与 TokenLab 的对比以及模型排名。图像和视频团队可以从 2026 年最佳 AI 图像模型 API 和 2026 年最佳 AI 视频模型 API 开始。对于代码任务，请参阅最佳代码 AI 模型。

从 OpenAI 迁移至 TokenLab 后的后续检查项

TokenLab 文档指出 OpenAI SDK 可与 Chat Completions 和 Responses 配合使用。这指的是请求和响应格式的兼容性，并不保证每个模型的行为完全一致。API 格式指南（观察于 2026-10-03）指出，可选参数取决于模型。它还说明模型不一定接受所有四种 API 格式，tokenlab.accepted_request_formats 显示了该模型接受的格式。请将以下每个领域视为需要用真实流量进行测试的内容。

流式传输

stream: true 会以服务器发送事件（SSE）的形式发送部分消息增量。根据创建聊天补全参考（观察于 2026-10-03）的文档，设置 stream_options 中的 include_usage: true 即可在流块中接收 token 使用情况。

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Count to five."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")

需要规划两种行为。如果流在输出到达后被中断，请勿将其视为完整响应。错误处理指南（观察于 2026-10-03）警告称，重复该请求可能会产生不同的输出或导致二次计费。此外，流式传输可能会在计费完成前结束，因此计费 ID 可能缺失。

工具调用

Chat Completions 参考列出了 tools、tool_choice 和 parallel_tool_calls。文档称并行调用“在所选模型支持时”有效。函数调用被记录为“由所选模型支持”，因此请检查功能列表。在上述表格中，gpt-5.5 和 laguna-s-2.1 都列出了 tool-use，但只有 gpt-5.5 列出了 json-mode 和 vision。请发送您真实的工具架构，而非示例，并检查返回的参数是否可解析。

如果您计划调用 Claude 模型，请注意迁移指南中的规则。Claude 工具调用、思考块（thinking blocks）和 Anthropic 消息字段属于 /v1/messages，Chat Completions 不保证支持这些功能。

错误形态

Chat Completions 和 Responses 返回 OpenAI 风格的 error 对象。根据错误处理指南，只有 message 和 type 是始终存在的。code、param、retryable 和 retry_after 等字段仅在相关时出现。请基于 HTTP 状态码和 code 进行分支处理，而不是基于消息文本，并使您的解析器能够容忍缺失字段。Anthropic Messages 和 Gemini 保留其各自的错误格式，因此单一解析器无法覆盖所有路由。

状态码	代码	含义
401	invalid_api_key	密钥缺失、无效、未激活或已撤销
401	expired_api_key	密钥已过期
402	insufficient_balance	账户余额不足以支付请求
402	quota_exceeded	已达到该密钥的使用限额
403	model_not_allowed	该密钥无法使用请求的模型
429	rate_limit_exceeded	请求过多；等待 Retry-After

来源：身份验证 和 错误处理，观察于 2026-10-03。

此表纠正了一个常见假设。余额不足是 402，而非 401。如果您的现有代码将所有 4xx 视为密钥错误，请更新它。

超时与重试

迁移指南指出，现有的重试、超时和流式传输代码通常可以保留。请根据记录的重试规则进行审查。

• 不要原样重复 400、401、402、403、404 或 413 响应。
• 在服务器提供的延迟后重试 429。
• 仅在 retryable 为 true 时重试 500–504，并遵守 retry_after。
• 503 all_channels_failed 可能会返回 retryable: false。在这种情况下，所选交付层没有资源，重复请求无济于事。

请将响应头中的 Request ID 与模型及您自己的任务 ID 一起保存。这是进行调查时所需的关键信息。

计费

根据计费指南，一个余额适用于所有模型，没有订阅费或最低消费。每个完成的请求仅计费一次，按产生该结果的交付选项计费。选项包括 TokenLab Verified、Official 和 Auto，其中 Auto 会优先尝试 Verified，然后是 Official。如果您需要硬性停止，请为每个 API 密钥设置消费限额。达到限额后，使用该密钥的请求将返回 402。

非流式传输的 OpenAI 兼容响应在计费完成且响应发送前包含 billing_transaction_id。它也可能出现在 X-Billing-Transaction-ID 响应头中。请存储该 ID，并与“使用情况”（Usage）页面进行核对，而不是依赖您自己的 token 计算。

从 OpenAI 迁移至 TokenLab 后的验证清单

在生产流量迁移前，请使用测试密钥按顺序运行以下步骤。每一行都对应上述记录的行为。

步骤	运行内容	预期结果
1. 模型发现	GET /v1/models/gpt-5.5 (无需密钥)	生命周期为 active，且包含您计划使用的格式
2. 认证请求	上述 Python 或 cURL 示例	非空答案；请求出现在 Requests 视图中，包含模型、状态和使用情况
3. 使用情况字段	读取非流式响应中的 usage	prompt_tokens, completion_tokens, total_tokens
4. 流式传输	stream: true 且 include_usage: true	SSE 块，随后是 usage；中断的流被处理为不完整
5. 工具调用	您真实的 tools 和 tool_choice	参数可解析并符合您的架构
6. 视觉或 JSON 模式	仅当模型列出 vision 或 json-mode 时	预期输出；如果未列出该功能则跳过测试
7. 错误密钥	使用已删除或错误的密钥请求	401 invalid_api_key
8. 无余额或密钥限额	使用低限额的密钥或空工作区	402 insufficient_balance 或 quota_exceeded
9. 模型限制	限制密钥的模型列表，然后请求其他模型	403 model_not_allowed
10. 超时与重试	在测试环境中强制超时	您的代码仅根据 retryable 和 retry_after 进行重试
11. 计费	将 billing_transaction_id 和使用情况与您的估算值对比	费用与模型的当前价格及记录的 token 相符

通过上述检查后，更改生产配置并部署。在确认新路径稳定之前，请保持旧的 OpenAI 密钥处于激活状态。

常见问题解答

从 OpenAI 切换时，我需要更改模型名称吗？

不一定，但请务必确认每一个名称。TokenLab 模型 ID 是精确的字符串，请使用 GET /v1/models 或 GET /v1/models/{model} 进行核对。截至 2026-10-03，实时 API 将 gpt-5.5 列为 active。如果请求返回 model_not_found，则说明 ID 未知或不可用。请读取模型列表并使用当前的 ID。

流式传输和工具调用会表现得与 OpenAI API 完全一样吗？

TokenLab 通过 SSE 记录流式传输，并通过 OpenAI 兼容的请求格式记录函数调用。文档同时指出，支持的选项取决于所选模型。因此，我们将结果视为兼容，而非完全相同。请使用您计划运行的特定模型测试流式传输、tools、tool_choice 以及您使用的任何 response_format。

余额耗尽时会收到什么状态码？

您将收到 HTTP 402，代码为 insufficient_balance。达到自身消费限额的密钥也会返回 402，代码为 quota_exceeded。缺失、无效或已撤销的密钥返回 401。请勿原样重试这些请求。请充值余额、提高密钥限额或更换密钥。

我可以使用同一个 OpenAI 客户端调用 Claude 或 Gemini 模型吗？

模型目录将 claude-sonnet-5 和 gemini-3.5-flash 列为支持 openai_chat_completions 格式的模型。因此，基础聊天可以通过同一个客户端进行。Claude 特有的字段（如思考块和 Claude 工具使用）属于 /v1/messages。Gemini 原生字段保留在 /v1beta 路由上。请确保每次对话使用一种 API 格式。

开始在 TokenLab 上构建

在 TokenLab 创建密钥，将基础 URL 设置为 https://api.tokenlab.sh/v1，并在处理生产环境前运行快速入门请求。