跳到正文
通达云视频

API REFERENCE

API 参考

接口地址 https://video-api.td-ai.cn/v1,所有请求都在请求头里带客户密钥 X-Customer-Key。

接口一览

方法路径用途
POST/v1/videos/generations创建生成任务
GET/v1/videos/generations列出最近 30 天的任务,支持按状态筛选、分页
GET/v1/videos/generations/{task_id}查询单个任务;路径里也可以填 order_id 或你的 external_id。成片链接过期时会自动换新
POST/v1/videos/generations/{task_id}/cancel取消任务(仅排队中)
POST/v1/videos/generations/batch-query批量查询,task_ids 与 external_ids 合计最多 50 个
POST/v1/videos/generations/{task_id}/appeals对成片审核不通过的任务提出申诉(7 天内)

鉴权

请求头 X-Customer-Key 填写客户密钥。客户密钥无效、已停用或已删除返回 401 UNAUTHORIZED_CUSTOMER_KEY; 账号被停用返回 403 CUSTOMER_ACCOUNT_DISABLED;账号还没有完成企业实名、没有开通返回 403 CUSTOMER_NOT_ACTIVE; 客户密钥没有该模型的调用权限返回 403 MODEL_PERMISSION_DENIED。

创建任务

POST /v1/videos/generations,请求体为 JSON;请求体不是合法 JSON、字段类型不对(例如 frames 传了字符串),或超过 1 MiB 时,返回 400 INVALID_PARAMETER。 新建任务返回 201;命中幂等返回 200 与已有任务。

字段类型必填说明
external_idstring是你自己的单号,在你的账号下永久唯一,缺失或空白返回 400 INVALID_PARAMETER。用同一个值、同样的内容重复提交,返回同一个任务(幂等);内容不同返回 409 EXTERNAL_ID_CONFLICT。失败的任务同样永久占用该单号,修改后重新下单请换新单号;遇到 500 OUTCOME_UNKNOWN(结果不确定)不要换单号,用同一个值重发。
promptstring是提示词:描述画面内容与运镜,最长 2000 个字符(超出返回 400 INVALID_PARAMETER)。
resolutionstring是1376x768 或 864x480;其他值返回 400 INVALID_RESOLUTION。
framesinteger否帧数,需满足 frames % 17 == 5 且在 [22, 362] 内,否则返回 400 INVALID_FRAME_LENGTH。见下方「帧数与时长」。
duration_secinteger否整数秒。只在不传 frames 时生效,按 fps 换算后向下对齐到最近的合法帧数。
fpsinteger否只参与帧数到时长的换算(target_duration_sec = round(frames ÷ fps))与预冻结计算,默认 24。成片帧率由模型决定(24fps),建议不传。
has_audioboolean否是否同时生成声音,默认 true。有声与静音单价不同。
model_pkg_codestring否模型编号,例如 minimax-h3;不填使用平台默认模型。
input_assetsarray否输入素材(首尾帧、参考图、参考音频等)。每项包含 asset_type(IMAGE / VIDEO / AUDIO)与 uri, 可选 asset_id、sha256、size_bytes。
authorization_idstring条件真人肖像 / 声音授权编号:在客户控制台上传被授权人本人签署的授权书、完成备案后获得。平台在预审阶段检测输入素材里的人脸肖像与真人声音: 输入素材涉及真人时,必须带上覆盖相应范围的有效授权(只涉及肖像需「肖像」或「肖像和声音」范围,只涉及声音需「声音」或「肖像和声音」范围,两者都涉及只能用「肖像和声音」范围)。 传入的授权编号不存在、不属于当前企业、已过期或已撤销时,创建接口当场返回 422 REAL_PERSON_AUTH_INVALID,不冻结余额、不占用 external_id;未带授权或授权范围未覆盖检出内容时,任务在预审阶段被拦截,状态变为失败、错误码为 PRE_AUDIT_FACE_AUTH_MISSING,不收费,冻结金额全额退回。
watermark_positionstring否显式标识「人工智能生成」所在的角:TOP_LEFT / TOP_RIGHT / BOTTOM_LEFT / BOTTOM_RIGHT,不区分大小写,首尾空格忽略; 不传或传空字符串按默认右下角(BOTTOM_RIGHT);其他值返回 400 INVALID_PARAMETER。
webhook_urlstring否任务结束时接收签名通知的地址,见 Webhook。
# 创建一条生成任务(异步),结果通过 Webhook 回调或轮询查询
curl -X POST "https://video-api.td-ai.cn/v1/videos/generations" \
  -H "X-Customer-Key: $TDC_CUSTOMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "ord-20261103-0042",
    "model_pkg_code": "minimax-h3",
    "prompt": "金色沙丘绵延到天边,一个旅人在风中缓慢前行,镜头自高空缓缓下降,风声由远及近。",
    "resolution": "1376x768",
    "frames": 362,
    "has_audio": true,
    "webhook_url": "https://example.com/hooks/tdc"
  }'

