Vidu Video Generation Skill

---

name: vidu-skills

description: Generate video by calling the official Vidu API with curl. Use when the user wants 文生视频, 图生视频, 首尾帧生视频, 参考生视频, 创建主体 (material element), or to submit or check vidu tasks. Requires VIDU_TOKEN and optional VIDU_BASE_URL.

compatibility: Requires ability to run curl (or equivalent HTTP client). Set VIDU_TOKEN in the environment; VIDU_BASE_URL optional (default https://service.vidu.cn). See references/api_reference.md for full API.

version: 1.0.1

---

# Vidu Video Generation Skill

Generate AI videos with Vidu (生数) via direct API calls — text-to-video, image-to-video, start-end frame, reference-based generation, and material elements, up to 1080p. Use curl with VIDU_TOKEN.

Execution model: use curl (direct API)

**All execution is done by calling the official Vidu API** with curl (or any HTTP client). Base URL: **$VIDU_BASE_URL** (default `https://service.vidu.cn` for mainland China; `https://service.vidu.com` for overseas).

**Required headers for all requests:**

| Header | Value |

|--------|--------|

| Authorization | `Token $VIDU_TOKEN` |

| Content-Type | `application/json` |

| User-Agent | `viduclawbot/1.0 (+$VIDU_BASE_URL)` |

**Main endpoints:**

---

Key Capabilities

---

Setup

1. Obtain a VIDU token (e.g. from the official Vidu console).

2. Set environment variables:

- `export VIDU_TOKEN="your-token"` (required)

- `export VIDU_BASE_URL=https://service.vidu.cn` (mainland China, default) or `https://service.vidu.com` (overseas)

3. **Dependency**: curl or any HTTP client that can send JSON and binary PUT. No Python or scripts required for execution.

---

Data usage note

This skill sends user-provided text prompts, image data, and task parameters to the Vidu API (service.vidu.cn or service.vidu.com) for video generation. Input data is not persisted locally beyond what is needed for the request. Data handling follows Vidu’s official policy.

---

Overview

Vidu video generation is **asynchronous**: submit a task → get **task_id** → use task_id to **query** status/result (GET `/vidu/v1/tasks/{task_id}` or SSE `/vidu/v1/tasks/state?id=`) when needed.

See **任务支持列表** below and **references/parameters.md**.

---

任务支持列表 (Supported task list)

When building the POST `/vidu/v1/tasks` body, ensure the user’s request matches one of the supported task types and constraints below. All parameters are passed in the request **body** (type, input.prompts, settings). **references/parameters.md** has the same list for quick lookup.

**模型版本 (Model version)**

| 任务类型 | 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 |

---

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

Create a material element for use in character2video: upload 1–3 images, name and description; API returns element `id` and `version`. **Flow**: **First** call **POST** `$VIDU_BASE_URL/vidu/v1/material/elements/pre-process` (required even if user provides description; body: `components`, `name`, `type: "user"`). Response includes `recaption` (style, description). Then call **POST** `$VIDU_BASE_URL/vidu/v1/material/elements` with the pre-process response `id`, same `components`, and `recaption` (or user description).

**Pre-process**: POST `$VIDU_BASE_URL/vidu/v1/material/elements/pre-process`. See **references/api_reference.md** §3b.

**Create element**: POST `$VIDU_BASE_URL/vidu/v1/material/elements`. Body: `id` (from pre-process), `name`, `modality: "image"`, `type: "user"`, `components` (1–3 items: **content** = `ssupload:?id={id}`, **src_img** = `ssupload:?id={id}`, `content_type: "image"`), `version: "0"`, `recaption`. See **references/api_reference.md** §3c.

**Prerequisite**: Each image must be uploaded first (Create upload → PUT to put_url → Finish) to get `ssupload:?id={id}`; use these in `components`.

---

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

---

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

Materials are used only in **character2video**. When submitting POST `/vidu/v1/tasks`: `type: "character2video"`; `input.prompts` must include **(1) text prompt (required)**; (2) optional image prompt (`type: "image"`); (3) optional material prompt (`type: "material"`, `name`, `material: { "id", "version" }`). Combine image + material + text; text required; **image + material at most 7**, at least one.

**Example body**:

{
  "input": {
    "prompts": [
      { "type": "text", "content": "[@艾莉娅]" },
      { "type": "material", "name": "艾莉娅", "material": { "id": "3073530415201165", "version": "1765430214" } }
    ],
    "editor_mode": "normal",
    "enhance": true
  },
  "type": "character2video",
  "settings": { "duration": 5, "resolution": "1080p", "movement_amplitude": "auto", "aspect_ratio": "16:9", "sample_count": 1, "schedule_mode": "normal", "codec": "h265", "model_version": "3.1", "use_trial": false }
}

---

Bundled resources

---

Workflow: Submit → Query → Get video URL

**Summary**: Submit (POST `/vidu/v1/tasks` → get `task_id`) → Query (GET `/vidu/v1/tasks/{task_id}` or SSE `/vidu/v1/tasks/state?id=`) → Get video from `creations[].nomark_uri`.

1. 文生视频 — Submit (curl example)

curl -s -X POST "$VIDU_BASE_URL/vidu/v1/tasks" \
  -H "Authorization: Token $VIDU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "User-Agent: viduclawbot/1.0 (+$VIDU_BASE_URL)" \
  -d '{
    "type": "text2video",
    "input": {
      "prompts": [{"type": "text", "content": "A cat walks in the snow at sunset"}],
      "editor_mode": "normal",
      "enhance": true
    },
    "settings": {
      "duration": 5,
      "resolution": "1080p",
      "aspect_ratio": "16:9",
      "model_version": "3.2",
      "transition": "pro",
      "sample_count": 1,
      "schedule_mode": "normal",
      "codec": "h265",
      "use_trial": false
    }
  }'

