seedance-video-local

star 219

用火山引擎 Ark 的 Seedance 2.0 系列做视频生成（文本+参考图/视频/音频），支持提交任务、轮询状态、下载结果，默认 480p 控成本。

dracohu2025-cloud By dracohu2025-cloud schedule Updated 5/3/2026
play_arrow Run Skill in Manus View GitHub

name: seedance-video-local description: 用火山引擎 Ark 的 Seedance 2.0 系列做视频生成（文本+参考图/视频/音频），支持提交任务、轮询状态、下载结果，默认 480p 控成本。 version: 1.0.0 author: Hermes Agent license: MIT platforms: [linux, macos] metadata: hermes: tags: [volcengine, ark, seedance, video-generation, multimodal]

Seedance Video Local

当用户想要：

  • 调用火山引擎 Seedance 2.0 生成视频
  • 使用参考图/参考视频/参考音频做多模态控制
  • 在本机可复用一套“提交→轮询→下载”的稳定流程
  • 先低成本验证（默认 480p）

就用这个 skill。

默认策略（重要）

  • 默认 resolution=480p（控成本）
  • 默认 ratio=16:9
  • 默认 duration=5（更省）
  • 默认 watermark=false
  • 默认模型：doubao-seedance-2-0-260128
  • 默认 profile=stable（质量与自由度平衡）

Profile 选型速查

  • strict：交付优先，强约束，最稳；非 timeline 场景仅保留一个主镜头运动。
  • stable：默认档，稳定与表现力平衡；适合日常生产。
  • cinematic：风格优先，约束更松；非 timeline 场景可保留最多两个镜头指令。

批量模式可在每条 item 内单独覆盖 profile，用于同一批任务做 A/B 对比。

鉴权与环境变量

  • 脚本要求显式传入：--api-key
  • 推荐在 shell 中以变量方式传入：--api-key "$VOLCENGINE_API_KEY"
  • 可选环境变量：ARK_BASE_URL（默认 https://ark.cn-beijing.volces.com/api/v3）

脚本

  • scripts/seedance_video.py
  • scripts/seedance_prompt_generator.py
  • scripts/seedance_workflow.py
  • scripts/seedance_cost_estimator.py

A) 生成任务脚本：seedance_video.py

功能：

  • check：检查环境
  • preview：只打印请求 JSON，不发请求
  • submit：创建任务
  • get：查询任务状态
  • run：创建并轮询到结束（可选自动下载）
  • cancel：取消/删除任务

B) Prompt Generator：seedance_prompt_generator.py

用途：把自然语言视频需求按 Seedance 方法论结构化。

固定方法：

  • subject > action > camera > style > constraints

能力：

  • 识别时间分镜（如 2-4 秒：... / [0-4s]: ... / [0.0-0.8s] ... / [00:00-00:04] ...）
  • 识别分层标题并提取结构（如 Core Subject / Main Action / Action Sequence / Cinematography / Visual Style / 【角色】 / 【风格】）
  • 输出五层结构与最终 prompt，尽量避免 subject / action 重复
  • 遵循 Seedance Prompt Bible 的实战规则：非时间轴场景默认只保留一个主摄像机运动（避免冲突）
  • 自动修复退化关键词（如 fast、glow/glimmer/glints、单独 cinematic、lots of movement）
  • 自动补默认约束（防抖动、防形变、防闪烁等）
  • 支持 --profile strict|stable|cinematic 三档：
    • strict：交付优先，强约束，最稳
    • stable：默认档，质量与自由度平衡
    • cinematic：风格优先，约束更松

示例：

python3 scripts/seedance_prompt_generator.py \
  --brief '第一视角果茶广告，2-4 秒摇杯，4-6 秒成品特写，golden hour，避免抖动' \
  --profile stable \
  --json

C) 统一入口：seedance_workflow.py

用途：一条命令完成「需求结构化 -> 生成 prompt -> 提交/轮询 Seedance 任务」。

模式：

  • preview：只生成结构化结果与最终 payload（不扣费）
  • submit：生成并提交任务（默认）
  • run：生成、提交并轮询到结束（可选下载）

模板：

  • --template ./template.json 可给单条与批量任务提供默认参数（refs、duration、ratio、resolution 等）
  • 合并优先级：item 字段 > template 字段 > 命令行默认值（批量时）

