TokenLab API Integration

Current public roots

• API root: https://api.tokenlab.sh
• OpenAI-compatible base URL: https://api.tokenlab.sh/v1
• Anthropic SDK base URL: https://api.tokenlab.sh（不要自行追加 /v1）
• Docs: https://tokenlab.sh/docs
• Model catalog: GET https://api.tokenlab.sh/v1/models
• Model detail: GET https://api.tokenlab.sh/v1/models/{id}
• OpenAPI: https://tokenlab.sh/docs/openapi.json
• Auth: Authorization: Bearer $TOKENLAB_API_KEY，或由原生 SDK 按其协议发送 key

Required workflow

1. 明确任务类型、同步/异步需求、输入输出媒体和调用方支持的协议。
2. 对所有非 chat 请求，先调用 /v1/models?category=<category>；不要把示例模型名当作实时可用性。
3. 对准备使用的模型再调用 /v1/models/{id}，读取 tokenlab.accepted_request_formats、tokenlab.capabilities、token 上限、价格与公开 request contract。
4. 根据公开 detail contract 选择 endpoint；禁止按模型名 substring、供应商印象或物理渠道字段推断。
5. 只发送所选 endpoint 声明的 request shape。不要把 Responses、Messages、Gemini 和 Chat payload 相互拍平或混用字段。
6. 请求失败时保留原始语义；只根据结构化 error 或用户明确选择重试。不得为了得到 HTTP 200 删除历史、工具调用、思考签名或媒体输入。
7. 原始 HTTP 异步响应读取顶层 id / task_id / poll_url / status；MCP 工具结果才读取标准化 delivery。以 status 判终态，不用缺失的 progress 推断成功。
8. 代码必须从环境变量读 key，传播超时与取消信号，并在结束时关闭流/reader。

可先运行本 Skill 的只读发现脚本：

python skills/tokenlab-api-integration/scripts/search_api.py --category video --limit 20
python skills/tokenlab-api-integration/scripts/search_api.py --detail claude-sonnet-4-6

Codex 客户端接入

用户需要把 Codex 的模型提供商设为 TokenLab 时，可使用本 Skill 的 scripts/configure_codex.py。它需要 Python 3.11+ 与支持独立 profile 文件的 Codex；不需要安装 Python 依赖，也不安装客户端。

先阅读 references/codex_setup.md，确认实际 CODEX_HOME 和客户端版本。模型必须来自当前 Responses 契约。先预览，只有明确执行配置时才使用 --apply；本机测试指定临时 --codex-home。保留用户账户、默认模型和权限，不能覆盖同名的非本工具 profile，也不要迁移旧配置来规避冲突。

配置只引用 TOKENLAB_API_KEY，不接受密钥命令参数、不打印已有配置。配置成功、客户端实际加载和付费请求成功分别验证。恢复也先预览；遇到用户后续编辑时停止覆盖。MCP/Skills 安装不等同于主模型提供商接入。

Claude Code 客户端接入

使用 references/claude_setup.md 中的 scripts/configure_claude.py 创建显式启动器。它需要 Python 3.11+、Claude Code 2.1.263+ 和用户明确选择的 Messages 模型；先预览，再在用户已要求执行配置时加 --apply。普通 claude 的账户、默认模型与权限配置保持原样。

启动器通过子进程环境将 TOKENLAB_API_KEY 交给 Claude 的 Bearer 认证，按次传入不含密钥的 --settings 与指定 --model。不能把环境变量名当成 JSON 中会展开的密钥。发现已有 settings 中的 Bearer、模型映射或托管策略冲突时停止，不删用户配置或绕过组织策略。WSL 继承策略尚未验证，此首切片不自动接入。--auth-status 只检查本地认证来源，不代表 Key 有效或请求成功。

OpenCode 与 Pi 客户端接入

用户明确需要配置客户端时，使用 OpenCode 接入说明 的 scripts/configure_opencode.py 或 Pi 接入说明 的 scripts/configure_pi.py。两者要求 Python 3.11+；实际客户端验证固定为 OpenCode 1.18.31 与 Pi 0.85.1，不把这些结果泛化为所有版本或 WSL。模型须明确选择并声明 Chat Completions 契约。

