byted-seedance-video-generate

视频生成技能

此技能使用 Doubao Seedance 1.0/1.5 模型生成视频。

触发条件

1. 用户希望根据文本描述生成视频
2. 用户希望基于图像（首帧/尾帧）创建视频
3. 用户希望使用参考素材（图像、视频、音频）创建视频
4. 用户询问视频生成能力

用法

环境变量

使用此技能前，请确保已设置以下环境变量：

• ARK_API_KEY 或 MODEL_VIDEO_API_KEY 或 MODEL_AGENT_API_KEY：视频生成服务的 API 密钥
• MODEL_VIDEO_API_BASE：API 基础 URL（可选，有默认值）
• MODEL_VIDEO_NAME：模型名称（可选，有默认值）

函数签名

async def video_generate(
    params: list,
    batch_size: int = 10,
    max_wait_seconds: int = 1200,
    model_name: str = None,
) -> Dict:

参数

params (list[dict])

视频生成请求列表。每一项都是一个包含以下字段的字典：

每项必填：

• video_name (str)：输出视频文件的名称/标识符
• prompt (str)：描述要生成的视频的文本。支持中文和英文。

每项可选——输入素材：

• first_frame (str)：首帧图像的 URL
• last_frame (str)：尾帧图像的 URL
• reference_images (list[str])：1-4 个用于风格/内容参考的图像 URL
• reference_videos (list[str])：0-3 个参考视频 URL（mp4/mov，每个 2-15s，总时长 ≤15s）
• reference_audios (list[str])：0-3 个参考音频 URL（mp3/wav，每个 2-15s，总时长 ≤15s）

每项可选——视频输出参数：

• ratio (str)：宽高比。选项："16:9"（默认）、"9:16"、"4:3"、"3:4"、"1:1"、"2:1"、"21:9"、"adaptive"
• duration (int)：视频时长，单位为秒。范围：根据模型不同为 2-12s
• resolution (str)：视频分辨率。选项："480p"、"720p"、"1080p"
• frames (int)：总帧数。必须在 [29, 289] 范围内，并符合 25 + 4n 格式
• camera_fixed (bool)：锁定摄像机移动。默认值：false
• seed (int)：用于复现结果的随机种子。范围：[-1, 2^32-1]
• watermark (bool)：是否添加水印。默认值：false
• generate_audio (bool)：是否生成音频。仅 Seedance 1.5 支持此参数
• tools (list[dict])：工具配置，例如 [{"type": "web_search"}]

输入模式

1. 文本生成视频：仅提供 prompt，不提供图像/视频
2. 首帧引导：提供 first_frame 作为起始图像
3. 首帧 + 尾帧引导：同时提供两者以生成转场视频
4. 参考图像：提供 reference_images 作为风格/内容参考
5. 多模态参考：组合使用 reference_images、reference_videos、reference_audios

返回值

脚本返回信息

video_generate.py 脚本将返回以下信息：

{
    "status": "success" | "partial_success" | "error",
    "success_list": [{"video_name": "video_url"}],
    "error_list": ["video_name"],
    "error_details": [{"video_name": "...", "error": {...}}],
    "pending_list": [{"video_name": "...", "task_id": "cgt-xxx", ...}]
}

根据脚本返回信息，最终返回给用户的内容包括视频生成任务的描述和视频 URL。你可以从 URL 下载视频，但仍应向用户提供视频 URL，供其查看和下载。

注意：URL 是脚本返回信息中 success_list 的 'url'。 必须通过以下两种方式返回 URL：

最终返回信息

对于 OpenClaw

1. 首先，将生成的视频保存/下载到允许的目录：

   • 建议使用：~/.openclaw/workspace/

2. 使用 message tool 发送视频，并提供以下参数：

   {
     "action": "send",
     "message": "Optional text description",
     "media": "/root/.openclaw/workspace/generated-video.mp4"
   }
   

   • 该工具将自动：读取本地文件，将其上传到频道服务器并生成 Web URL，然后作为视频消息发送

3. 确认发送成功：检查工具是否返回 {"ok": true}，以确认视频已成功发送

4. 普通文本（非 message tool）：生成后，以 Markdown 格式显示视频列表，例如：

   <video src="https://example.com/video1.mp4" width="640" controls>video-1</video>
   

   非常重要： 视频 URL 必须是以 https:// 开头的原始在线资源链接，不能是已下载视频的本地地址。

普通模式

你应返回以下三类信息：