帧数与时长

帧数必须满足 length % 17 == 5,区间 [22, 362]。帧数只用来换算目标时长:target_duration_sec = round(frames ÷ fps),生成按这个整数秒进行(1 到 15 秒),成片帧率由模型决定。

  • 传 frames:不合法直接返回 400 INVALID_FRAME_LENGTH,不会帮你改。
  • 只传 duration_sec(整数秒):换算成帧数后向下对齐到最近的合法帧数,例如 15 秒对齐为 345 帧。
  • 两者都不传:默认 124 帧,目标时长 5 秒。

帧数换算

合法帧数满足 length % 17 == 5,区间 [22, 362],24fps

合法15.08s ≈ 15.1s (24fps)

帧数符合 length % 17 == 5 步进规范

全部合法帧数(点选填入)

任务对象

创建、查询、取消、列表与批量查询返回的都是同一种任务对象(列表与批量查询放在 tasks 数组里)。

字段类型说明
task_idstring任务编号,tsk_ 开头。
order_idstring订单编号,ord_ 开头。
external_idstring你提交的单号。
model_pkg_codestring模型编号(没传时为平台默认模型)。
promptstring提交的提示词(为空时不返回)。
requested_resolutionstring请求的分辨率。
requested_has_audioboolean请求是否有声。
watermark_positionstring显式标识所在的角(传了才返回)。
webhook_urlstring通知地址(传了才返回)。
authorization_idstring提交的真人授权编号(传了才返回)。
has_real_person_authboolean下单时带了有效的授权编号时为 true。平台在预审阶段再检测输入素材里的人脸和声音,授权范围没覆盖时任务在预审失败。
statusstringQUEUED / RUNNING / SUCCEEDED / FAILED / CANCELED,即排队中 / 跑任务中 / 成功 / 失败 / 已取消。
status_zhstring状态中文,接口原文为:排队中 / 跑任务中 / 生成成功 / 生成失败 / 已取消。
generation_statusstring生成情况:PENDING / RUNNING / COMPLETED / FAILED / CANCELED。
audit_statusstring审核结论:PENDING / PRE_AUDIT_REJECTED / POST_AUDIT_PASSED / POST_AUDIT_REJECTED;申诉裁决后为 APPEAL_APPROVED / APPEAL_REFUNDED / APPEAL_UPHELD。
billing_statusstring费用状态:FROZEN(已冻结)/ CHARGED(已扣费)/ UNFROZEN(全额退回)/ REFUNDED_BY_APPEAL(申诉退款)。
queue_positioninteger排队位置(排队中时有意义)。
estimated_wait_secinteger预计还需等待的秒数(排队中时有意义)。
requested_framesinteger实际采用的帧数(按秒数下单时为对齐后的帧数)。
target_duration_secinteger目标时长(整数秒)。
frozen_amount_feninteger下单时冻结的金额(分)。
charged_amount_feninteger实扣金额(分)。
refunded_diff_feninteger退回可用余额的金额(分)。
outputobject成功时返回:video_url(24 小时有效)、video_url_expires_at、duration_sec、resolution、has_audio。
errorobject失败时返回:code、message_zh。
rejected_atstring成片审核不通过的时间(申诉期限从这里起算)。
can_appealboolean当前能否提出申诉:只在成片审核不通过、7 天内且尚未申诉时为 true。
appeal_deadline_atstring申诉截止时间(成片审核不通过后 7 天)。
appeal_id / appeal_status / appeal_ruling_verdictstring申诉编号、进度与裁决结果。
appeal_reason / appeal_contactstring提交申诉时填写的理由与联系方式。
appeal_submitted_at / appeal_ruled_atstring申诉提交与裁决的时间。
appeal_refunded_feninteger申诉改判退款的金额(分)。
idempotent_reusedboolean命中幂等、返回已有任务时为 true。
created_at / updated_atstringRFC 3339 时间(UTC)。
{
  "task_id": "tsk_01JC4QH7Z8M2KX9F3T5V7W2YBD",
  "order_id": "ord_01JC4QH7ZA6N8P0R2S4T6V8X0Y",
  "external_id": "ord-20261103-0042",
  "model_pkg_code": "minimax-h3",
  "requested_resolution": "1376x768",
  "requested_has_audio": true,
  "requested_frames": 362,
  "target_duration_sec": 15,
  "status": "QUEUED",
  "status_zh": "排队中",
  "generation_status": "PENDING",
  "audit_status": "PENDING",
  "billing_status": "FROZEN",
  "frozen_amount_fen": 448,
  "charged_amount_fen": 0,
  "refunded_diff_fen": 0,
  "can_appeal": false,
  "created_at": "2026-11-03T09:20:00Z"
}