Response contains `id` (task_id). Use it to query.

2. 查询任务结果 (curl example)

curl -s "$VIDU_BASE_URL/vidu/v1/tasks/$TASK_ID" \
  -H "Authorization: Token $VIDU_TOKEN" \
  -H "User-Agent: viduclawbot/1.0 (+$VIDU_BASE_URL)"

3. 任务状态 SSE (optional, stream to user)

curl -N -s "$VIDU_BASE_URL/vidu/v1/tasks/state?id=$TASK_ID" \
  -H "Authorization: Token $VIDU_TOKEN" \
  -H "Accept: text/event-stream" \
  -H "User-Agent: viduclawbot/1.0 (+$VIDU_BASE_URL)"

Return the SSE output directly to the user; do not wait for a terminal state.

4. 图片上传（图生视频 / 首尾帧 / 创建主体前）

**Step 1 — Create upload:**

curl -s -X POST "$VIDU_BASE_URL/tools/v1/files/uploads" \
  -H "Authorization: Token $VIDU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "User-Agent: viduclawbot/1.0 (+$VIDU_BASE_URL)" \
  -d '{"metadata":{"image-width":"1920","image-height":"1080"},"scene":"vidu"}'

From response take `id` and `put_url`.

**Step 2 — PUT image bytes to put_url:**

curl -s -X PUT "$PUT_URL" \
  -H "Content-Type: image/jpeg" \
  -H "x-amz-meta-image-width: 1920" \
  -H "x-amz-meta-image-height: 1080" \
  --data-binary @/path/to/image.jpg

Save the **ETag** from the response (use quotes if the server returns them).

**Step 3 — Finish upload:**

curl -s -X PUT "$VIDU_BASE_URL/tools/v1/files/uploads/$UPLOAD_ID/finish" \
  -H "Authorization: Token $VIDU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "User-Agent: viduclawbot/1.0 (+$VIDU_BASE_URL)" \
  -d "{\"etag\":\"$ETAG\",\"id\":\"$UPLOAD_ID\"}"

Use `ssupload:?id=$UPLOAD_ID` in task prompts or in element `components`.

5. 创建主体（curl flow）

After uploading 1–3 images to get `ssupload:?id=...`:

**Pre-process** — POST `$VIDU_BASE_URL/vidu/v1/material/elements/pre-process` with body `components` (array: each item has **content** = `ssupload:?id={id}`, **src_img** = `ssupload:?id={id}`, `content_type: "image"`), `name`, `type: "user"`. See api_reference §3b.

**Create** — POST `$VIDU_BASE_URL/vidu/v1/material/elements` with body including `id` (from pre-process response), `name`, `modality: "image"`, `type: "user"`, `components`, `version: "0"`, `recaption` (from pre-process or user). See api_reference §3c.

---

Implementation Guide

1. **Determine task type**: text2video, img2video, headtailimg2video, character2video, or 创建主体.

2. **Choose parameters**: From 任务支持列表 select `model_version` (Q2/Q3), `duration`, `aspect_ratio`, `transition` (omit for img2video aspect_ratio, character2video transition).

3. **Prepare inputs**: For img2video/headtailimg2video/character2video or 创建主体, upload image(s) via Create upload → PUT → Finish to get `ssupload:?id=...`. For character2video with materials, ensure elements exist (create via pre-process + create element if needed).

4. **Submit**: curl POST `$VIDU_BASE_URL/vidu/v1/tasks` with JSON body (type, input.prompts, settings). Capture `id` as task_id.

5. **Query**: curl GET `$VIDU_BASE_URL/vidu/v1/tasks/{task_id}` (or use SSE) until state is success/failed; on success return `creations[].nomark_uri`; on failure return err_code/err_msg.

---

Prompt Tips

---

Output to the user

---

Fallback (no curl)

If the environment **cannot** run curl (or equivalent HTTP client), execution as described above is not possible. Tell the user that this skill requires curl (or an HTTP client) with VIDU_TOKEN and point them to **references/api_reference.md** for manual API usage.