视频生成 — ZCloudAPI

视频生成使用同一套异步接口：提交任务 -> 查询进度 -> 等待转存 -> 下载 MP4。 更换模型只需调整 model 和该模型支持的规格，不需要接入不同厂商的网址。

视频不是文本流式输出，也不会在提交请求中直接返回完整视频。生成通常需要几分钟；拿到任务 ID 后保存下来，不要因为暂时没看到结果就重复提交。

第一步：准备 Key 和模型

在控制台创建「视频模型」分组的 Key，或使用能够访问视频分组的 AUTO Key。模型白名单和自定义 AUTO 顺序仍然有效；用了 AUTO 不代表会绕过你设置的限制。创建方法见「获取 API Key」。

macOS / Linux：

export ZCLOUD_API_KEY="sk-你的-ZCloudAPI-Key"
export ZCLOUD_BASE_URL="https://api.zcloudapi.com/v1"

curl --fail-with-body "$ZCLOUD_BASE_URL/models" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY"

Windows PowerShell 设置环境变量：

$env:ZCLOUD_API_KEY="sk-你的-ZCloudAPI-Key"
$env:ZCLOUD_BASE_URL="https://api.zcloudapi.com/v1"

下面的 shell 示例适用于 macOS / Linux；Windows 可以使用后文的 Python 示例。Key 只放在环境变量或服务端 Secret 中，不要写进网页前端、源码或公开日志。

截至 2026-10-17，公开视频模型包括以下四款。最终可用性以当前 Key 的 /v1/models 和模型广场为准。

模型名	当前开放分辨率	时长规则	音频规则
`veo-3.1-lite`	720p、1080p	4 / 6 / 8 秒；1080p 必须 8 秒	有声，不支持关闭
`veo-3.1`	720p	4 / 6 / 8 秒	有声，不支持关闭
`kling-3.0`	720p、1080p、4k	配置允许 3–15 整秒，首次建议 5 秒	可选，默认无声
`minimax-h3`	768p	4–15 整秒	当前接入只开放有声

开放配置不等于所有组合都逐项实测。 首次建议用 Veo Lite 的 720p / 4 秒横版、Kling 的 720p / 5 秒无声横版，或 Veo 3.1 的 720p / 4 秒有声竖版、MiniMax H3 的 768p / 4 秒有声竖版。其他组合需先做小规模验证；供应商可能调整或归一化部分参数，以实际文件为准。当前不开放 MiniMax H3 2K 和 Veo 3.1 标准版的高清档。

第二步：提交生成任务

下面的请求会真实生成并扣费。首次测试只提交一次：

curl --fail-with-body "$ZCLOUD_BASE_URL/videos" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "veo-3.1-lite",
    "prompt": "蓝色陶瓷杯放在木桌上，镜头缓慢横移，自然光，无文字",
    "seconds": 4,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

成功响应的关键字段如下。task_example 只是示意，请保存你实际收到的 id：

{
  "id": "task_example",
  "object": "video",
  "model": "veo-3.1-lite",
  "status": "queued"
}

MiniMax H3 使用同一入口，请求体可以改成：

{
  "model": "minimax-h3",
  "prompt": "蓝色陶瓷杯放在木桌上，竖版镜头缓慢横移，无文字",
  "seconds": 4,
  "resolution": "768p",
  "aspect_ratio": "9:16",
  "generate_audio": true
}

参数	用途与注意事项
`model`	必填，使用当前 Key 可见的完整模型名
`prompt`	必填，描述画面、动作和镜头
`seconds`	正整秒，支持数字或整数字符串；不是生成等待时间
`resolution`	分辨率档位，按上方模型表选择
`aspect_ratio`	Veo 支持 `16:9`、`9:16`；Kling / H3 还支持 `1:1`
`generate_audio`	布尔值；Kling 可传 `false`，其他三款用 `true`
`size`	可选像素尺寸别名，如 `1280x720`；不要与分辨率、比例冲突；H3 推荐省略
`duration`	`seconds` 的兼容别名，同时传入时必须一致
`audio` / `sound`	`generate_audio` 的兼容别名，同时传入时必须一致

建议明确传时长。不传时 Veo 默认 8 秒，Kling 和 H3 默认 5 秒。H3 使用原生尺寸网格，例如 768p 竖版实测为 768×1344，不是精确 9:16 的像素比。视频容器可能有少量尾帧时长，不要据此自行计算额外账单。

不要传 stream、response_format，也不要把图片编辑参数直接搬过来。 本教程只覆盖文生视频，每次一个视频。两款新模型 veo-3.1 和 minimax-h3 的参考图片、输入视频及文件上传尚未开放；不能仅凭接口名称相似就认为支持图生视频、视频编辑、remix 或指定音色。

第三步：查询进度

export TASK_ID="替换为刚才返回的实际任务ID"

curl --fail-with-body "$ZCLOUD_BASE_URL/videos/$TASK_ID" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY"

建议每 10–15 秒查询一次。客户端可以设置总等待预算；超出预算后保留任务 ID，稍后继续查询，而不是重新生成。

字段	值	含义
`status`	`queued` / `in_progress`	正在排队或生成
`status`	`completed`	生成完成，还需要看转存状态
`status`	`failed`	生成失败，保留任务 ID 和错误信息
`metadata.storage.status`	`waiting_generation`	等待生成完成
`metadata.storage.status`	`pending` / `uploading`	正在准备或上传 OSS
`metadata.storage.status`	`ready`	已转存，可以下载
`metadata.storage.status`	`failed`	转存失败，不等同于生成失败，不要重新生成

