TOKTESK DEVELOPER PLATFORM

一次接入，调用
多种主流 AI
视频模型

用统一的 REST API 生成视频、查询进度和获取限时下载地址。平台统一管理生成服务，客户设备只使用各自的独立 Key。

POST /v1/videos

curl https://toktesk.com/v1/videos \
  -H "Authorization: Bearer sk-tt-..." \
  -H "Idempotency-Key: order-20260914-001" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "产品展示短片",
    "model": "cm-sd25-lw",
    "duration": 20,
    "ratio": "9:16"
  }'

202 ACCEPTED{ "id": "…", "status": "queued" }

Bearer API Key按模型与时长计费幂等安全重试限时签名下载

QUICK START

三步完成接入

创建客户 Key

登录工作台进入“API 接入”，按客户设置每日任务额度和并发。完整 Key 只显示一次。

提交生成任务

携带 Bearer Key 与唯一 Idempotency-Key。参考图先上传到文件接口，再将 image_id 放入任务。

轮询并下载

查询任务直到 succeeded，再获取 10 分钟有效的签名地址。视频仍由 TokTesk 服务器统一保存。

MODEL CATALOG

保留原始模型名称

MODELS

正在读取模型目录…

以 /v1/catalog 实时返回为准

REST ENDPOINTS

面向 AI 软件的完整调用流程

GET/v1/catalog模型与能力

GET/v1/pricing统一计费

GET/v1/balance积分与流水

POST/v1/files上传参考图

POST/v1/videos创建视频任务

GET/v1/videos/{id}查询任务状态

GET/v1/videos/{id}/signed_url获取下载地址

POST/v1/webhooks/test测试回调地址

GET/v1/webhooks/deliveries回调投递记录

PRODUCTION

回调、限流与排查

完成回调

创建任务时传 callback_url（公网 https 地址）。任务成功、失败或取消后，平台主动 POST 通知，无需反复轮询。接收方 10 秒内返回 2xx 即视为送达，否则在 30 秒、2 分钟、10 分钟、1 小时、6 小时后重试。

调用频率

每个 Key 每分钟最多 300 次请求、30 次创建任务。响应头 X-RateLimit-Remaining 显示剩余次数；超限返回 429 和 Retry-After（秒）。轮询建议间隔 5 秒以上。

请求编号

每个响应都带 X-Request-Id，错误内容里也有 request_id。遇到问题时把它发给我们，可以直接定位到这一次调用。

IP 白名单

在控制台“API 接入 → 设置”中填写服务器 IP 或网段。设置后，其他 IP 用这个 Key 调用会返回 403 IP_NOT_ALLOWED。

只在服务器端调用

API Key 等同于账户积分，请只放在你的后端服务里，不要写进网页、小程序或 App 前端，浏览器跨域请求会被拒绝。必须使用 https。

安全重试

网络超时请用同一个 Idempotency-Key 重试，不会重复创建任务或重复扣费；参数不同会返回 409。

创建任务并接收回调

curl https://toktesk.com/v1/videos \
  -H "Authorization: Bearer sk-tt-..." \
  -H "Idempotency-Key: order-20261015-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"产品展示短片","model":"cm-sd25-lw",
       "duration":20,"ratio":"9:16",
       "callback_url":"https://your-server.com/toktesk/callback"}'

# 回调请求体
{"id":"whd_…","event":"video.succeeded",
 "created_at":"…","data":{"id":"…","status":"succeeded",…}}
# event：video.succeeded / video.failed / video.cancelled
# 收到后调用 GET /v1/videos/{id}/signed_url 获取下载地址

校验回调签名（Python）

import hmac, hashlib

API_KEY = "sk-tt-..."
SECRET = hmac.new(API_KEY.encode(), b"toktesk-webhook",
                  hashlib.sha256).hexdigest()

def verify(headers, raw_body: bytes) -> bool:
    # X-TokTesk-Signature: t=1760500000,v1=ab12…
    parts = dict(p.split("=", 1) for p in
                 headers["X-TokTesk-Signature"].split(","))
    msg = parts["t"].encode() + b"." + raw_body
    sig = hmac.new(SECRET.encode(), msg,
                   hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, parts["v1"])

# 测试回调地址：
# POST /v1/webhooks/test  {"callback_url": "https://…"}

常见错误码

HTTP	code	含义与处理
400	`IDEMPOTENCY_KEY_REQUIRED`	缺少 Idempotency-Key（8–128 位）
400	`INVALID_MODEL` / `INVALID_DURATION`	模型或时长不支持，以 `/v1/catalog` 为准
400	`INVALID_CALLBACK_URL`	回调地址必须是公网 https
401	`INVALID_API_KEY`	Key 错误或已停用；同一 IP 10 分钟内错误 20 次会暂时锁定
402	`VIDEO_CREDITS_REQUIRED`	积分不足，请充值后重试
403	`IP_NOT_ALLOWED`	请求 IP 不在该 Key 的白名单内
409	`IDEMPOTENCY_CONFLICT`	同一个 Idempotency-Key 用于了不同参数
429	`RATE_LIMITED`	调用过于频繁，按 Retry-After 秒数后重试
429	`DAILY_LIMIT_REACHED` / `CONCURRENCY_LIMIT_REACHED`	达到该 Key 的每日额度或并发上限
5xx	`INTERNAL_ERROR` 等	平台临时故障，稍后用同一 Idempotency-Key 重试，并提供 request_id