跳到正文
通达云视频

QUICKSTART

快速开始

三步完成第一条视频生成:拿到客户密钥、提交任务、接收结果。

三步接入

  1. 1

    开通账号,创建客户密钥

    完成企业实名(提交后账号自动开通)后,在客户控制台创建客户密钥(每个账号最多 20 把),并放进服务端的环境变量,例如 TDC_CUSTOMER_KEY。 客户密钥只能在服务端使用,不要写进网页或 App。

  2. 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. 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 重新下单。