跳转到主要内容
本页说明维护中的共享 tokenlab-api-integration skill。规范分发源位于 hedging8563/tokenlab-skills，公开仓库有意只保留这个 skill。
本页用于 skill 安装和 agent 工作流说明。端点、SDK 或客户端配置请查看对应工具的专门集成页或 API Reference。

​
这个技能做什么

  • 为 TokenLab 聊天、图像、音频、视频、翻译等 API 家族生成最小可运行示例。
  • OpenAI 兼容客户端使用 https://api.tokenlab.sh/v1，并说明何时切到 Anthropic 或 Gemini 原生路由。
  • 通过 /v1/models、/llms.txt 和 recommended_for 推荐列表发现模型，而不是依赖陈旧的本地列表。
  • 非聊天请求重试前读取模型模型说明，避免静默丢弃不支持的字段。
  • 处理 did_you_mean、suggestions、retry_after、recommended_request 等 Agent-First 错误提示。

​
安装

请使用规范的非交互式安装命令：
npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
这会从 TokenLab skills 仓库安装共享的 tokenlab-api-integration skill。如果你的工具不支持安装器，请把仓库里的 skills/tokenlab-api-integration/ 复制到工具的共享 skills 或 rules 目录。

​
更新既有安装

如果你是在 TokenLab skills 仓库清理前安装的，请重新运行同一条命令。当前公开包更小，也不再依赖生成式本地搜索脚本。

​
验证安装

询问你的 coding agent： 
有哪些可用的 skills？
如果能看到 tokenlab-api-integration，表示安装成功。

​
获取 API Key

1

访问 TokenLab

前往 tokenlab.sh
2

登录

创建账户或登录
3

获取 API Key

打开 Dashboard → API Keys 并创建新 key
4

复制 key

你的 key 以 sk-... 开头，请妥善保存。
不要把 API key 粘贴到提示词或源码里。skill 应询问要使用哪个环境变量，并生成从该变量读取 key 的代码。

​
推荐的 Agent 工作流

  1. 先生成匹配用户语言和 API 家族的最小可运行示例。
  2. 模型选择未确定时，先调用 /v1/models 或 https://api.tokenlab.sh/llms.txt，不要硬编码。
  3. 非聊天任务先调用 /v1/models?recommended_for=<scene>，其中 <scene> 可为 image、video、music、3d、tts、stt、embedding、rerank 或 translation。
  4. 修改失败的非聊天请求前，读取 /v1/models/:model，并对齐 supported_operations、supported_parameters、request_endpoint, request_endpoint_by_operation、request_shape_mode 和 recommended_request。
  5. 如果 API 返回 Agent-First 错误，使用结构化字段修正请求；只有 retryable 表示可重试时才重试。

​
最小聊天示例

这个示例使用 OpenAI Python SDK 和 TokenLab base URL： 
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)
运行方式： 
pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.py

​
模型发现与模型说明

优先使用实时发现，不依赖陈旧的打包列表： 
# 机器可读 API 概览
curl https://api.tokenlab.sh/llms.txt

# 列出模型
curl "https://api.tokenlab.sh/v1/models" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?category=image" -H "Authorization: Bearer sk-KEY"

# 非聊天场景推荐列表
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=translation" -H "Authorization: Bearer sk-KEY"

# 非聊天请求重试前读取单一模型模型说明
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# 仅价格详情
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"

​
原生路由提示

常见聊天、Responses、图像、嵌入、音频和 rerank 示例默认走 OpenAI 兼容 /v1。只有请求需要供应商特定行为，或 TokenLab 返回 X-TokenLab-Native-Endpoint 优化提示时，才切换 Anthropic 或 Gemini 原生路由。 
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages

​
Agent-First 错误恢复

错误响应包含 coding agent 可直接解析的字段：
错误有用字段Agent 处理方式
模型名称错误did_you_mean, suggestions, hint使用修正后的模型或推荐替代项重试
余额不足balance_usd, estimated_cost_usd, suggestions请求用户确认，或切换到可负担模型
速率限制或临时不可用retryable, retry_after, alternatives等待后重试，或选择列出的替代模型
非聊天请求不兼容supported_operations, supported_parameters, request_endpoint, request_endpoint_by_operation, request_shape_mode, recommended_request按模型说明重建请求；会改变意图的字段必须 return a clear error

​
支持的 API 家族

家族主要路径
聊天与 Responses/v1/chat/completions, /v1/responses
Claude 原生 messages/v1/messages
Gemini 原生请求/v1beta/models/{model}:generateContent
图像/v1/images/generations, /v1/images/edits
视频/v1/videos/generations
音乐/v1/music/generations
Worlds/v1/worlds/generations 以及 world 状态和媒体资产端点
3D/v1/3d/generations
音频/v1/audio/speech, /v1/audio/transcriptions, /v1/audio/translations
Realtime/v1/realtime?model={model}
嵌入与 rerank/v1/embeddings, /v1/rerank
文本翻译/v1/translations

​
最佳实践

API Key 安全

使用环境变量和服务端调用，不要在前端代码里暴露 key。

非聊天先看契约

重试图像、视频、音乐、3D、翻译、音频、嵌入或 rerank 请求前，先读取 /v1/models?recommended_for=... 和 /v1/models/:model。

最小可运行示例

先生成一个能跑通的调用，再添加抽象、队列或 UI 流程。

使用结构化提示

修改代码前先解析 did_you_mean、retry_after、alternatives 和 recommended_request。

​
FAQ

在请求中提到 “TokenLab” 或 “TokenLab API”，例如：用 TokenLab 给我的 Node.js 应用添加图像生成。
任何支持共享 skill 或 rules 目录的 coding agent 都可以使用这个文件夹。skills 安装器会自动处理支持的 agent。
重新运行安装命令即可，它会从规范公开仓库刷新本地副本。
npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y

​
资源

Agent-First API

结构化错误提示和恢复行为

API 文档

端点配置和 API Reference

模型

浏览可用模型

llms.txt

面向 agents 的机器可读 API 概览
有问题？请使用 GitHub Issues 或联系 support@tokenlab.sh。