注意：

  • seedance_workflow.py 默认 mode 是 submit，会真实发起任务并产生费用。
  • 强烈建议先跑 --mode preview 做结构化与 payload 校验，再提交。
  • 若用户明确要求“先看 prompt 再决定是否生成”（高成本场景常见），必须执行审批门：
    1. 先输出导演版 prompt（可含中文注释版）供 review；
    2. 未收到用户明确确认前，禁止 submit/run；
    3. 用户确认后再提交，且默认继续使用 480p 控成本。
  • 对“剧情型 prompt”（多段事件）必须做 beat 覆盖核对：提交前逐条核对关键事件是否都在 timeline 里（例如：开火→子弹充能→贴地飞行→击中爆裂→拉回人物→收枪离场），避免后半段语义丢失。

示例（推荐先 preview）：

python3 scripts/seedance_workflow.py \
  --mode preview \
  --brief '第一视角果茶广告，2-4 秒摇杯，4-6 秒成品特写，golden hour' \
  --ref-image-url 'https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg' \
  --json

正式提交：

python3 scripts/seedance_workflow.py \
  --mode submit \
  --api-key "$VOLCENGINE_API_KEY" \
  --brief '第一视角果茶广告，2-4 秒摇杯，4-6 秒成品特写，golden hour' \
  --ref-image-url 'https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg' \
  --ref-video-url 'https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4' \
  --generate-audio \
  --duration 11 \
  --json

D) 成本统计模块：seedance_cost_estimator.py

依据（与你给的图一致）：

  • tokens = (宽 * 高 * 帧率 * 时长) / 1024 * 条数
  • 单价：¥0.046 / 1000 tokens

说明：

  • seedance_workflow.py 已内置成本估算输出到 cost_estimate
  • 同时输出人类可读摘要：单条结果 cost_summary_human（示例：预计 ¥x.xx / 条，本次合计 ¥y.yy）
  • 批量结果 summary 里额外包含：estimated_video_count 与 cost_summary_human（示例：预计 ¥x.xx / 条，批量总计 ¥y.yy）
  • 终端非 JSON 模式会直接打印 cost_summary: ...，方便快速看预算
  • 默认参数：fps=24、video_count=1、token_price_cny_per_1k=0.046
  • 可覆盖参数：--fps、--video-count、--token-price-cny-per-1k、--width、--height
  • --width/--height 不填时，会按 resolution + ratio 自动估算像素尺寸
  • 智能比例/智能时长模式下仅能估算，实际以最终结果为准

示例：

python3 scripts/seedance_workflow.py \
  --mode preview \
  --brief '第一视角果茶广告，2-4 秒：摇杯，4-6 秒：成品特写' \
  --resolution 480p \
  --ratio 16:9 \
  --duration 5 \
  --fps 24 \
  --video-count 1 \
  --json

批量模式（--auto-submit-from-file）：

说明：

  • 支持三种输入：JSON 数组、{"items": [...]}、JSONL（每行一个 JSON 对象）。
  • 每条 item 可覆盖全局参数，常用覆盖字段：
    • brief / brief_file
    • mode（preview/submit/run）
    • profile（strict/stable/cinematic）
    • resolution / ratio / duration / seed
    • fps / video_count / token_price_cny_per_1k
    • width / height
    • ref_image_url / ref_video_url / ref_audio_url
    • first_frame_url / last_frame_url
    • generate_audio / watermark / extra_json / download
  • 批量模式退出码：有失败项时返回非 0；可配 --continue-on-error 继续后续任务。

方案1：不使用 template（每条自己带参数）

[
  {
    "brief": "第一视角果茶广告，2-4 秒：摇杯，4-6 秒：成品特写",
    "ref_image_url": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"],
    "duration": 6
  },
  {
    "brief": "第一视角举杯递给镜头，golden hour",
    "ref_video_url": ["https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"],
    "resolution": "720p"
  }
]

方案2：使用 template（推荐，batch 里只写 brief）

template.json（常用默认参数）：

{
  "ref_image_url": ["https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg"],
  "ref_video_url": ["https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4"],
  "ratio": "16:9",
  "duration": 8,
  "resolution": "480p",
  "generate_audio": true
}

batch.json（只保留差异）：

[
  {"brief": "第一视角果茶广告，2-4 秒：摇杯，4-6 秒：成品特写"},
  {"brief": "第一视角举杯递给镜头，golden hour", "duration": 11}
]

合并优先级：

  • 批量 item 字段 > template 字段 > 命令行默认值
  1. 先批量 preview（零成本）：
python3 scripts/seedance_workflow.py \
  --mode preview \
  --auto-submit-from-file ./batch.json \
  --template ./template.json \
  --batch-output ./batch.preview.result.json \
  --json
  1. 批量 submit（真实提交，可选遇错继续）：
python3 scripts/seedance_workflow.py \
  --mode submit \
  --api-key "$VOLCENGINE_API_KEY" \
  --auto-submit-from-file ./batch.json \
  --template ./template.json \
  --continue-on-error \
  --batch-output ./batch.submit.result.json \
  --json