可下载时的关键字段示意：

{
  "id": "task_example",
  "status": "completed",
  "metadata": {
    "storage": {
      "status": "ready",
      "retention": "permanent",
      "url": "https://oss-host.example/video.mp4?signature=example",
      "url_expires_at": 1792219600
    }
  }
}

第四步：下载视频

确认 status=completed 且 metadata.storage.status=ready 后，可以调用本站下载入口：

curl --fail --location "$ZCLOUD_BASE_URL/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY" \
  -o video.mp4

接口鉴权后返回 302，视频文件由 OSS 发送。普通 curl --location 不向不同主机转发 Authorization；不要加 --location-trusted。

也可以使用查询结果里的 metadata.storage.url 直接下载，保留全部签名参数，且不发送 API Key。签名 URL 是临时访问凭证，不要公开传播。

视频长期保存；下载链接临时有效。 当前签名链接默认约 1 小时有效，url_expires_at 是链接截止时间，不是视频删除时间。过期后重新查询任务获取新链接即可，不需要重新生成，也不会再次收取生成费用。

Python：提交、轮询和保存

先在你的项目环境安装 requests：python -m pip install requests，并设置前面的环境变量。以下示例只自动提交一次；轮询超时会保留任务 ID，禁止盲目重跑整个脚本。

import os
import time
import requests

base = os.getenv("ZCLOUD_BASE_URL", "https://api.zcloudapi.com/v1").rstrip("/")
headers = {"Authorization": "Bearer " + os.environ["ZCLOUD_API_KEY"]}

# 已有任务时设置 ZCLOUD_VIDEO_TASK_ID，只查询下载，不再创建。
task_id = os.getenv("ZCLOUD_VIDEO_TASK_ID")
if not task_id:
    response = requests.post(base + "/videos", headers=headers, json={
        "model": "veo-3.1-lite",
        "prompt": "蓝色陶瓷杯，镜头缓慢横移，自然光，无文字",
        "seconds": 4,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "generate_audio": True,
    }, timeout=120)
    response.raise_for_status()
    task_id = response.json()["id"]
print("请保存任务 ID：", task_id, flush=True)

deadline = time.monotonic() + 20 * 60
while time.monotonic() < deadline:
    response = requests.get(base + "/videos/" + task_id, headers=headers, timeout=60)
    response.raise_for_status()
    task = response.json()
    storage = task.get("metadata", {}).get("storage", {})
    print(task.get("status"), storage.get("status"), flush=True)
    if task.get("status") == "failed":
        raise RuntimeError(f"任务失败：{task_id}，{task.get('error')}")
    if storage.get("status") == "failed":
        raise RuntimeError(f"转存异常，请保留任务 ID 联系支持：{task_id}")
    if task.get("status") == "completed" and storage.get("status") == "ready":
        # OSS 使用签名 URL，不携带本站 Authorization。
        with requests.get(storage["url"], stream=True, timeout=120) as video:
            video.raise_for_status()
            with open("video.mp4", "wb") as target:
                for chunk in video.iter_content(1024 * 1024):
                    target.write(chunk)
        print("已保存 video.mp4")
        break
    time.sleep(15)
else:
    raise TimeoutError(f"仍未完成；设置 ZCLOUD_VIDEO_TASK_ID={task_id} 后继续查询")

提交请求本身超时、没有拿到 ID 时，可能已经在上游创建任务。先检查控制台日志或联系支持，不要自动重试 POST。查询或下载失败后可使用同一任务 ID 恢复，不必再次付生成费用。

计费怎么核对

生成费用 = 对应规格的平台基础秒价 × 有效分组倍率 × 计费秒数。 按输出视频规格和计费时长收费，不按排队或生成等待的几分钟收费，也不是按文件 MB 或文本 Token 收费。

以 2026-10-17 视频分组 1.8 倍率的基础档为例：

模型	规格	分组价 / 视频秒	示例计费时长	预计平台扣费
`veo-3.1-lite`	720p，有声	0.6570	4 秒	2.6280
`veo-3.1`	720p，有声	5.2560	4 秒	21.0240
`kling-3.0`	720p，无声	1.0800	5 秒	5.4000
`minimax-h3`	768p，有声	0.9000	4 秒	3.6000

页面 $ 表示平台额度，不是真实美元。上表分组价已经含倍率，不要再乘一次 1.8。实际日志可能存在整数额度换算的极小误差；价格、规格和分组可能调整，下单前以模型广场为准。官方参考价只用于比较，不直接决定实际扣费。

常见问题

现象	怎么处理
400，参数或规格不支持	检查模型、时长、分辨率、音频；H3 不要传 2K，不要传 `stream`
401 / 403	检查 Key 是否有效、额度、模型白名单及分组权限
503，无可用渠道	确认 Key 可见模型、自定义 AUTO 含视频组，以及当前渠道可用性
生成完成，但拿不到下载链接	继续查询 `metadata.storage.status`；完成生成不等于完成转存
`/content` 返回 202	尚未转存完成，按 `Retry-After` 等待；不要把 JSON 响应当成 MP4
`/content` 返回 503	转存或存储异常，稍后查询或联系支持，不要因此重新生成
OSS 返回 403	签名可能过期，重新查询任务获取新链接；不要删除 URL 的签名参数
查询任务返回 404	检查任务 ID 和账号；只能访问所属账号的任务
轮询等待很久	记录任务 ID，隔一段时间继续查询；不要把 HTTP 超时当作任务已取消

联系支持时提供模型名、任务 ID、请求时间、响应中的 request ID 和错误信息即可，不要发送完整 API Key 或签名下载 URL。