核心指南
让 TokenLab 接入更可靠
控制费用、重试、API 密钥和请求记录
可靠的接入应该让用户知道自己选了什么模型、可能花多少钱；普通的网络中断不会产生重复任务；API 密钥也不会出现在浏览器里。下面的做法适用于聊天、图片、视频、音频等 TokenLab API。
用最新信息选择模型
模型名称、能力和价格会变化，不要在代码或文档里长期维护一张固定推荐表。请从 Models API 或模型页面读取最新信息。
新增一种用途时，可以这样判断：
- 按产品需要的能力筛选模型。
- 比较当前 TokenLab 价格。
- 用真实用户任务测试少量候选模型。
- 在每次请求里明确填写模型 ID。
不要悄悄替用户换模型。不同模型的输出质量、价格、上下文长度、工具和媒体能力都可能不同。
给费用设上限
使用文字模型时，把最大输出长度限制在产品真正用得上的范围内。不同 API 和模型使用的参数可能不同，发送 max_tokens 或 max_output_tokens 前请查看模型页面。
提示词不是越短越好，但重复的上下文和套话一定会增加输入 tokens。固定说明尽量简洁，只保留下一条回答真正需要的对话历史。
图片、视频、音乐、3D 和 Worlds 的费用通常与数量、时长、分辨率或其他生成选项有关。API 能提供预估时，费用较高的生成应在用户确认前展示当前预估。
长回答使用流式输出
流式输出会边生成边显示，让用户更早看到内容，但不会减少 token 费用。
包含客户端初始化和完成状态检查的完整示例，见流式传输。
连接中断时，这次回答仍未完成。不要把残缺内容标成成功，也不要在可能产生第二次副作用或收费时自动重发。
只重试可能恢复的错误
收到 429 后，按 Retry-After 响应头或 retry_after 字段等待。短暂的 5xx 错误可以使用有限次数的指数退避。鉴权、参数、余额和上下文长度错误需要应用或用户修改内容，原样重发没有用。
尊重 Retry-After、限制尝试次数并关闭 SDK 重复重试的完整示例，见请求速率限制。
重试要同时限制次数和总时长。媒体创建请求超时后，请用已经取得的任务 ID 查询，确认没有创建成功再重新提交。接口支持幂等键时，请为同一次用户操作复用同一个键。
API 密钥只放在服务端
不要把 TokenLab API 密钥写进浏览器 JavaScript、移动应用安装包、公开仓库或用户能看到的日志。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
timeout=30.0,
max_retries=0,
)开发、生产和不同应用分别使用独立 API 密钥，并只开放所需模型和额度。密钥可能泄露时应立即撤销。
保存有用的请求记录
下面这些信息可以把一次用户操作与用量、账单和支持记录对应起来：
- API 请求的
request_id - 异步生成的
task_id - 返回时的
billing_transaction_id - 模型 ID 和 API 地址
- 你自己的用户、项目或任务 ID
不要记录 API 密钥、管理令牌、完整的私密提示词、私密媒体或签名 URL。最终收费以 Console 和 Management API 的用量记录为准，模型响应中的 token 数不一定能完整说明费用。
正确处理异步生成
图片、视频、音乐、3D 和 Worlds 可能会在结果完成前返回。保存任务 ID，通过返回的 poll_url 查询，直到状态变为 completed 或 failed。一次状态查询失败，不代表生成任务已经失败。
取消、超时和重复提交的处理方式见异步任务与状态查询。
上线前检查
- 使用准备上线的模型和 API 格式发送真实示例。
- 同时验证成功响应和常见错误。
- 确认产品展示的价格与 TokenLab 当前价格一致。
- 页面刷新、网络超时和重复点击不会产生重复任务。
- 用户看到的结果能够对应到请求 ID。