vidu-video-generation

name	vidu-video-generation
description	Generate video with vidu via bundled scripts. Use when the user wants 文生视频, 图生视频, 首尾帧生视频, 参考生视频, 创建主体 (material element), or to submit or check vidu tasks. 创建主体: upload 1–3 images, name and description, call material/elements API. Execution is script-based; run scripts in scripts/ with VIDU_TOKEN set.

Vidu Video Generation Skill

Execution model: use scripts

All execution for this skill is done by running the bundled scripts in scripts/. Do not implement the API calls yourself; run the appropriate script and use its output.

• Submit task: Run scripts/run_vidu_generation.py with the user’s prompt and optional image path(s). It handles upload (if needed) → submit → returns task_id. No wait mode; use task_id to query status/result when needed.
• Query task status/result: Use scripts/get_task_result.py <task_id> (or GET /vidu/v1/tasks/{task_id}) to get current state and, when success, video URL(s).
• Task state SSE (流式): GET https://service.vidu.cn/vidu/v1/tasks/state?id={task_id} is an SSE stream. When using this endpoint, return the SSE output directly to the model — do not wait for a terminal state. Each event includes state, estimated_time_left, err_code, and queue_wait_time (排队预测时间, unit: minutes).
• 主体预处理 (script): Run scripts/pre_process_element.py with --name and 1–3 --image-uri (ssupload:?id=...); calls POST material/elements/pre-process only, outputs full response including recaption (style, description). Use when you need recaption alone or as a step before create_element.
• 创建主体 (script): Run scripts/create_element.py with --name, 1–3 --image paths, and optional --description/--style; uploads images → runs pre_process_element.py (required every time) → POSTs to material/elements (uses pre-process recaption when --description is omitted), outputs element id and version.
• Step-by-step: If you need to run individual steps, use scripts/upload_image.py, scripts/pre_process_element.py, scripts/create_element.py, scripts/list_elements.py, scripts/submit_task.py, scripts/get_task_result.py, and scripts/get_upload_url.py as needed. See scripts/README.md for usage and examples.

Ensure the environment has VIDU_TOKEN set. VIDU_BASE_URL configures the service domain: 中国大陆 使用 https://service.vidu.cn（默认），海外/非中国地区 使用 https://service.vidu.com。Scripts require Python 3 and requests; see scripts/README.md for details.

---

Overview

Vidu video generation is asynchronous: submit a task → get task_id → use task_id to query task status/result (e.g. get_task_result.py or GET API) when needed. The scripts do not wait; they return task_id after submit.

• 文生视频 (text2video): 一段文字。Q3 时长 1–16、宽高比 16:9/9:16/1:1/4:3/3:4、transition pro/speed；Q2 时长 2–8、不传 transition。
• 图生视频 (img2video): 一张图 + 一段文字。宽高比不传（由输入图决定）。Q3 时长 1–16、transition pro/speed；Q2 时长 2–8、transition pro/speed。
• 首尾帧生视频 (headtailimg2video): 两张图（首帧、尾帧）+ 一段文字。Q3 时长 1–16、Q2 时长 2–8，transition pro/speed。
• 参考生视频 (character2video): 图 + 主体 + 文字（可组合）；文字必填。图+主体合计最多 7 个，至少提供一种（图或主体）。仅 Q2，时长 2–8，不传 transition。主体在 prompts 中通过 type: "material"、material.id、material.version 引用。
• 创建主体 (Create element): 上传 1–3 张图片，提供主体名称和可选描述；必须先调用 POST /vidu/v1/material/elements/pre-process（即使用户指定了描述也需调用），再调用 POST /vidu/v1/material/elements；未指定描述时使用 pre-process 返回的 recaption。图片需先经现有上传流程得到 ssupload:?id=...。响应含主体 id 与 version，用于参考生任务。
• 查询主体: GET /vidu/v1/material/elements/personal，参数 pager.page、pager.pagesz、keyword、modalities；返回 elements[].id、version。

详见上方「任务支持列表」与 references/parameters.md。

---

任务支持列表 (Supported task list)

Before choosing script arguments, ensure the user’s request matches one of the supported task types and constraints below. references/parameters.md has the same list for quick lookup.

