智谱视频生成 API 怎么用？提交异步任务并轮询结果

智谱视频生成 API 是异步任务：先向 /paas/v4/videos/generations 提交提示词，保存返回的任务 ID，再请求 /paas/v4/async-result/{id} 轮询。收到 HTTP 200 只表示提交成功，只有状态为 SUCCESS 且结果里有可访问的视频 URL，才能进入内容验收。

提交一个最小文生视频任务

把 API Key 放入环境变量。以下示例使用官方页面当前列出的 cogvideox-3，生成参数和可用模型以后可能调整：

import os, time, requests

base = "https://open.bigmodel.cn/api/paas/v4"
headers = {
    "Authorization": f"Bearer {os.environ['ZAI_API_KEY']}",
    "Content-Type": "application/json",
}
payload = {
    "model": "cogvideox-3",
    "prompt": "固定镜头，一只橙色纸鹤放在木桌上，窗外柔和晨光，无文字",
    "quality": "quality",
    "with_audio": False,
    "size": "1280x720",
    "fps": 30,
    "duration": 5,
}
created = requests.post(
    f"{base}/videos/generations",
    headers=headers, json=payload, timeout=60
)
created.raise_for_status()
task_id = created.json()["id"]
print("task_id:", task_id)

请求路径、文本转视频与图像转视频方式可在智谱视频生成（异步）官方接口核对。提示词或图片至少要提供一种；分辨率、帧率、时长和图片格式必须符合所选模型约束。

有限轮询，不要重复创建

result = None
for attempt in range(30):
    r = requests.get(
        f"{base}/async-result/{task_id}",
        headers=headers, timeout=30
    )
    r.raise_for_status()
    data = r.json()
    status = data.get("task_status")
    if status == "SUCCESS":
        result = data
        break
    if status == "FAIL":
        raise RuntimeError(data)
    if status != "PROCESSING":
        raise RuntimeError(f"未知状态: {status}")
    time.sleep(5)

if result is None:
    raise TimeoutError("轮询达到上限；保留 task_id，稍后继续查询")
print(result["video_result"][0]["url"])

查询接口及 PROCESSING、SUCCESS、FAIL 状态见官方异步结果文档。轮询超时后应保存任务 ID，稍后继续查同一任务；重新 POST 会新建任务，可能重复计费。

怎样验收生成结果

1. 检查状态为 SUCCESS，video_result 非空，URL 能返回视频内容而不是错误页。
2. 下载到受控目录，记录任务 ID、请求参数、文件哈希和下载时间。
3. 播放完整视频，确认时长、分辨率、方向和帧率符合请求。
4. 逐项检查纸鹤颜色、木桌、晨光、固定镜头和“无文字”；不要只看封面图。
5. 检查黑帧、抖动、主体变形、意外文字、音频和版权或肖像风险。

常见失败处理

费用、安全与未实测边界

提交异步任务可能产生费用，失败、重试和不同质量参数的计费以当前官方价格和账单为准。上传人物或版权素材前应取得授权，不生成冒充真人或误导性内容。本文没有使用你的 Key 提交任务，示例视频也未实际生成；参数依据 2026-10-01 官方接口整理，模型、额度、价格和结果 URL 规则以后可能变化。