1. 文件格式、视频文件（如果你有其他方式发送视频文件）以及视频的本地路径，例如： local_path: /root/.openclaw/workspace/skills/video-generate/xxx.mp4
2. 生成后，以 Markdown 格式展示视频列表，例如：

<video src="https://example.com/video1.mp4" width="640" controls>video-1</video>
<video src="https://example.com/video2.mp4" width="640" controls>video-2</video>

代码实现

完整实现请参见 scripts/video_generate.py。

使用示例

# Text-to-Video
python scripts/video_generate.py -p "小猫骑着滑板穿过公园" -n cat_park -r 16:9 -d 5 --resolution 720p

# First Frame Guidance
python scripts/video_generate.py -p "小猫跳起来" -n cat_jump -f "https://example.com/cat.png" -r adaptive -d 5

# First + Last Frame Guidance
python scripts/video_generate.py -p "平滑过渡动画" -n transition \
    -f "https://example.com/start.png" \
    -l "https://example.com/end.png" \
    -d 6

# Reference Images (style/content guidance)
python scripts/video_generate.py -p "[图1]戴着眼镜的男生和[图2]柯基小狗坐在草坪上" -n styled \
    --ref-images "https://example.com/boy.png" "https://example.com/dog.png" \
    -r 16:9 -d 5

# Multimodal Reference (video + audio)
python scripts/video_generate.py -p "将视频中的人物换成[图1]中的男孩" -n multimodal \
    --ref-images "https://example.com/boy.png" \
    --ref-videos "https://example.com/source.mp4" \
    --ref-audios "https://example.com/voice.wav" \
    -d 5

# With Audio Generation (Seedance 1.5 only)
python scripts/video_generate.py -p "女孩抱着狐狸，可以听到风声和树叶沙沙声" -n with_audio \
    -f "https://example.com/girl_fox.png" \
    --generate-audio \
    -m doubao-seedance-1-5-pro-251215 \
    -d 6 --resolution 1080p

# Query task status
python scripts/video_generate.py -q "cgt-20260222165751-wsnw8"

# Use specific model
python scripts/video_generate.py -p "A futuristic city" -m doubao-seedance-2-5-260628

# No watermark
python scripts/video_generate.py -p "A beautiful landscape" --no-watermark

命令行选项

选项	简写	描述
--prompt	-p	视频的文字描述（必填）
--name	-n	视频名称标识符（默认：video）
--model	-m	模型名称（默认：doubao-seedance-2-5-260628）
--ratio	-r	宽高比（默认：16:9）
--duration	-d	视频时长，单位为秒（2-12）
--resolution		视频分辨率：480p、720p、1080p
--first-frame	-f	首帧图片 URL
--last-frame	-l	尾帧图片 URL
--ref-images		参考图片 URL（以空格分隔，1-4 张图片）
--ref-videos		参考视频 URL（以空格分隔，0-3 个视频）
--ref-audios		参考音频 URL（以空格分隔，0-3 个音频）
--generate-audio		生成音频（仅限 Seedance 1.5）
--seed		用于确保结果可复现的随机种子
--no-watermark		禁用水印
--timeout	-t	最大等待时间，单位为秒（默认：1200）
--query-task	-q	通过 task_id 查询任务状态

模型回退

如果遇到模型相关错误（例如 ModelNotOpen），可以降级使用以下模型：

• doubao-seedance-1-5-pro-251215
• doubao-seedance-1-0-pro-250528

错误处理

• 如果脚本报错 "PermissionError: ARK_API_KEY or MODEL_VIDEO_API_KEY or MODEL_AGENT_API_KEY not found in environment variables"，请告知用户需要提供 ARK_API_KEY、MODEL_VIDEO_API_KEY 或 MODEL_AGENT_API_KEY 环境变量。将其写入工作区中的环境变量文件。如果文件已存在，则追加到文件末尾。确保环境变量格式正确并生效，然后重试刚才失败的视频生成任务。

注意事项

• 提示词应简洁（建议不超过 500 个字符）
• 对于首帧和尾帧，请确保宽高比与所选比例一致
• 参考图片：1-4 张，格式：jpeg/png/webp/bmp/tiff/gif
• 参考视频：0-3 个，格式：mp4/mov，总时长 ≤ 15 秒
• 参考音频：0-3 个，格式：mp3/wav，总时长 ≤ 15 秒
• 多模态输入至少需要一张图片或一个视频（不支持仅音频）
• 仅 Seedance 1.5 pro 支持音频生成
• 如果轮询超时，请使用 --query-task 和返回的 task_id