Volcengine Video Studio

---

name: volcengine-video-studio description: Production-ready Volcengine/ARK video generation for prompt-to-video, image-to-video, and draft-video refinement. Use when users want a hands-on skill that can submit jobs, poll status, inspect task payloads, and download finished outputs with Seedance-compatible models. 中文：适合火山引擎 / ARK 兼容接口的视频生成实战工作流；支持文生视频、图生视频、草稿视频优化、任务提交与轮询、结果检查和成片下载。

---

volcengine-video-studio

Use this skill to actually submit, poll, inspect, and download Volcengine / ARK video generation jobs instead of only drafting prompts.

中文说明

这是一个面向 火山引擎 / ARK 兼容视频生成接口 的生产可用型 skill，重点不是只写视频提示词，而是把整条生成链路真正跑通，从提交任务、轮询状态，到拿回结果、下载成片，都能一把做完。

它特别适合下面这些对外场景：

文生视频

图生视频

草稿视频二次优化

提交生成任务并持续轮询状态

检查任务返回内容与原始 payload

将生成好的视频自动下载到本地

如果你想要的是一个能真实发起任务、能追踪任务进度、能拿到最终视频文件、适合实战交付的火山视频 skill，这个版本就是为这种需求准备的。

Treat the prompt and optional reference media as runtime input for each task. Do not reuse documentation example prompts or example media in a real generation request unless the user explicitly asks for that exact example.

What this skill is good at

text-to-video from a task-specific prompt

image-to-video using a local file, data URL, or remote image URL

draft-video refinement with a guiding prompt

polling existing tasks and downloading finished outputs

switching between a faster default model and a stronger alternate model

Default path

Run the bundled script with the actual prompt for the current task:

python3 scripts/generate_video.py "当前任务的实际视频提示词"

To switch to the alternate model for one run:

VOLCENGINE_VIDEO_MODEL=doubao-seedance-1-5-pro-251215 \
python3 scripts/generate_video.py "当前任务的实际视频提示词"

By default the script:

submits the task

polls until the task finishes

extracts returned video URLs from the task payload

downloads generated files into ~/Desktop/volcengine-videos/-/

Required config

The script reads config from env vars:

VOLCENGINE_API_KEY or ARK_API_KEY

VOLCENGINE_VIDEO_MODEL (recommended)

VOLCENGINE_VIDEO_ENDPOINT or VOLCENGINE_ENDPOINT or ARK_BASE_URL

Recommended video models:

doubao-seedance-1-0-pro-fast-251015 — default, faster iteration

doubao-seedance-1-5-pro-251215 — alternate higher-tier option

Default behavior:

if VOLCENGINE_VIDEO_MODEL is unset, the script defaults to doubao-seedance-1-0-pro-fast-251015

avoid relying on VOLCENGINE_MODEL for video runs when that env var is also used for image generation

Typical endpoint:

https://ark.cn-beijing.volces.com/api/v3

The script calls:

POST /contents/generations/tasks

GET /contents/generations/tasks/{task_id}

Common workflows

1. Text to video

python3 scripts/generate_video.py "为当前需求编写的视频提示词" \
  --ratio 16:9 \
  --duration 5

2. Image to video

python3 scripts/generate_video.py "描述你希望图片如何动起来" \
  --image ~/Desktop/reference.png \
  --ratio 9:16 \
  --duration 5

3. Draft/sample video to final video

python3 scripts/generate_video.py "说明要保留什么、增强什么" \
  --video ~/Desktop/draft.mp4

4. Inspect an existing task only

python3 scripts/generate_video.py --task-id  --wait false

5. Submit only, do not wait

python3 scripts/generate_video.py "当前任务的实际视频提示词" \
  --ratio 16:9 \
  --wait false

6. Use raw content JSON when the target model needs a custom body

python3 scripts/generate_video.py --content-json '[
  {"type":"text","text":"当前任务的实际视频提示词"},
  {"type":"image_url","image_url":{"url":"https://example.com/reference.png"}}
]'

Local media support

For --image and --video:

local file path → converted to data: URL automatically

https://... URL → sent as-is

data:... URL → sent as-is

This makes local reference media usable without manual upload steps.

Key options

--ratio 16:9|9:16|1:1|adaptive

--duration

--frames

--seed

--resolution

--camera-fixed true|false

--watermark true|false

--callback-url

--poll-interval

--timeout

--download-results true|false

--download-dir

--print-request

Execution checklist

1. Confirm whether the user wants text-to-video, image-to-video, or draft-video refinement. 2. Treat the prompt as task-specific runtime input; never carry over example prompt text or example media into a real run unless explicitly requested. 3. Choose prompt-first mode by default; use --content-json only when the API shape must be customized. 4. Pass local reference media directly with --image or --video. 5. Prefer --duration for whole-second clips and --frames only when finer control is required. 6. Poll by default so the final answer includes actual output URLs or downloaded files. 7. Mention the saved file paths when downloads are enabled. 8. If the API returns an unexpected structure, surface the raw JSON instead of guessing.

Troubleshooting

Missing key → set VOLCENGINE_API_KEY

Missing or wrong model → set VOLCENGINE_VIDEO_MODEL

If a video run accidentally picks an image model (for example doubao-seedream-4-5) → explicitly set VOLCENGINE_VIDEO_MODEL instead of reusing VOLCENGINE_MODEL

Missing endpoint → set VOLCENGINE_VIDEO_ENDPOINT

401/403 → key invalid or missing permission

404 → endpoint wrong or region mismatch

400 → unsupported model/parameter combination

Task remains queued too long → check quota, rate limit, or model availability

No obvious video URL in response → inspect raw

References

references/sources.md

references/api-notes.md

ing VOLCENGINE_MODEL

Missing endpoint → set VOLCENGINE_VIDEO_ENDPOINT

401/403 → key invalid or missing permission

404 → endpoint wrong or region mismatch

400 → unsupported model/parameter combination

Task remains queued too long → check quota, rate limit, or model availability

No obvious video URL in response → inspect raw

References

references/sources.md

references/api-notes.md

Missing key → set VOLCENGINE_API_KEY

Missing or wrong model → set VOLCENGINE_VIDEO_MODEL

If a video run accidentally picks an image model (for example doubao-seedream-4-5) → explicitly set VOLCENGINE_VIDEO_MODEL instead of reusing VOLCENGINE_MODEL

Missing endpoint → set VOLCENGINE_VIDEO_ENDPOINT

401/403 → key invalid or missing permission

404 → endpoint wrong or region mismatch

400 → unsupported model/parameter combination

Task remains queued too long → check quota, rate limit, or model availability

No obvious video URL in response → inspect raw