QUICKSTART
快速开始
三步完成第一条视频生成:拿到客户密钥、提交任务、接收结果。
三步接入
- 1
开通账号,创建客户密钥
完成企业实名(提交后账号自动开通)后,在客户控制台创建客户密钥(每个账号最多 20 把),并放进服务端的环境变量,例如
TDC_CUSTOMER_KEY。 客户密钥只能在服务端使用,不要写进网页或 App。 - 2
提交一条生成任务
向
POST /v1/videos/generations提交任务。下面的例子请求 362 帧(目标时长 15 秒)的有声视频,接口立即返回任务编号,并冻结 ¥4.48。# 创建一条生成任务(异步),结果通过 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" }' - 3
接收结果
任务结束(成功、失败或已取消)时,平台向
webhook_url发送签名通知,见Webhook。也可以用GET /v1/videos/generations/{task_id}轮询。成功后,
output.video_url是成片下载链接,24 小时有效;过期后在 30 天内再次查询任务,会拿到新的链接,不额外收费。
幂等重试:网络超时也不会重复下单
external_id 是你自己系统里的单号,在你的账号下永久唯一:用过的单号不会再给别的请求用。用同一个 external_id 重复提交同样的请求,接口不会新建任务、也不会再次冻结金额,而是返回第一次创建的那个任务:
- 第一次提交:
201 Created,返回新任务。 - 重复提交:
200 OK,返回同一个task_id,并带"idempotent_reused": true。
以第一次提交为准
命中幂等时直接返回已有任务,不会用新请求里的参数覆盖;同一个 external_id 带着不同的参数提交,会返回409 EXTERNAL_ID_CONFLICT。要换参数重新生成,请换一个新的 external_id。因此,遇到网络超时、连接中断、429,或 503 SERVICE_UNAVAILABLE、500 OUTCOME_UNKNOWN 时,只要用同一个 external_id 原样重发即可:
import os
import time
import requests
URL = "https://video-api.td-ai.cn/v1/videos/generations"
HEADERS = {"X-Customer-Key": os.environ["TDC_CUSTOMER_KEY"]}
payload = {
"external_id": "ord-20261103-0042", # 你自己的单号,在你的账号下永久唯一
"model_pkg_code": "minimax-h3",
"prompt": "金色沙丘绵延到天边,一个旅人在风中缓慢前行,镜头自高空缓缓下降,风声由远及近。",
"resolution": "1376x768",
"frames": 362,
"has_audio": True,
}
for attempt in range(4):
resp = None # 每次尝试前清空,避免上一次的 429 掩盖这一次的网络错误
try:
resp = requests.post(URL, headers=HEADERS, json=payload, timeout=30)
except requests.RequestException:
time.sleep(2**attempt) # 超时或断网:原样重发,external_id 不变
continue
if resp.status_code == 429:
# 创建频率按 60 秒滑动窗口计算,且不返回 Retry-After:等满窗口再重发
time.sleep(61)
continue
if resp.status_code in (500, 503):
# 503 服务暂时不可用;500 OUTCOME_UNKNOWN 是结果不确定(可能已创建)。
# 两种都用同一个 external_id 原样重发:已创建就返回那个任务,没创建才新建,不会重复冻结
time.sleep(2**attempt)
continue
break
else:
raise RuntimeError("重试 4 次仍未成功(网络错误、429 或 5xx),请稍后用同一个 external_id 再提交")
task = resp.json()
if resp.status_code == 201:
print("新建任务", task["task_id"])
elif resp.status_code == 200 and task.get("idempotent_reused"):
print("命中已有任务,没有重复冻结", task["task_id"])
else:
raise RuntimeError(task["error"])结果不确定时不要换单号
500 OUTCOME_UNKNOWN 表示请求可能已经生效、只是没收到确认。这时请用同一个 external_id 重发(也可以先查询任务): 已经创建的话返回那个任务,没有创建才会新建,不会重复冻结。换新的 external_id 反而可能创建出第二个任务。只有结果确定的失败(例如任务生成失败、预审不通过) 才需要换新的 external_id 重新下单。