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_id | string | 是 | 你自己的单号,在你的账号下永久唯一,缺失或空白返回 400 INVALID_PARAMETER。用同一个值、同样的内容重复提交,返回同一个任务(幂等);内容不同返回 409 EXTERNAL_ID_CONFLICT。失败的任务同样永久占用该单号,修改后重新下单请换新单号;遇到 500 OUTCOME_UNKNOWN(结果不确定)不要换单号,用同一个值重发。 |
| prompt | string | 是 | 提示词:描述画面内容与运镜,最长 2000 个字符(超出返回 400 INVALID_PARAMETER)。 |
| resolution | string | 是 | 1376x768 或 864x480;其他值返回 400 INVALID_RESOLUTION。 |
| frames | integer | 否 | 帧数,需满足 frames % 17 == 5 且在 [22, 362] 内,否则返回 400 INVALID_FRAME_LENGTH。见下方「帧数与时长」。 |
| duration_sec | integer | 否 | 整数秒。只在不传 frames 时生效,按 fps 换算后向下对齐到最近的合法帧数。 |
| fps | integer | 否 | 只参与帧数到时长的换算(target_duration_sec = round(frames ÷ fps))与预冻结计算,默认 24。成片帧率由模型决定(24fps),建议不传。 |
| has_audio | boolean | 否 | 是否同时生成声音,默认 true。有声与静音单价不同。 |
| model_pkg_code | string | 否 | 模型编号,例如 minimax-h3;不填使用平台默认模型。 |
| input_assets | array | 否 | 输入素材(首尾帧、参考图、参考音频等)。每项包含 asset_type(IMAGE / VIDEO / AUDIO)与 uri, 可选 asset_id、sha256、size_bytes。 |
| authorization_id | string | 条件 | 真人肖像 / 声音授权编号:在客户控制台上传被授权人本人签署的授权书、完成备案后获得。平台在预审阶段检测输入素材里的人脸肖像与真人声音: 输入素材涉及真人时,必须带上覆盖相应范围的有效授权(只涉及肖像需「肖像」或「肖像和声音」范围,只涉及声音需「声音」或「肖像和声音」范围,两者都涉及只能用「肖像和声音」范围)。 传入的授权编号不存在、不属于当前企业、已过期或已撤销时,创建接口当场返回 422 REAL_PERSON_AUTH_INVALID,不冻结余额、不占用 external_id;未带授权或授权范围未覆盖检出内容时,任务在预审阶段被拦截,状态变为失败、错误码为 PRE_AUDIT_FACE_AUTH_MISSING,不收费,冻结金额全额退回。 |
| watermark_position | string | 否 | 显式标识「人工智能生成」所在的角:TOP_LEFT / TOP_RIGHT / BOTTOM_LEFT / BOTTOM_RIGHT,不区分大小写,首尾空格忽略; 不传或传空字符串按默认右下角(BOTTOM_RIGHT);其他值返回 400 INVALID_PARAMETER。 |
| webhook_url | string | 否 | 任务结束时接收签名通知的地址,见 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
帧数符合 length % 17 == 5 步进规范
全部合法帧数(点选填入)
任务对象
创建、查询、取消、列表与批量查询返回的都是同一种任务对象(列表与批量查询放在 tasks 数组里)。
| 字段 | 类型 | 说明 |
|---|---|---|
| task_id | string | 任务编号,tsk_ 开头。 |
| order_id | string | 订单编号,ord_ 开头。 |
| external_id | string | 你提交的单号。 |
| model_pkg_code | string | 模型编号(没传时为平台默认模型)。 |
| prompt | string | 提交的提示词(为空时不返回)。 |
| requested_resolution | string | 请求的分辨率。 |
| requested_has_audio | boolean | 请求是否有声。 |
| watermark_position | string | 显式标识所在的角(传了才返回)。 |
| webhook_url | string | 通知地址(传了才返回)。 |
| authorization_id | string | 提交的真人授权编号(传了才返回)。 |
| has_real_person_auth | boolean | 下单时带了有效的授权编号时为 true。平台在预审阶段再检测输入素材里的人脸和声音,授权范围没覆盖时任务在预审失败。 |
| status | string | QUEUED / RUNNING / SUCCEEDED / FAILED / CANCELED,即排队中 / 跑任务中 / 成功 / 失败 / 已取消。 |
| status_zh | string | 状态中文,接口原文为:排队中 / 跑任务中 / 生成成功 / 生成失败 / 已取消。 |
| generation_status | string | 生成情况:PENDING / RUNNING / COMPLETED / FAILED / CANCELED。 |
| audit_status | string | 审核结论:PENDING / PRE_AUDIT_REJECTED / POST_AUDIT_PASSED / POST_AUDIT_REJECTED;申诉裁决后为 APPEAL_APPROVED / APPEAL_REFUNDED / APPEAL_UPHELD。 |
| billing_status | string | 费用状态:FROZEN(已冻结)/ CHARGED(已扣费)/ UNFROZEN(全额退回)/ REFUNDED_BY_APPEAL(申诉退款)。 |
| queue_position | integer | 排队位置(排队中时有意义)。 |
| estimated_wait_sec | integer | 预计还需等待的秒数(排队中时有意义)。 |
| requested_frames | integer | 实际采用的帧数(按秒数下单时为对齐后的帧数)。 |
| target_duration_sec | integer | 目标时长(整数秒)。 |
| frozen_amount_fen | integer | 下单时冻结的金额(分)。 |
| charged_amount_fen | integer | 实扣金额(分)。 |
| refunded_diff_fen | integer | 退回可用余额的金额(分)。 |
| output | object | 成功时返回:video_url(24 小时有效)、video_url_expires_at、duration_sec、resolution、has_audio。 |
| error | object | 失败时返回:code、message_zh。 |
| rejected_at | string | 成片审核不通过的时间(申诉期限从这里起算)。 |
| can_appeal | boolean | 当前能否提出申诉:只在成片审核不通过、7 天内且尚未申诉时为 true。 |
| appeal_deadline_at | string | 申诉截止时间(成片审核不通过后 7 天)。 |
| appeal_id / appeal_status / appeal_ruling_verdict | string | 申诉编号、进度与裁决结果。 |
| appeal_reason / appeal_contact | string | 提交申诉时填写的理由与联系方式。 |
| appeal_submitted_at / appeal_ruled_at | string | 申诉提交与裁决的时间。 |
| appeal_refunded_fen | integer | 申诉改判退款的金额(分)。 |
| idempotent_reused | boolean | 命中幂等、返回已有任务时为 true。 |
| created_at / updated_at | string | RFC 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(不收钱,也不代表对已提交任务退款)。