核心

API 参考

端点、认证、响应头与错误说明

概述

TokenLab 提供 OpenAI 兼容端点,也支持 Anthropic 和 Gemini 请求格式。现有 OpenAI 客户端可以直接使用 /v1;只有应用依赖某种 API 的特有行为时,才需要换成对应格式。POST /v1/responses 是可选端点,具体能力取决于模型。

基础 URL

https://api.tokenlab.sh

认证

模型请求使用 TokenLab API 密钥,标准鉴权请求头为:

Authorization: Bearer sk-your-api-key

GET /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/completionsPOSTOpenAI 兼容 Chat Completions
/v1/messagesPOSTAnthropic Messages
/v1/messages/count_tokensPOST统计 Messages 请求的输入 token 数
/v1/messages/batchesPOST, GET创建和列出 Message Batches
/v1/messages/batches/{message_batch_id}GET, DELETE获取或删除 Message Batch
/v1/messages/batches/{message_batch_id}/resultsGET读取结果
/v1/messages/batches/{message_batch_id}/cancelPOST取消 Message Batch
/v1/responsesPOSTOpenAI Responses API
/v1/responses/{id}GET, DELETE获取或删除已保存的响应
/v1/responses/compactPOST压缩 Responses 对话的上下文
/v1/translationsPOST文本到文本翻译

Embeddings 与 Rerank

端点方法说明
/v1/embeddingsPOST创建文字 Embeddings
/v1/multimodal/embeddingsPOST使用多模态 Embedding 模型生成向量
/v1/rerankPOST按相关性重排文档

决策

端点方法说明
/v1/systemonePOST评估带类型的决策问题

文件与批处理

端点方法说明
/v1/filesPOST, GET上传和列出文件
/v1/files/{file_id}GET, DELETE获取或删除文件
/v1/files/{file_id}/contentGET下载文件内容
/v1/batchesPOST, GET创建和列出批处理
/v1/batches/{batch_id}GET获取批处理
/v1/batches/{batch_id}/cancelPOST取消批处理

图像

端点方法说明
/v1/images/generationsPOST从文本生成图像
/v1/images/editsPOST编辑图像
/v1/images/variationsPOST创建图像变体
/v1/images/generations/{id}GET异步图片任务的兼容状态路径

图片模型可能直接返回成品,也可能返回异步任务。如果响应包含 status: "pending" 或任务 ID,请调用 GET /v1/tasks/{id} 查询。

音频

端点方法说明
/v1/audio/speechPOST文本转语音 (TTS)
/v1/audio/transcriptionsPOST语音转文本 (STT)
/v1/audio/translationsPOST把语音翻译为英文文本

实时

端点方法说明
/v1/realtime?model={model}WS实时 WebSocket 会话

使用 /v1/realtime 建立 WebSocket 连接。普通 GET /v1/realtime 会返回端点信息。这不是 OpenAI Realtime REST API;client secret、Calls 和旧版 beta session 端点暂不支持。

视频

端点方法说明
/v1/videos/generationsPOST创建视频生成任务
/v1/videos/generations/{id}GET兼容状态路径
/v1/videos/assetsPOST, GET创建和列出 Seedance 素材
/api/v3/contents/generations/tasksPOST, 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/generationsPOST创建音乐生成任务
/v1/music/generations/{id}GET兼容状态路径

3D 生成

端点方法说明
/v1/3d/generationsPOST创建 3D 模型生成任务
/v1/3d/generations/{id}GET兼容状态路径

Worlds

端点方法说明
/v1/worlds/generationsPOST创建 world 生成任务
/v1/worlds/listPOST列出 worlds
/v1/worlds/{id}GET, DELETE获取或删除 world
/v1/worlds/media-assets/prepare-uploadPOST准备媒体素材上传

模型与价格

端点方法说明
/v1/modelsGET列出所有可用模型
/v1/models/{model}GET获取特定模型信息
/v1/models/{model}/pricingGET获取单个模型的价格
/v1/pricingGET列出模型价格

Gemini(v1beta)

原生 Google Gemini API 格式支持:

端点方法说明
/v1beta/modelsGET列出接受 Gemini 请求的模型
/v1beta/models/{model}GET获取模型
/v1beta/models/{model}:generateContentPOST生成内容
/v1beta/models/{model}:streamGenerateContentPOST流式生成内容
/v1beta/models/{model}:countTokensPOST统计 token 数
/v1beta/files、/v1beta/cachedContentsPOST, GET, DELETEGemini 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 规范

本页内容