模型版本 (Model version)

• Q3 → model_version: "3.2"
• Q2 → model_version: "3.1"

任务类型	type	输入	模型	时长(秒)	宽高比	生成模式 transition	清晰度
文生视频	text2video	一段文字	Q3	1–16	16:9, 9:16, 1:1, 4:3, 3:4	pro(电影大片), speed(闪电出片)	1080p
文生视频	text2video	一段文字	Q2	2–8	16:9, 9:16, 1:1, 4:3, 3:4	不传	1080p
图生视频	img2video	一张图 + 一段文字	Q3	1–16	依据输入图片，参数不传	pro, speed	1080p
图生视频	img2video	一张图 + 一段文字	Q2	2–8	依据输入图片，不传	pro, speed	1080p
首尾帧生视频	headtailimg2video	两张图 + 一段文字	Q3	1–16	—	pro, speed	1080p
首尾帧生视频	headtailimg2video	两张图 + 一段文字	Q2	2–8	—	pro, speed	1080p
参考生视频	character2video	图+主体+文字（文字必填；图+主体合计最多7）	Q2	2–8	—	不传	1080p

• 文生视频: 只传文字，--type text2video。Q2 时不要传 transition。
• 图生视频: 仅支持 1 张图片 + 1 段文字；宽高比由输入图决定，调用时 不要传 aspect_ratio。
• 首尾帧生视频: 固定 2 张图 + 1 段文字，--type headtailimg2video；两张图顺序为「首帧、尾帧」。
• 参考生视频: 图+主体+文字（文字必填；图+主体合计最多 7），--type character2video；仅 Q2，不要传 transition。可用 --image-uri、--material "name:id:version" 组合。

脚本会根据 --type 自动省略不该传的参数（如 img2video 不传 aspect_ratio，character2video 不传 transition）。选 type 和 model-version 时请严格按上表。

---

创建主体（先 pre-process，再 POST /vidu/v1/material/elements）

创建主体用于在参考生任务中使用的 material element：上传 1–3 张图、名称与描述，接口返回主体 id 与 version。流程：必须先调用 POST /vidu/v1/material/elements/pre-process（即使用户指定了描述也需调用；body: components, name, type: "user"），响应中的 recaption（style、description）为 vidu 预生成描述；若未特别指定描述，可用该描述填充主体描述；再调用创建主体接口。

• Pre-process URL: {VIDU_BASE_URL}/vidu/v1/material/elements/pre-process，详见 references/api_reference.md §3b。
• 创建主体 URL: https://service.vidu.cn/vidu/v1/material/elements（或 {VIDU_BASE_URL}/vidu/v1/material/elements）
• Method: POST
• Headers: 与现有约定一致（Authorization: Token {token}, Content-Type: application/json, User-Agent）。

前置条件: 每张图片先按「Upload images」三步（CreateUpload → PUT to put_url → FinishUpload）得到 ssupload:?id={id}；共 1–3 张图。同一张图可复用同一 id 填 content 与 src_img，或按 API 要求使用不同 id。

Request body: id（pre-process 响应中的主体 id，创建时必带）, name（主体名称）, modality: "image", type: "user", components（1–3 个：第一个 type: "main"，其余 type: "auxiliary"；每项含 content、src_img 均为 ssupload:?id=...，content_type: "image"）, version: "0", recaption: { description, style? }（可由 pre-process 响应的 recaption 填充）。详见 references/api_reference.md §3b、§3c。

Example: 见 api_reference。成功响应含 element id、version，用于参考生任务。

---

查询主体（GET /vidu/v1/material/elements/personal）

• URL: https://service.vidu.cn/vidu/v1/material/elements/personal
• Method: GET
• Query: pager.page（页码）、pager.pagesz（每页条数）、pager.page_token（可选）、keyword（搜索词，URL 编码）、modalities（可重复，如 modalities=image）。
• Response: elements[]，每项含 id、name、version、components、recaption 等；用 id 与 version 在参考生任务中引用。另有 next_page_token。

---

参考生任务中引用主体（character2video）

