核心
API 参考
端点、认证、响应头与错误说明
概述
TokenLab 提供 OpenAI 兼容端点,也支持 Anthropic 和 Gemini 请求格式。现有 OpenAI 客户端可以直接使用 /v1;只有应用依赖某种 API 的特有行为时,才需要换成对应格式。POST /v1/responses 是可选端点,具体能力取决于模型。
基础 URL
https://api.tokenlab.sh认证
模型请求使用 TokenLab API 密钥,标准鉴权请求头为:
Authorization: Bearer sk-your-api-keyGET /v1/models、GET /v1/models/{model}、GET /v1/models/{model}/pricing 和 GET /v1/pricing 是公开接口,不需要密钥。Anthropic Messages 也接受 x-api-key;Gemini 除 Bearer 外,还接受 x-goog-api-key 或 ?key=。/v1/management/* 要求使用管理令牌(mt-...)。
在 Console 创建 API 密钥。
交付方式
生成请求可以通过 X-TokenLab-Delivery-Policy: auto | verified | official 选择交付方式。请求头优先于 API 密钥设置,API 密钥设置优先于工作区默认值。
Auto优先使用 TokenLab Verified,需要时改用 Official。你只需为最终完成请求的方式付费。TokenLab Verified是由 TokenLab 验证的交付方式,按 Verified 价格计费。Official按 Official 价格计费,即模型厂商公布的价格。- Realtime 会话使用 API 密钥或工作区设置,不接受请求覆盖。
请求头取值无效时返回 400。所选交付方式暂时不可用时返回 503 delivery_tier_unavailable,以及请求 ID。请读取 retryable:所选操作没有可用供应时,它为 false,请不要原样重复同一请求。
带请求表单的 API 页面可以输入 TokenLab API 密钥并发送真实请求,请求会使用你的账户余额和限额。也可以使用 cURL、Postman 或 SDK。
支持的端点
聊天与文字生成
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/chat/completions | POST | OpenAI 兼容 Chat Completions |
/v1/messages | POST | Anthropic Messages |
/v1/messages/count_tokens | POST | 统计 Messages 请求的输入 token 数 |
/v1/messages/batches | POST, GET | 创建和列出 Message Batches |
/v1/messages/batches/{message_batch_id} | GET, DELETE | 获取或删除 Message Batch |
/v1/messages/batches/{message_batch_id}/results | GET | 读取结果 |
/v1/messages/batches/{message_batch_id}/cancel | POST | 取消 Message Batch |
/v1/responses | POST | OpenAI Responses API |
/v1/responses/{id} | GET, DELETE | 获取或删除已保存的响应 |
/v1/responses/compact | POST | 压缩 Responses 对话的上下文 |
/v1/translations | POST | 文本到文本翻译 |
Embeddings 与 Rerank
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/embeddings | POST | 创建文字 Embeddings |
/v1/multimodal/embeddings | POST | 使用多模态 Embedding 模型生成向量 |
/v1/rerank | POST | 按相关性重排文档 |
决策
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/systemone | POST | 评估带类型的决策问题 |
文件与批处理
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/files | POST, GET | 上传和列出文件 |
/v1/files/{file_id} | GET, DELETE | 获取或删除文件 |
/v1/files/{file_id}/content | GET | 下载文件内容 |
/v1/batches | POST, GET | 创建和列出批处理 |
/v1/batches/{batch_id} | GET | 获取批处理 |
/v1/batches/{batch_id}/cancel | POST | 取消批处理 |
图像
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/images/generations | POST | 从文本生成图像 |
/v1/images/edits | POST | 编辑图像 |
/v1/images/variations | POST | 创建图像变体 |
/v1/images/generations/{id} | GET | 异步图片任务的兼容状态路径 |
图片模型可能直接返回成品,也可能返回异步任务。如果响应包含 status: "pending" 或任务 ID,请调用 GET /v1/tasks/{id} 查询。
音频
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/audio/speech | POST | 文本转语音 (TTS) |
/v1/audio/transcriptions | POST | 语音转文本 (STT) |
/v1/audio/translations | POST | 把语音翻译为英文文本 |
实时
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/realtime?model={model} | WS | 实时 WebSocket 会话 |
使用 /v1/realtime 建立 WebSocket 连接。普通 GET /v1/realtime 会返回端点信息。这不是 OpenAI Realtime REST API;client secret、Calls 和旧版 beta session 端点暂不支持。
视频
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/videos/generations | POST | 创建视频生成任务 |
/v1/videos/generations/{id} | GET | 兼容状态路径 |
/v1/videos/assets | POST, GET | 创建和列出 Seedance 素材 |
/api/v3/contents/generations/tasks | POST, GET | 使用火山引擎请求格式的 Seedance 任务 |
用任务 id 调用 GET /v1/tasks/{id} 查询。/v1/videos/generations/{id} 继续保留,供现有集成使用。
异步任务
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/tasks/{id} | GET | 查询任何异步任务的状态 |
/v1/tasks/{id} | DELETE | 取消异步任务 |
所有异步任务(图片、视频、音乐、3D、Worlds 和异步音频转写)都调用 GET /v1/tasks/{id} 查询,使用创建响应中的 id 或 task_id。Worlds 创建响应返回的 poll_url 位于 /v1/worlds/generations/{id},Worlds 也请调用 /v1/tasks/{id}。本页按类型划分的状态路径是兼容端点,供现有集成使用。
音乐
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/music/generations | POST | 创建音乐生成任务 |
/v1/music/generations/{id} | GET | 兼容状态路径 |
3D 生成
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/3d/generations | POST | 创建 3D 模型生成任务 |
/v1/3d/generations/{id} | GET | 兼容状态路径 |
Worlds
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/worlds/generations | POST | 创建 world 生成任务 |
/v1/worlds/list | POST | 列出 worlds |
/v1/worlds/{id} | GET, DELETE | 获取或删除 world |
/v1/worlds/media-assets/prepare-upload | POST | 准备媒体素材上传 |
模型与价格
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/models | GET | 列出所有可用模型 |
/v1/models/{model} | GET | 获取特定模型信息 |
/v1/models/{model}/pricing | GET | 获取单个模型的价格 |
/v1/pricing | GET | 列出模型价格 |
Gemini(v1beta)
原生 Google Gemini API 格式支持:
| 端点 | 方法 | 说明 |
|---|---|---|
/v1beta/models | GET | 列出接受 Gemini 请求的模型 |
/v1beta/models/{model} | GET | 获取模型 |
/v1beta/models/{model}:generateContent | POST | 生成内容 |
/v1beta/models/{model}:streamGenerateContent | POST | 流式生成内容 |
/v1beta/models/{model}:countTokens | POST | 统计 token 数 |
/v1beta/files、/v1beta/cachedContents | POST, GET, DELETE | Gemini Files 与缓存内容 |
Gemini 端点除标准的 Bearer token 外,还支持 ?key= 查询参数认证。
管理
/v1/management/* 使用管理令牌管理余额、API 密钥和 Webhook。参见管理 API。
响应格式
各端点保留对应 API 的响应格式。以下成功与错误示例采用 Chat Completions 格式。
成功响应
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1234567890,
"model": "gpt-5.6-terra",
"choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
"usage": {
"prompt_tokens": 10,
"completion_tokens": 20,
"total_tokens": 30
}
}响应头
存在下列响应头时可用于排查。
| 响应头 | 说明 |
|---|---|
X-Request-ID | 用于支持和排查问题的请求 ID |
X-Routing-Time-MS | 非流式:到上游返回为止的总用时(毫秒),含上游排队与推理。流式:固定为 0。不能用来判断排队或路由开销。 |
X-Task-ID | 任务型响应的公开异步任务标识 |
X-Billing-Transaction-ID | 最终计费后的计费交易标识 |
Official 请求拒绝可能包含 upstream,说明上游返回的错误及公开服务名称。参见处理 API 错误。
错误响应
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}速率限制
限制取决于账户等级,按 API 密钥计算。429 响应带有 Retry-After、X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。各等级的限制和重试方法见速率限制。
OpenAPI 规范
OpenAPI 规范
下载完整的 OpenAPI 3.1 规范