Prompt Generator 方法要点（来自实测）

  • 五层顺序固定：subject > action > camera > style > constraints
  • 时间分镜优先：识别 2-4 秒：...、[0-4s]: ...、[00:00-00:04] ...、[0.8-1.6s] ...（小数秒）后，优先生成 time-coded prompt
  • 当需求包含“后半段关键剧情”（如子弹飞行→击中目标→爆裂→人物收枪离场）时，必须写成显式分镜时间线；不要只给长段叙述，否则模型易压缩后半段动作
  • 结构化标题优先：可直接写 Core Subject / Main Action / Action Sequence / Cinematography / Visual Style / Camera Settings / Quality，也支持 【角色】/【风格】/【场景】
  • 长句解析支持分号切分（；/;），可降低 subject 与 action 重复
  • 非 timeline 场景：strict/stable 默认单主镜头运动，cinematic 可保留最多两个镜头指令
  • 对退化词做自动修复：
    • fast → single fast element, keep all other elements steady
    • glow/glimmer/glints → steady intensity diffuse light
    • cinematic（单独）→ cinematic film tone, 35mm
    • lots of movement → one primary movement only
  • 默认约束建议始终注入：
    • avoid jitter
    • avoid bent limbs
    • avoid temporal flicker
    • maintain face consistency

Prompt Generator 回归测试

python3 scripts/test_seedance_prompt_generator.py
python3 scripts/test_seedance_workflow.py
python3 scripts/test_seedance_cost_estimator.py

如果你改了关键词映射/正则、成本公式参数、或统一入口编排，先跑这组测试再提交。

快速开始

1) 零成本预览（推荐）

python3 scripts/seedance_video.py preview \
  --prompt '第一视角果茶广告，首尾帧清晰，节奏轻快' \
  --ref-image-url 'https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg' \
  --ref-image-url 'https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg' \
  --ref-video-url 'https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4' \
  --ref-audio-url 'https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3' \
  --generate-audio

2) 提交并轮询

python3 scripts/seedance_video.py run \
  --api-key "$VOLCENGINE_API_KEY" \
  --prompt '第一视角果茶广告，镜头从摘果到成品递杯' \
  --ref-image-url 'https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg' \
  --ref-image-url 'https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic2.jpg' \
  --ref-video-url 'https://ark-project.tos-cn-beijing.volces.com/doc_video/r2v_tea_video1.mp4' \
  --ref-audio-url 'https://ark-project.tos-cn-beijing.volces.com/doc_audio/r2v_tea_audio1.mp3' \
  --generate-audio \
  --duration 11 \
  --download ./outputs/seedance_ad.mp4

3) 查询已有任务

python3 scripts/seedance_video.py get \
  --api-key "$VOLCENGINE_API_KEY" \
  --task-id cgt-xxxx

参考 API 路径

  • 创建：POST /contents/generations/tasks
  • 查询：GET /contents/generations/tasks/{id}
  • 取消/删除：DELETE /contents/generations/tasks/{id}

结果说明

  • 成功状态：succeeded
  • 运行中状态：queued / running
  • 失败状态：failed / expired / cancelled
  • 成功后关注：content.video_url（通常有时效，建议立刻下载）

常见坑

  1. 401/403：API Key 不对或没生效。
  2. 参考资源 URL 必须公网可访问。
  3. first_frame/last_frame 不能与 reference_image/reference_video/reference_audio 混用；会报 InvalidParameter。
  4. 分辨率、时长越高，成本越高；先用 480p+短时长确认可行再提档。
  5. 运行中的任务无法删除（InvalidAction.RunningTaskDeletion）；通常只支持取消排队中的任务。
  6. 任务状态轮询若看不到实时日志，优先用 python3 -u .../seedance_video.py run（unbuffered）或直接 get 查询 task_id。

交付建议（飞书）

生成完成后，建议立刻上传飞书云盘并返回可打开链接：

  1. lark-cli drive +upload 上传 mp4（注意 --file 必须是当前目录相对路径）
  2. 用 drive metas batch_query 通过 file_token 取 url
  3. 回复用户该 https://*.feishu.cn/file/<token> 链接

这一步建议作为默认交付收尾，避免只给本地路径。

Install via CLI
npx skills add https://github.com/dracohu2025-cloud/draco-skills-collection --skill seedance-video-local
Repository Details
star Stars 219
call_split Forks 37
navigation Branch main
article Path SKILL.md
More from Creator
dracohu2025-cloud
dracohu2025-cloud Explore all skills →