API Docs | TokenBox

快速开始

首次接入按以下顺序完成。生产调用前，请先确认余额、Key 权限和模型状态。

01
创建密钥
登录 Console 创建 API Key。明文只展示一次，请立即存入服务端密钥管理系统。
02
发现模型
调用 GET /v1/models，以响应中的 id 作为后续请求的 model。
03
发起调用
根据模型能力调用文本或视频端点，并在 Console 日志中核对结果和费用。

鉴权与权限

所有网关请求都通过 Authorization Bearer 头携带 API Key。不同端点要求对应 scope。

models.read

读取当前 Key 可见的模型目录

chat.completions

调用文本对话补全接口

video.generations

创建和查询视频生成任务

不要把 API Key 放入浏览器代码、移动端安装包、URL 或代码仓库。Key 泄露后应立即在 Console 禁用并重新创建。

模型与端点

不要在代码中猜测模型名称。先读取模型列表，只调用返回结果中满足业务能力的模型。

cURL

export TOKENBOX_API_KEY="tfk-your-key"

curl https://tokenbox.me/v1/models \
  -H "Authorization: Bearer $TOKENBOX_API_KEY"

方法	路径	用途
GET	/v1/models	列出当前 Key 可见的模型
GET	/v1/models/{model}	读取单个模型元数据
POST	/v1/chat/completions	创建文本对话补全
POST	/v1/contents/generations/tasks	创建异步视频任务
GET	/v1/contents/generations/tasks/{task_id}	查询视频任务状态

文本对话

文本接口兼容 OpenAI Chat Completions。请将 <TEXT_MODEL_ID> 替换为模型列表中支持文本对话的 id。

cURL

curl https://tokenbox.me/v1/chat/completions \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<TEXT_MODEL_ID>",
    "messages": [
      {"role": "user", "content": "用一句话介绍杭州"}
    ],
    "max_tokens": 256
  }'

Python

pip install openai

main.py

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["TOKENBOX_API_KEY"],
    base_url="https://tokenbox.me/v1",
)

response = client.chat.completions.create(
    model="<TEXT_MODEL_ID>",
    messages=[{"role": "user", "content": "用一句话介绍杭州"}],
)

print(response.choices[0].message.content)

Node.js

npm install openai

index.mjs

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKENBOX_API_KEY,
  baseURL: "https://tokenbox.me/v1",
});

const response = await client.chat.completions.create({
  model: "<TEXT_MODEL_ID>",
  messages: [{ role: "user", content: "用一句话介绍杭州" }],
});

console.log(response.choices[0].message.content);

流式响应

设置 stream=true 后返回 SSE。客户端应持续读取 data 行，直到收到 data: [DONE]。

cURL · SSE

curl -N https://tokenbox.me/v1/chat/completions \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<TEXT_MODEL_ID>",
    "messages": [
      {"role": "user", "content": "用一句话介绍杭州"}
    ],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

视频生成

视频生成是异步接口。创建任务后保存响应中的 id，并轮询查询端点直到任务完成。

创建视频任务

export IDEMPOTENCY_KEY="$(uuidgen)"

curl https://tokenbox.me/v1/contents/generations/tasks \
  -H "Authorization: Bearer $TOKENBOX_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ctyun/cdance2.0-0611",
    "content": [
      {"type": "text", "text": "雨后的杭州西湖，电影感航拍镜头"}
    ],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5
  }'

查询任务状态

curl https://tokenbox.me/v1/contents/generations/tasks/<TASK_ID> \
  -H "Authorization: Bearer $TOKENBOX_API_KEY"

创建视频任务会产生费用。每次创建必须传入唯一 Idempotency-Key；网络超时重试同一业务请求时必须复用原值，避免重复任务。

错误处理

错误响应采用统一 JSON 结构。程序应优先判断 HTTP 状态码和 error.code，不要依赖可变的 message 文案。

HTTP	错误码	处理建议
400	invalid_request	检查请求 JSON、必填字段和参数范围
401	invalid_api_key	检查 Key 是否完整、有效且未被禁用
402	insufficient_balance	充值后再重试
403	insufficient_scope	使用包含对应 scope 的新 Key
404	model_not_found	重新读取模型列表并替换 model
429	rate_limit_exceeded	指数退避，并遵守 Retry-After
5xx	internal_error	保留请求 ID，稍后重试或联系支持

请记录响应头 x-request-id。排查失败、延迟或账单问题时，可用该 ID 在 Console 调用日志中定位请求。