先预览；用户已要求执行配置时继续 --apply。OpenCode 生成按次通过 OPENCODE_CONFIG 加载的独立配置层，同时显式传入 --model tokenlab/<model>，避免改变普通启动的隐式默认提供商。Pi 把 provider 追加到现有条目之后，显式用 --provider tokenlab --model <model> 启动，保留原默认设置和账号。脚本只写环境变量引用，不能传真实 Key 参数，也不能为了通过冲突检查删除原提供商、账户或权限配置。

两者保留原始字节备份，重复执行幂等，遇到后续编辑或同名冲突停止覆盖。按对应说明用 --restore 恢复；配置成功、真实客户端加载、实际付费请求分别验证。测试只用临时目录和虚构凭据。

Hermes 客户端接入

使用 Hermes 接入说明 和 scripts/configure_hermes.py 为官方 Hermes 0.21.3 新增命名 provider。用已安装 Hermes 的 Python 运行，或通过 --hermes-python 明确指定它；不在全局 Python 安装依赖。先检测实际 HERMES_HOME、当前 profile 和版本，再预览并按已授权的配置任务执行 --apply。

仅增量插入 providers.tokenlab，使用 key_env: TOKENLAB_API_KEY；保留 YAML 注释、已有默认模型、账号和权限。普通启动保持原选择；每次使用教程给出的明确 home/provider/model 启动方式。同名配置、凭据、托管设置、后续编辑或不明确的 YAML 拒绝覆盖，不能通过运行模型向导或删除设置绕过。--restore 可在 Hermes 已卸载时恢复原字节。WSL 和托管配置不属于本次自动接入范围。配置创建、实际客户端加载及付费请求分别说明，不能把其中一种当成另一种成功。

Protocol selection

模型列表适合筛选。聊天协议 eligibility 以模型详情中的 tokenlab.accepted_request_formats 为准；决策与其他非 chat 操作以 tokenlab.public_contract.public_operations、request_endpoint / request_endpoint_by_operation 为准。决策模型可以没有聊天格式，不能因空 accepted_request_formats 拒绝其已声明的 System One 操作。

规则：

• 同一个 agent/harness model entry 只绑定一个首选协议，避免模型选择器重复。
• Claude/Gemini 的原生字段必须留在 Messages/Gemini endpoint。
• Responses 不是 Chat 的同义词；只有 detail contract 声明支持且客户端真的实现 Responses 时才使用。
• 当前 DeepSeek Harness custom provider 支持 openai-responses、anthropic-messages、openai-completions，不支持配置 Gemini native；因此 Gemini 在 Harness 中只能走其公开声明的 Chat fallback。
• 聊天接入若 accepted_request_formats 缺失或不包含调用方协议，fail closed：换模型或换客户端。非 chat 接入若没有所需公开 operation/endpoint，同样拒绝猜测请求。

DeepSeek Harness bundle

使用公开 @tokenlabai/dsh-provider bundle 时先核对 npm 版本、固定 MCP 版本与 Harness peers。保持 Responses、Messages、Chat 三条互斥聊天路由。Jev 等决策模型通过 MCP evaluate_decisions 调用原生 System One，不进入聊天模型列表，也不交给异步 waiter。Webhook 管理工具使用 full profile 与单独的 TOKENLAB_MANAGEMENT_TOKEN；Harness 会过滤继承的凭据环境变量，bundle 必须显式传给 MCP 子进程。管理 token 与推理 key 不可互相替代。

Endpoint map

不要从这张表猜具体模型参数。非 chat endpoint 先读取当前模型 detail/OpenAPI；图像尺寸、视频 duration、reference media、音色、格式等限制由所选模型公开 contract 决定。

System One decisions

先读取 /v1/models?category=decision 和模型详情，确认 systemone 与 /v1/systemone。Jev 1.13 的公开模型 ID 为 jev-1.13，示例仍须核对实时目录。

• 请求只有 model、state、questions；state 与 instructions 可为字符串、JSON 对象或数组。
• noul 返回 yes 概率；choice 从具名选项中选择；score 对 2–10 个有序描述等级评分，可为小数。不要把 score 当成精确金额或日期计算。
• 保留 answers 下的题名、概率分布、confidence 和 usage。缺少 confidence 时不要补成 1；confidence 不是正确率保证。输出免费也须保留非零 output tokens。
• 原生同步决策接口没有 messages、input、stream、tools 或 Batch 字段；不要改走 Chat/Responses/Messages/Gemini。
• 判定结果不执行动作，也不授予退款、转账等权限。阈值、校验、授权及副作用由业务代码控制。
• MCP 使用已发行版本声明的 evaluate_decisions；若工具不存在，升级 MCP 或按原生 HTTP 契约调用，不冒充其他工具。

