视频生成

大约 4 分钟

视频生成

接入结论

创建任务：POST https://www.yuzhixiaolongxia.com/v1/videos
查询任务：GET https://www.yuzhixiaolongxia.com/v1/videos/{id}
下载内容：GET https://www.yuzhixiaolongxia.com/v1/videos/{id}/content
认证：Authorization: Bearer <你的 API 令牌>
令牌分组：视频
接口类型：异步任务
本页范围：Sora 系列 + Veo3 系列等通用视频模型

Seedance 看专文

Seedance 2.0 视频生成有完整专文，包含 6 个模型选择、metadata.reference_images/videos/audios、本地素材上传等：

Seedance 2.0 视频生成教程（业务视角）
Seedance 2.0 程序接入文档（工程师视角）

Seedance 的端点是 /v1/video/generations（带 s），本页讲的是通用 /v1/videos，两者不通用。

模型分组速查

系列	典型模型 ID	特点
Sora	`sora-2`、`sora-2-pro`	文生视频，Pro 版质量更高
Veo3	`veo_3_1-fast`、`veo_3_1-fast-hd`、`veo_3_1-fast-fl`、`veo_3_1-fast-fl-hd`	Veo3 快速系列，含 HD 与 fl 变体
Seedance	看专文	6 个模型，支持 reference_images / reference_videos

实际可用 ID 以模型广场为准，调用前建议跑一次 GET /v1/models 确认。

第一步：创建任务

请求体（JSON）

字段	类型	必填	说明
`model`	string	是	视频模型 ID
`prompt`	string	是	视频描述
`duration`	integer	否	时长（秒），默认 5
`size`	string	否	分辨率，例如 `1280x720`
`seed`	integer	否	随机种子，复现结果时使用

TypeScript

const create = await fetch("https://www.yuzhixiaolongxia.com/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.YZX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "sora-2",
    prompt: "A cinematic shot of a cat walking through a sunlit garden, 4K, smooth motion",
    duration: 5,
  }),
});

const task = await create.json();
console.log("task id:", task.id ?? task.task_id);

Python

import os
import requests

API_BASE = "https://www.yuzhixiaolongxia.com/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['YZX_API_KEY']}",
    "Content-Type": "application/json",
}

resp = requests.post(
    f"{API_BASE}/videos",
    headers=HEADERS,
    json={
        "model": "sora-2",
        "prompt": "A cinematic shot of a cat walking through a sunlit garden, 4K",
        "duration": 5,
    },
    timeout=60,
)
task = resp.json()
task_id = task.get("id") or task.get("task_id")
print("task id:", task_id)

提交响应

{
  "id": "video-task-abc123",
  "task_id": "video-task-abc123",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "created": 1714000000
}

优先读 id，没有再读 task_id，两者都没有要把响应体记到日志方便排查。

第二步：轮询状态

GET /v1/videos/{id}
Authorization: Bearer <你的令牌>

状态机

status	本地动作
`queued` / `pending`	排队中，保持轮询
`in_progress` / `processing`	生成中，保持轮询
`completed` / `succeeded` / `success`	优先读取响应里的视频地址，再调用下载或入库
`unknown`	有视频地址按完成处理；没有继续轮询
`failed` / `cancelled`	停止轮询，保存错误信息

轮询建议

创建后等 8~10 秒再首次查询，太频繁没有意义
后续 8~15 秒查一次
总等待 3~5 分钟；超时改为人工/异步重试
不要因为一次 queued 就重复创建新任务，会浪费额度

完成响应

{
  "id": "video-task-abc123",
  "status": "completed",
  "data": [
    { "url": "https://www.yuzhixiaolongxia.com/v1/files/video-abc.mp4", "duration": 5 }
  ]
}

视频地址可能出现在多个字段，建议按以下优先级取：

data[0].url
data.result_url
result_url
url / video_url
output_url / download_url

如果都没有，再走 GET /v1/videos/{id}/content 兜底下载。

第三步：下载视频

curl -L "https://www.yuzhixiaolongxia.com/v1/videos/video-task-abc123/content" \
  -H "Authorization: Bearer $YZX_API_KEY" \
  --output result.mp4

下载链路同样需要带 Authorization。

Python 完整闭环示例

import os
import time
import requests

API_BASE = "https://www.yuzhixiaolongxia.com/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['YZX_API_KEY']}",
    "Content-Type": "application/json",
}


def create_task() -> str:
    resp = requests.post(
        f"{API_BASE}/videos",
        headers=HEADERS,
        json={
            "model": "sora-2",
            "prompt": "A beautiful sunset over the ocean, cinematic, 4K",
            "duration": 5,
        },
        timeout=60,
    )
    resp.raise_for_status()
    body = resp.json()
    task_id = body.get("id") or body.get("task_id")
    if not task_id:
        raise RuntimeError(f"missing task id: {body}")
    return task_id


def wait_done(task_id: str, max_attempts: int = 30) -> dict:
    for _ in range(max_attempts):
        time.sleep(10)
        r = requests.get(f"{API_BASE}/videos/{task_id}", headers=HEADERS, timeout=30)
        r.raise_for_status()
        body = r.json()
        status = body.get("status")
        if status in ("completed", "succeeded", "success"):
            return body
        if status in ("failed", "cancelled"):
            raise RuntimeError(f"task failed: {body}")
    raise TimeoutError(f"task {task_id} timeout")


def download(task_id: str, body: dict, out: str) -> None:
    data = body.get("data") or []
    url = (data[0].get("url") if data else None) or body.get("url")
    if not url:
        url = f"{API_BASE}/videos/{task_id}/content"
    r = requests.get(url, headers=HEADERS, stream=True, timeout=120)
    r.raise_for_status()
    with open(out, "wb") as f:
        for chunk in r.iter_content(chunk_size=1 << 20):
            f.write(chunk)


task_id = create_task()
result = wait_done(task_id)
download(task_id, result, "result.mp4")
print("done")

常见问题

一直 `pending`

视频队列偶尔较长，等 2~3 分钟再看；不要重复提交。

`failed`

提示词触发内容审核（暴力 / 露骨 / 真人肖像滥用等） → 改写提示词
令牌不在视频分组 → 看令牌分组介绍
模型 ID 拼写错 → 用 GET /v1/models 查正确 ID

`n8n` HTTP 节点超时

把节点 Timeout 调到 300000 ms（5 分钟），用 Wait 节点拆分轮询，不要让一个节点阻塞等结果。

下载链接 403

链接必须带 Authorization。直接在浏览器粘贴是打不开的，需要走脚本带 Header 下载。

上一步：图像生成 | 下一步：模型列表