跳到正文
通达云视频

DOCS

开发者文档

视频生成接口是标准的 REST 接口:提交一条生成任务,异步拿到有声成片。这里汇总接入前需要知道的约定。

接口约定

接口地址
https://video-api.td-ai.cn/v1
鉴权
请求头 X-Customer-Key: 你的客户密钥,客户密钥在客户控制台创建,每个账号最多 20 把
数据格式
请求与响应均为 JSON(UTF-8),金额单位为分(整数)
幂等
创建任务必须带你自己的单号 external_id,它在你的账号下永久唯一:用同样的内容重复提交返回同一个任务,不会重复下单; 内容不同则返回 409 EXTERNAL_ID_CONFLICT
异步
创建后立即返回任务编号;结果通过 Webhook 回调,或查询任务获取
请求编号
每个响应都带 X-Request-Id 响应头;出错时响应体里也有 request_id,联系支持时请提供

默认限额

每个企业账号默认每分钟最多 60 次创建任务请求(60 秒滑动窗口,只有创建任务计入),同时最多 100 个排队中的任务。超出时分别返回 429 RATE_LIMIT_EXCEEDED 与 429 QUEUE_LIMIT_EXCEEDED,被拦下的请求不收费、不会创建任务。

响应里没有 Retry-After 头:遇到 429 RATE_LIMIT_EXCEEDED 请等满 60 秒窗口,遇到 429 QUEUE_LIMIT_EXCEEDED 请等已有任务开始生成,再用同一个 external_id 重试。需要更高限额请联系我们。

错误响应

所有错误都返回统一的结构:code 用于程序判断,message_zh 可以直接展示给你的用户,doc_url 指向该错误码的说明。完整列表见错误码。

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message_zh": "账户可用余额不足以预冻结当前任务最高规格上限",
    "request_id": "req_01JC4QH7Z8M2KX9F3T5V7W2YBE",
    "doc_url": "https://video.td-ai.cn/docs/error-codes#INSUFFICIENT_BALANCE"
  }
}

从哪里开始