查询、取消、批量查询与列表

  • 查询单个任务:链接过期后再次查询会拿到新的 video_url(30 天内);超过 30 天返回 404 TASK_RETENTION_EXPIRED。
  • 取消:只有排队中的任务可以取消,冻结金额全额退回。已在跑任务中返回 409 TASK_ALREADY_RUNNING,已结束返回 409 TASK_NOT_CANCELLABLE。请求体可选 {"reason": "..."}(空请求体可以);请求体不是合法 JSON、字段类型不对或超过 64 KiB 时,返回 400 INVALID_PARAMETER。
  • 批量查询:请求体 {"task_ids": [...], "external_ids": [...]},合计最多 50 个,超过 50 个返回 400 INVALID_PARAMETER;查不到的编号直接略过。返回 {"tasks", "total", "request_id"}。请求体不是合法 JSON 或超过 128 KiB 时,返回 400 INVALID_PARAMETER。
  • 列表:参数 page(默认 1)、page_size(默认 20,最大 100)、status;只含最近 30 天的任务。 返回 {"tasks", "total", "page", "page_size", "request_id"}。
# 查询单个任务:路径里可以填 task_id,也可以填你的 external_id
curl -s "https://video-api.td-ai.cn/v1/videos/generations/tsk_01JC4QH7Z8M2KX9F3T5V7W2YBD" \
  -H "X-Customer-Key: $TDC_CUSTOMER_KEY"

# 取消(只有「排队中」可以取消)
curl -s -X POST "https://video-api.td-ai.cn/v1/videos/generations/tsk_01JC4QH7Z8M2KX9F3T5V7W2YBD/cancel" \
  -H "X-Customer-Key: $TDC_CUSTOMER_KEY"

# 批量查询:task_ids 与 external_ids 合计最多 50 个
curl -s -X POST "https://video-api.td-ai.cn/v1/videos/generations/batch-query" \
  -H "X-Customer-Key: $TDC_CUSTOMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ids": ["ord-20261103-0042"]}'

# 列表:最近 30 天,按状态筛选、分页(page_size 最大 100)
curl -s "https://video-api.td-ai.cn/v1/videos/generations?status=SUCCEEDED&page=1&page_size=20" \
  -H "X-Customer-Key: $TDC_CUSTOMER_KEY"

申诉

只有「成片审核不通过」的任务可以申诉,期限为审核结束后 7 天(以任务里的 appeal_deadline_at 为准)。POST /v1/videos/generations/{task_id}/appeals,请求体可选 {"reason": "申诉理由", "contact": "联系方式"}(空请求体可以,contact 必须是字符串;请求体不是合法 JSON、字段类型不对或超过 64 KiB 返回 400 INVALID_PARAMETER), 成功返回 201 与 appeal_id。

申诉相关的错误

不符合申诉条件返回 422 APPEAL_NOT_ELIGIBLE;超过 7 天返回 422 APPEAL_WINDOW_EXPIRED; 已经申诉过返回 409 APPEAL_ALREADY_SUBMITTED。裁决结果见状态与计费。其他没预料的内部错误返回 500 INTERNAL_ERROR(不收钱,也不代表对已提交任务退款)。