主体仅可在参考生任务（character2video）中使用。提交 POST /vidu/v1/tasks 时：type: "character2video"；input.prompts 需包含 (1) 文本 prompt（必填）；(2) 可选图 prompt（type: "image"）；(3) 可选 material prompt（type: "material", name, material: { "id", "version" }）。可图+主体+文字组合，文字必填，图+主体合计最多 7 个，至少一种。

Example:

{
  "input": {
    "prompts": [
      { "type": "text", "content": "[@艾莉娅]" },
      { "type": "material", "name": "艾莉娅", "material": { "id": "3073530415201165", "version": "1765430214" } }
    ],
    "editor_mode": "normal",
    "enhance": true
  },
  "type": "character2video",
  "settings": { "duration":                  

---

Bundled resources

• scripts/ — Use these for all execution. See scripts/README.md for dependency (Python 3, requests), environment (VIDU_TOKEN, VIDU_BASE_URL), and example commands for each script.
• references/api_reference.md — Full API contracts (for understanding or when debugging).
• references/parameters.md — 任务支持列表与参数约束 (supported task list and parameter constraints).
• references/errors_and_retry.md — Error handling (read when interpreting failures).

---

Workflow (script-based)

1. Get token and domain: Ensure VIDU_TOKEN is set. Set VIDU_BASE_URL by region: mainland China → https://service.vidu.cn (default); outside China → https://service.vidu.com.

2. 文生视频 (text2video)
   run_vidu_generation.py text2video --prompt "<user text>"，按任务支持列表加 --model-version 3.2|3.1、--duration、--aspect-ratio、--transition（Q2 时不传 transition）。

3. 图生视频 (img2video)
   仅 1 张图 + 1 段文字。run_vidu_generation.py img2video --prompt "<user text>" --image <path>。不要传 --aspect-ratio（脚本会省略）。

4. 首尾帧生视频 (headtailimg2video)
   2 张图（首帧、尾帧）+ 1 段文字。run_vidu_generation.py headtailimg2video --prompt "<user text>" --image <首帧路径> --image <尾帧路径>，并加 --model-version、--duration、--transition。

5. 参考生视频 (character2video)
   图+主体+文字（文字必填；图+主体合计最多 7），仅 Q2。run_vidu_generation.py character2video --prompt "<user text>" [--image ...] [--material "name:id:version" ...]（不要传 transition）。

6. Interpret output

   • Script exits 0 and prints task_id. Caller uses this task_id to query status/result later (e.g. get_task_result.py <task_id> or GET /vidu/v1/tasks/{task_id}).
   • Script exits non-zero or prints error JSON to stderr: report failure to the user and, if present, err_code / err_msg.

If you cannot use run_vidu_generation.py (e.g. custom body or step-by-step control), run the steps manually in order:

• Upload images: python scripts/upload_image.py <image_path> for each image; capture the output ssupload:?id=.... The same upload flow is used for img2video/headtailimg2video/character2video and for 创建主体 (1–3 images).
• Get upload resource URL (optional): To obtain a public download URL for an uploaded file, run python scripts/get_upload_url.py <ssupload_uri_or_id>. The returned URL is valid for 1 hour only; after expiry, run the script again to get a new URL.
• Submit: python scripts/submit_task.py --type ... --prompt "..." [--image-uri ...] [--material ...]；character2video 时文字必填，图+主体合计最多 7。Capture task_id from stdout. Respect 任务支持列表 (img2video 不传 aspect_ratio，character2video 不传 transition).
• Query status/result: python scripts/get_task_result.py <task_id>. Call when needed; response includes state and, when success, nomark_uri line(s).

---

Output to the user

• After submit: Return the task_id to the user; mention that video generation is in progress and they can query status/result later with that task_id (e.g. get_task_result.py or GET /vidu/v1/tasks/{task_id}).
• After query (get_task_result.py): If state is success, return the nomark_uri link(s) to the user; if failed, report err_code / err_msg.
• Failure (submit or script error): Clearly state that the task failed and, if available, the reason (err_code / err_msg from script or references).

---

Fallback (no Python)

If the environment cannot run Python scripts, you cannot execute this skill as intended. Tell the user that this skill requires script execution (Python 3, requests, VIDU_TOKEN) and point them to scripts/README.md and references/api_reference.md for manual API usage elsewhere.