byted-ark-seedance-skill（字节方舟种子技能）

Ark AgentPlan Seedance Skill

概述

豆包 Seedance AI 视频生成 Skill - 火山方舟 Agent Plan 专属版本。

✨ 核心优势：

• ✅ 零配置可用 - 自动复用 Agent Plan 的 API Key，无需单独配置
• ✅ 调用原生接口 - 与语言模型共用服务入口
• ✅ 异步架构 - 提交即返回，轮询不阻塞
• ✅ 功能完整 - 支持文生视频、参考图/视频/音频、首尾帧控制、联网搜索

触发条件

用户说以下关键词时自动激活：

• 生视频、生成视频、视频生成
• seedance
• 给我做个视频、做个视频

输入参数

💡 智能参数提取：Skill 会自动从用户输入中识别参数： - "5秒"、"10秒" → duration - "竖屏"、"手机" → ratio: "9:16" - "横屏"、"电脑" → ratio: "16:9" - "方形"、"正方形" → ratio: "1:1" - "480p"、"720p"、"1080p" → resolution - "不要声音"、"静音" → generate_audio: false - "快速生成"、"用fast版" → 模型切换到 2.0 fast - "样片预览" → draft: true - "用高质量版"、"高分辨率" → 模型切换到 2.0 标准版 - "固定镜头" → camera_fixed: true - "用seed=12345" → seed: 12345 - "联网搜索" → enable_web_search: true - "低成本"、"离线模式" → service_tier: "flex"

🚀 快速开始

30 秒上手

直接在对话中说出视频需求即可：

用户: "给我生成一个小猫在草地上奔跑的视频，10秒，竖屏"
Agent: "好的，视频生成任务已提交，完成后会自动通知您...（约需3-5分钟）"

✅ 无需额外配置，语言模型能用的话生视频直接就能用

✨ 功能特性

🎯 智能模型选择

Skill 会根据用户输入自动选择最合适的模型，无需手动指定：

🎬 多模态生成模式

自动识别用户输入，选择最佳模式：

支持的高级模式：

• 首尾帧生视频："图1是开头画面，图2是结尾画面"
• 参考图生视频："图1为主体，图2为风格参考，图3为背景"
• 长视频拼接：开启 return_last_frame 后，以上一段视频的尾帧作为下一段的首帧
• 虚拟人/真人素材视频：传入 asset:// 格式的素材ID作为参考

🔄 异步轮询机制

Skill 采用 异步架构，不阻塞对话：

1. 提交任务 → 立即返回（<3秒）
2. Cron 每分钟轮询任务状态
3. 阶梯降级轮询：0-20分钟高频，之后低频
4. 最长等待 48 小时（与 API 一致）
5. 任务完成/失败自动通知用户

⚠️ 重要：必须配置 Cron 定时任务才能收到完成通知！ 详见 INSTALL.md。

📚 典型场景示例

场景 1: 简单文生视频

用户输入： "给我生成一个小猫在草地上奔跑的视频，5秒，720p"

处理：

{
  prompt: "一只可爱的小猫在绿草地上奔跑，阳光明媚，高清画质",
  duration: 5,
  ratio: "16:9",
  resolution: "720p",
  model: "doubao-seedance-2-0"
}

场景 2: 首帧生视频

用户输入： "[发了一张图片] 用这张图作为开头，生成一个日落海边的视频，8秒"

处理：

{
  prompt: "日落海边，波光粼粼，海鸥飞过，温暖治愈",
  duration: 8,
  reference_images: ["https://..."],
  model: "doubao-seedance-2-0"
}

场景 3: 首尾帧生视频

用户输入： "[发了两张图片] 图1是开头，图2是结尾，生成一个日出到日落的过渡视频"

处理：

{
  prompt: "日出东方到日落西山的时间流逝，云彩变化，光线渐变",
  duration: 10,
  reference_images: ["https://start.jpg", "https://end.jpg"],
  model: "doubao-seedance-2-0"
}

场景 4: 参考音频生视频

用户输入： "[发了一段音乐] 用这首曲子生成一个配合音乐节奏的光影视频"

处理：

{
  prompt: "配合音乐节奏变化的抽象光影艺术视频",
  duration: 10,
  reference_audio: "https://...mp3",
  model: "doubao-seedance-2-0"
}

场景 5: 低成本离线生成

用户输入： "用低成本模式生成一个城市夜景延时视频，不着急，慢慢生成"

处理：

{
  prompt: "繁华都市的夜景延时摄影，车水马龙，灯光璀璨",
  duration: 10,
  service_tier: "flex",
  model: "doubao-seedance-1-5-pro"
}

📤 返回结果格式

{
  "success": true,
  "task_id": "cgt-20260427xxxxxx-xxxx",
  "message": "视频生成任务已提交，预计3-5分钟完成，完成后会自动通知您",
  "estimated_time": "3-5分钟",
  "error": null
}

任务管理命令

📥 文件保存位置

视频自动保存到：~/Desktop/Seedance-Videos/

⚠️ MVP 版本说明：为防止轮询进程阻塞和数据库死锁，暂不自动下载视频到本地。用户可直接点击链接在线查看或手动保存。

❌ 错误处理

⚙️ 配置说明（一般不需要）

🔑 API Key（一般无需手动配置）

Agent Plan 专属版本 - 自动复用 Agent Plan 的 apiKey，无需单独配置生视频 API Key

💡 智能识别多种环境变量命名：ARK_API_KEY / ARK_APIKEY / ARK_KEY / DOUBAO_API_KEY / BYTEDANCE_ARK_API_KEY，只要语言模型配置了就能自动找到

📋 高级配置（一般不需要）

如需使用不同账号、自定义模型或更换 API 地址，可以通过以下环境变量覆盖：

# 方式一：全局配置（推荐，Seedream 可复用）
echo 'export ARK_API_KEY="ark-你的APIKey"' >> ~/.zshrc

# 方式二：Seedance 专属配置（如需要使用不同账号）
echo 'export ARK_SEEDANCE_API_KEY="ark-你的APIKey"' >> ~/.zshrc

source ~/.zshrc

🔄 Cron 配置（必须）

必须配置定时任务才能轮询状态和接收完成通知：

# 编辑 crontab
crontab -e

# 添加一行（注意修改为你的实际路径）
* * * * * /usr/local/bin/node ~/.agents/skills/byted-ark-seedance-skill/scripts/poll.js >> ~/.agents/skills/byted-ark-seedance-skill/poll.log 2>&1

详见 INSTALL.md。

🤖 Agent 开发指南

多模态文件预处理（Agent 层负责）

重要： 用户在对话中发送的图片、视频、音频文件，Agent 层必须先统一转换为公网可访问的 URL。

处理方式：

1. Agent 层从消息上下文中解析用户上传的文件
2. 将不同格式的文件统一转换为公网可访问的 HTTP URL
3. 将转换后的 URL 数组传入对应参数

支持的输入格式：

• HTTP/HTTPS URL
• Base64 编码格式
• 各平台提供的文件标识（由 Agent 层负责转换为 URL）

调用脚本方式

执行 scripts/generate.js，传入参数：

node scripts/generate.js \
  --prompt "用户的描述" \
  --duration 5 \
  --ratio "16:9" \
  --resolution 720p \
  --api-key "ark-xxx"   # Agent 层自动传入，无需用户配置

支持的原生 API 接口

本 Skill 调用 Agent Plan 原生视频生成接口，与语言模型共用服务入口。