Async contract

视频、音乐、3D 一律按异步任务处理；图像可能同步也可能异步。原始 HTTP 响应的任务标识、状态和查询地址位于顶层，不能因缺少 delivery 就判定为同步。MCP 工具会将原始响应放进 response 并添加标准化 delivery：

{
  "delivery": {
    "mode": "async",
    "task_id": "ldtask_...",
    "status": "pending",
    "poll_url": "/v1/tasks/ldtask_...",
    "terminal": false
  },
  "response": {}
}

实现必须：

• MCP 的 delivery.mode === "complete" 时直接处理结果；async 时保留 task id 和 poll URL。原始 HTTP 使用顶层任务字段，内联图像结果可直接消费。
• 优先使用返回的 poll_url；通用 video/music/3D 可用 /v1/tasks/{id}。
• pending / processing 是非终态；completed / failed 是通用终态。兼容 endpoint 还可能返回 succeeded / cancelled / expired，按对应 OpenAPI 处理。
• 使用有上限的 polling interval、整体 timeout 和 AbortSignal/context cancellation；如需重试 GET 查询，限制暂态重试次数，401/403/404/大多数 4xx 不重试。不要因等待失败自动重新提交生成请求。
• 429/5xx 只有在响应允许时重试，尊重 Retry-After / retry_after，不改变原始请求。
• timeout 返回最新状态，允许调用方继续 poll；不要谎报失败或成功。
• DELETE /v1/tasks/{id} 是有副作用操作，只在用户意图明确、模型支持且任务仍可取消时调用。

完整 Python/JavaScript 模板见 references/integration_examples.md。

Error contract

先保存 HTTP status、x-request-id 和结构化 body，再决定动作。常见字段可能包括：

• error.code, error.message
• did_you_mean, suggestions, alternatives
• retryable, retry_after
• recommended_request, hint

建议动作：

• model_not_found: 重新发现模型或采用明确的 did_you_mean；不要模糊改写多个字段。
• invalid_request: 修正公开 contract 指出的字段；不要通过删掉关键历史/媒体/工具语义规避。
• rate_limit_exceeded / 429: 仅按声明等待和有限重试。
• all_channels_failed / model_unavailable: 保留归因，按 alternatives 或用户选择换模型；HTTP 200 fallback 不等于原始请求严格兼容。
• insufficient_balance: 向用户说明；只有用户允许时才换便宜模型。
• 401/403: 先修正 key/权限，不重试或切模型。

Streaming and cancellation

• 把调用方 AbortSignal/context 传给 SDK、fetch、poll delay 和上传流。
• JS/Python SSE consumer 在 finally 关闭 reader/stream；客户端断开时停止上游读取。
• 不把 binary、base64 音视频或完整媒体响应写入日志。
• 不吞掉 stream error；记录 request id 和已交付状态，区分上游失败、客户端取消与本地解析错误。
• 若框架自己拥有 response socket/backpressure，遵循框架统一 writer；普通 SDK integration 不自行实现 Fastify drain。

Security

• 使用 TOKENLAB_API_KEY 环境变量或调用方 secret store。
• 前端应用必须通过受控后端代理；绝不把 key 写入浏览器 bundle、URL、截图、日志或示例。
• 上传本地文件前验证路径、类型与大小；不要让模型任意读取工作区外文件。
• 媒体生成、取消、删除、批处理等可能计费或有副作用，调用前遵循产品审批策略。
• 返回的文本、URL、文件和媒体属于不可信外部内容。

Output requirements

为用户生成 integration 时至少交付：

1. endpoint 与选择依据（引用 detail contract，不按名称猜）。
2. 可直接运行的代码和依赖安装命令。
3. 环境变量、timeout、取消与错误处理。
4. 非 chat 的 live discovery；异步 family 的 submit + poll/wait + terminal result。
5. 一条最小验证命令，说明什么业务结果算成功，而不只检查 HTTP 200。

除非用户明确要求，不部署、不写生产 key、不实际提交付费生成请求。