Back to Details

vfx

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

vfx

VFX处理

Maps a video-to-video VFX move onto the Pika MCP's Seedance reference-to-video, at 1080p by default (bump to 4K, or drop to 720p, only if the user asks). The user hands you a clip + the change they want; you read EVERY frame (locally extracted with ffmpeg and tiled into contact sheets) and understand the audio (speech + music + SFX + ambience), author a Seedance-faithful prompt that locks the original (face, gestures, camera move) and time-codes the change to the right beat, then re-render the same shot with the VFX baked in. One run produces one clip for one requested change.
For a 4K-only version of this skill with no resolution choice, see 
/pika:4k-vfx
.
将视频转视频VFX效果映射到Pika MCP的Seedance reference-to-video功能上，默认分辨率为1080p（仅在用户要求时提升至4K或降至720p）。用户提供一段视频片段及想要的修改效果；你需要读取每一帧画面（通过ffmpeg本地提取并拼接成联络图），并理解音频内容（语音、音乐、音效及环境音），编写符合Seedance规范的提示词，锁定原视频中的（面部、手势、镜头运动），并将修改效果按时间码对齐到合适的节拍，随后重新渲染同一镜头并内置VFX效果。每次运行仅针对一项请求修改生成一个视频片段。
如需仅支持4K分辨率且无分辨率选项的版本，请查看
/pika:4k-vfx
。

How it works — why reading EVERY frame (and the audio) is the mechanism (do not skip the reading pass)

工作原理——为何必须读取每一帧（及音频）（不可跳过读取步骤）

Seedance treats the reference video as a motion/style anchor, NOT a pixel-locked base — it does not copy the input frame-for-frame, it re-generates the shot guided by your prompt. So fidelity comes from the PROMPT: the more exhaustively the prompt describes the original (subject identity, exact gestures, camera move, framing, lighting, palette, wardrobe) and the audio (dialogue + lip-sync, music/SFX beats), the more the output reads as the same shot with the change layered on, at any resolution. Reading EVERY frame — not a sample — is how you build that exhaustive description: you locally extract all frames with ffmpeg, tile them 25-to-a-contact-sheet (5×5), and analyze every sheet so the prompt is built from the entire timeline rather than a handful of stills. Skip the read (or read only a sample) and the output drifts — a different face, a different camera move, a different room, a missed motion beat. The reading pass — all frames + the audio — IS the skill.
Seedance将参考视频视为运动/风格锚点，而非像素锁定的基础素材——它不会逐帧复制输入内容，而是根据提示词重新生成镜头。因此，还原度取决于提示词：提示词越详尽地描述原视频（主体身份、精确手势、镜头运动、构图、光线、色调、服饰）及音频内容（对话与唇同步、音乐/音效节拍），输出视频就越能呈现为“在原镜头基础上叠加修改效果”的效果，且适用于任何分辨率。读取每一帧而非抽样读取是构建详尽描述的关键：你需要通过本地ffmpeg提取所有帧，将每25帧拼接成一张联络图（5×5网格），并分析每张联络图，确保提示词基于完整时间线而非少量静态帧。跳过读取步骤（或仅抽样读取）会导致输出内容偏移——比如面部不同、镜头运动改变、场景变化、错过运动节拍。读取步骤（所有帧+音频）正是本技能的核心。

Prerequisites

前置条件

pika MCP available, and local 
ffmpeg
 in the run environment (used to extract every frame and build the contact sheets). Two inputs from the user: (1) a video clip (a local file or a public URL) and (2) the VFX change they want made to it. A third input is optional: (3) a resolution — defaults to 1080p if not specified. Tools used: 
upload_asset
, 
probe_media
, 
analyze_media
, 
transcribe_audio
, 
estimate_cost
, 
generate_reference_video
, 
task_status
(frame extraction + tiling is done locally with ffmpeg, not an MCP tool).
需具备Pika MCP，且运行环境中装有本地
ffmpeg
（用于提取所有帧并生成联络图）。需要用户提供两个输入：(1) 视频片段（本地文件或公共URL）和**(2) 想要的VFX修改效果**。第三个输入为可选：(3) 分辨率——未指定时默认1080p。使用的工具包括：
upload_asset
、
probe_media
、
analyze_media
、
transcribe_audio
、
estimate_cost
、
generate_reference_video
、
task_status
（帧提取与拼接通过本地ffmpeg完成，而非MCP工具）。

Stage 0 — Gather inputs (settle this first)

阶段0 — 收集输入（优先完成）

You need exactly two things before generating, plus one implicit default:
  1. The video — the original clip to transform. If they gave a local file, you will upload it (Step 1); if they gave a public URL, keep it.
  2. The change / VFX — what should be different in the output (e.g. "turn the plaza into an open desert on a finger snap", "make it snow", "set the room on fire behind me", "morph my jacket into glowing armor").
  3. The resolution (
    state.resolution
    )     — default to 
    1080p
     unless the user's request says otherwise. Look for explicit signals: "4K", "highest quality", "max resolution" → 
    state.resolution = "4k"
    ; "720p", "cheaper", "faster", "lower res is fine" → 
    state.resolution = "720p"
    . Absent any signal, stay at 
    1080p
    — do not ask "which resolution do you want?", just default silently and let the Step-6 gate surface the choice for confirmation. Set 
    state.seedance_model
    from 
    state.resolution
    right away, since Step 6 quotes it: 
    standard
     for 
    1080p
    or 
    4k
    (
    fast
    /
    mini
    cap at 720p — REQUIRED), 
    fast
     for 
    720p
    (cheaper, faster, and sufficient at that resolution).
If either video or change is missing, ask for it before doing anything else — do not invent a change, and do not proceed on a clip you cannot reach. Once both are in hand, say in one line what you're about to do ("Reading every frame of your clip to build the desert-on-snap 1080p prompt…") and run Steps 1–5 without further check-ins — but stop at the Step 6 agreement gate before generating: the render is the expensive, irreversible step, and it only fires after the user approves the prompt, resolution, and cost.
生成前你需要确切获取两项内容，外加一项默认设置：
  1. 视频——待转换的原片段。若用户提供本地文件，你需上传（步骤1）；若提供公共URL，直接使用即可。
  2. 修改效果/VFX——输出视频中需要改变的内容（例如：“打响指时将广场变为开阔沙漠”、“添加下雪效果”、“在我身后点燃房间”、“将我的夹克变形为发光盔甲”）。
  3. 分辨率（
    state.resolution
    ）    ——默认设置为**
    1080p
    ，除非用户明确要求其他分辨率。需留意明确信号：“4K”、“最高画质”、“最大分辨率”→
    state.resolution = "4k"
    ；“720p”、“更便宜”、“更快”、“低分辨率即可”→
    state.resolution = "720p"
    。若无任何信号，保持1080p——无需询问“你想要哪种分辨率？”，直接默认设置，后续步骤6的确认环节会让用户看到该选项。立即根据
    state.resolution
    设置
    state.seedance_model
    ，因为步骤6会引用该参数：
    standard
    适用于1080p或4K（
    fast
    /
    mini
    最高仅支持720p——必须遵守），
    fast
    **适用于720p（成本更低、速度更快，且在该分辨率下效果足够）。
若视频或修改效果缺失，在进行任何操作前先向用户索要——不要自行编造修改效果，也不要处理无法获取的视频片段。获取两项内容后，用一句话告知用户你即将执行的操作（例如：“正在读取你的视频每一帧，以构建打响指变沙漠的1080p提示词……”），然后无需进一步确认即可执行步骤1-5，但在执行步骤7生成前必须停在步骤6的确认环节：渲染是成本高昂且不可逆转的步骤，仅在用户确认提示词、分辨率及成本后才可执行。

Step 1 — Upload the clip (
upload_asset
)

步骤1 — 上传视频片段（
upload_asset
）

Real video must be uploaded — inline base64 only works for tiny assets (<~3MB), so any actual clip goes through the presigned-upload path.
  1. Call 
    upload_asset
    with 
    filename
    , 
    mime_type
    (
    video/mp4
    for mp4), and 
    size_bytes
    (the file's byte size).
  2. PUT the raw bytes to the returned 
    presigned_url
    .
  3. Keep the returned 
    public_url
    → 
    state.clip_url
    .
If the user already gave a public URL, skip this step and set 
state.clip_url
to it.
真实视频必须上传——内嵌base64仅适用于极小素材（<约3MB），因此任何实际视频片段都需通过预签名上传路径上传。
  1. 调用
    upload_asset
    ，传入
    filename
    、
    mime_type
    （MP4格式为
    video/mp4
    ）和
    size_bytes
    （文件字节大小）。
  2. 将原始字节数据PUT到返回的
    presigned_url
    。
  3. 保存返回的
    public_url
    →
    state.clip_url
    。
若用户已提供公共URL，跳过此步骤，直接将
state.clip_url
设为该URL。

Step 2 — Probe (
probe_media
)

步骤2 — 探测媒体信息（
probe_media
）

Call 
probe_media
on 
state.clip_url
to read duration, fps, dimensions, and aspect ratio. Use these to: (a) sanity-check the all-frame extraction in Step 3 (duration × fps ≈ total frame count ≈ 25 × number of sheets), and (b) choose the output 
aspect_ratio
and 
duration
here, matched to the source — the Step-6 gate quotes this choice (plus 
state.resolution
from Stage 0) to the user and Step 7 fires with it.
调用
probe_media
读取
state.clip_url
的时长、帧率、尺寸及宽高比。这些信息用于：(a) 验证步骤3中全帧提取的合理性（时长×帧率≈总帧数≈25×联络图数量），(b) 在此处选择与源视频匹配的输出
aspect_ratio
和
duration
——步骤6的确认环节会向用户展示该选择（外加阶段0的
state.resolution
），步骤7将以此执行。

Step 3 — Extract EVERY frame locally and tile into contact sheets (ffmpeg)

步骤3 — 本地提取所有帧并拼接成联络图（ffmpeg）

Read the whole video, not a sample. Use local ffmpeg to extract every frame at the source rate (no drops, no exceptions), then tile them into legible contact sheets at 25 frames per sheet (5×5 grid) so each 
analyze_media
call covers 25 consecutive frames at once.
Work in a relative working directory (do not use an absolute system temp path):
mkdir -p frames sheets
ffmpeg -i INPUT -vsync 0 frames/f_%05d.png            # every frame, no drops
Then build the 25-per-sheet contact sheets (5×5), scaling each frame down so the sheet is legible and stamping the frame index onto each tile:
ffmpeg -i INPUT -vf "scale=480:-1,drawtext=text='%{n}':x=4:y=4:fontsize=20:fontcolor=yellow:box=1:boxcolor=black@0.5,tile=5x5" sheets/sheet_%03d.png
drawtext=text='%{n}'
stamps the frame index on each tile so the analysis can reference exact frames; 
tile=5x5
groups 25 consecutive frames per sheet. If 
drawtext
is unavailable in the local ffmpeg build, fall back to plain 
scale=480:-1,tile=5x5
. 
INPUT
is the local clip (or a local copy of the URL). Confirm the sheet count lines up with the probe in Step 2 — every frame must land on a sheet, no exceptions.
读取完整视频，而非抽样读取。使用本地ffmpeg按源帧率提取每一帧（无遗漏、无例外），然后将每25帧拼接成一张清晰的联络图（5×5网格），以便每次
analyze_media
调用可一次性分析25帧连续画面。
在相对工作目录中操作（不要使用绝对系统临时路径）：
mkdir -p frames sheets
ffmpeg -i INPUT -vsync 0 frames/f_%05d.png            # 提取每一帧，无遗漏
然后构建每25帧一张的联络图（5×5），缩小每帧画面尺寸以保证联络图清晰，并在每个帧块上标记帧索引：
ffmpeg -i INPUT -vf "scale=480:-1,drawtext=text='%{n}':x=4:y=4:fontsize=20:fontcolor=yellow:box=1:boxcolor=black@0.5,tile=5x5" sheets/sheet_%03d.png
drawtext=text='%{n}'
会在每个帧块上标记帧索引，以便分析时可引用精确帧；
tile=5x5
将25帧连续画面分组为一张联络图。若本地ffmpeg版本不支持
drawtext
，则退化为仅使用
scale=480:-1,tile=5x5
。
INPUT
为本地视频片段（或URL的本地副本）。确认联络图数量与步骤2的探测结果一致——每一帧都必须包含在某张联络图中，无例外。

Step 4 — Read EVERY sheet + understand the audio (
upload_asset
, 
analyze_media
, 
transcribe_audio
)

步骤4 — 读取所有联络图+理解音频（
upload_asset
、
analyze_media
、
transcribe_audio
）

This is the fidelity step, and it has two mandatory halves: read all the frames and understand the audio. Neither is optional.
这是保证还原度的步骤，包含两个必备部分：读取所有帧和理解音频。两者缺一不可。

4a — Read all the frames (every sheet)

4a — 读取所有帧（每张联络图）

For each contact sheet from Step 3 (cover ALL of them — every frame is on a sheet, no exceptions): upload it with 
upload_asset
(the sheets are images, so upload to get a URL), then call 
analyze_media
on that sheet URL with a 
query
that reads the full progression across those 25 frames — pulling out everything the prompt must lock:
  • Subject / identity — who/what is in frame; face, hair, build, distinguishing features.
  • Exact motion & gestures — what the subject does, beat by beat, referencing the stamped frame indices (e.g. "raises right hand around frame 0048, snaps fingers around frame 0072").
  • Camera move — static / pan / push-in / handheld / orbit, and its timing.
  • Framing — shot size (close/medium/wide), subject position, headroom.
  • Lighting — direction, hardness, color temperature, time of day.
  • Palette — dominant colors, mood.
  • Wardrobe / props / setting — clothing, objects, background.
Carry the read across all sheets so the entire timeline is understood start-to-end, not just a sampled middle.
针对步骤3生成的每张联络图（覆盖全部——每一帧都在联络图中，无例外）：使用
upload_asset
上传（联络图为图片，需上传以获取URL），然后调用
analyze_media
分析该联络图URL，
query
需读取这25帧的完整变化过程——提取提示词必须锁定的所有信息：
  • 主体/身份——画面中的人/物；面部、发型、体型、显著特征。
  • 精确动作与手势——主体的动作，逐节拍描述，引用标记的帧索引（例如：“约第0048帧抬起右手，约第0072帧打响指”）。
  • 镜头运动——静态/摇移/推近/手持/环绕，及其时机。
  • 构图——镜头景别（近景/中景/全景）、主体位置、头部空间。
  • 光线——方向、硬度、色温、时段。
  • 色调——主导色彩、氛围。
  • 服饰/道具/场景——服装、物品、背景。
需覆盖所有联络图，确保理解完整时间线的首尾内容，而非仅抽样分析中间部分。

4b — Understand the audio (mandatory, not just speech)

4b — 理解音频（必备，而非仅语音）

Always read the audio — it is required, not optional. Two passes:
  • transcribe_audio
    for speech + timestamps (the words and when they're said), so the prompt can preserve dialogue and lip-sync beats.
  • analyze_media
    on the audio (or the video URL) to understand the NON-speech audio too — music, sound effects, ambience, tone, and rhythm/beats.
Fold the audio understanding into the prompt where it matters — preserve dialogue + lip-sync if anyone speaks, and time the VFX change to an audio beat / sound cue when the change should land on the music or a sound (e.g. snap, hit, downbeat) rather than a bare timestamp.
Assemble the all-frame read and the audio read into a single faithful description of the original — that description is the raw material for Step 5.
必须读取音频内容——这是必备步骤，而非可选。需执行两次分析：
  • transcribe_audio
    用于提取语音+时间戳（内容及发声时机），以便提示词可保留对话及唇同步节拍。
  • 在音频（或视频URL）上调用
    analyze_media
    ，以理解非语音音频内容——音乐、音效、环境音、音调及节奏/节拍。
将音频理解融入提示词的关键位置——若有人物对话则保留对话及唇同步，且当修改效果需与音乐或音效（如响指、撞击、重拍）同步时，将VFX修改效果的时间码对齐到音频节拍/音效提示，而非仅使用裸时间戳。
将全帧读取结果及音频读取结果整合为对原视频的完整描述——该描述是步骤5的素材。

Step 5 — Write the Seedance prompt (the authoring step, NEVER skip it)

步骤5 — 编写Seedance提示词（创作步骤，绝不可跳过）

Compose ONE prompt = a faithful, exhaustive description of the original (the locked elements) + the user's requested change, time-coded + a reference to the input clip via the 
@Video1
 token. Be thorough: every detail you read in Step 4 that you omit is a detail Seedance is free to change.
Template — fill the 
[SLOTS]
from your Step-4 read (
[RESOLUTION LABEL]
= 
4K
/ 
1080p
/ 
720p
matching 
state.resolution
):
Re-render this exact shot @Video1 in cinematic [RESOLUTION LABEL]. LOCK the original: [SUBJECT/IDENTITY — face, hair, build, wardrobe], performing [EXACT GESTURES, beat by beat]. Keep the SAME camera move ([CAMERA: static / pan / push-in / handheld], [timing]), the SAME framing ([SHOT SIZE + subject position]), the SAME lighting ([direction, hardness, color temp, time of day]) and the SAME palette ([dominant colors / mood]). CHANGE: [the VFX], time-coded — at [t0]–[t1]s [what the scene looks like before the change], then at [t2]s [the change triggers / VFX appears] and [how the scene reads after]. Everything not described by the change stays identical to @Video1. Photorealistic, high detail, consistent identity throughout.
Time-code the change so Seedance knows when it happens relative to the locked motion (e.g. "at 0–3s the plaza is unchanged as the subject raises their hand; at 3s on the finger snap the plaza dissolves into an open desert, sand and heat-haze replacing the buildings while the subject, camera move, and framing stay identical"). The stronger and more specific the time-coded change clause, the less Seedance ignores it.
编写一个提示词 = 对原视频的完整详尽描述（锁定元素）+ 用户要求的修改效果（带时间码） + 通过**
@Video1
**标记引用输入视频。需详尽：步骤4中读取的任何细节若未在提示词中提及，Seedance都可能对其进行修改。
模板——根据步骤4的读取结果填充
[占位符]
（
[分辨率标签]
= 与
state.resolution
匹配的
4K
/
1080p
/
720p
）：
以电影级[分辨率标签]重新渲染此精确镜头@Video1。锁定原视频元素：[主体/身份——面部、发型、体型、服饰]，做出[精确手势，逐节拍描述]。保持相同镜头运动（[镜头类型：静态/摇移/推近/手持]，[时机]）、相同构图（[景别 + 主体位置]）、相同光线（[方向、硬度、色温、时段]）及相同色调（[主导色彩/氛围]）。修改：[VFX效果]，带时间码——[t0]–[t1]秒时[修改前场景状态]，然后在[t2]秒时[修改触发/VFX出现]，且[修改后场景状态]。未被修改描述覆盖的所有内容需与@Video1完全一致。写实风格，高细节，全程身份一致。
为修改效果添加时间码，让Seedance知道修改在锁定运动中的触发时机（例如：“0–3秒时广场保持不变，主体抬起右手；3秒打响指时广场溶解为开阔沙漠，沙子和热浪取代建筑，同时主体、镜头运动及构图保持不变”）。时间码修改条款越明确具体，Seedance忽略该修改的可能性就越小。

Step 6 — Agreement gate (
estimate_cost
) — MANDATORY before generating

步骤6 — 确认环节（
estimate_cost
）——生成前必须执行

The render is the expensive step, and once fired it can't be un-spent. Never call 
generate_reference_video
without explicit user approval in this session. Present, in one message:
  1. The full Step-5 prompt — verbatim, so the user can catch a wrong detail (face, gesture, timing) before it costs money.
  2. The generation recipe — provider 
    seedance
    , model 
    state.seedance_model
    , resolution 
    state.resolution
    (state plainly that this is 
    1080p
    unless the user asked for something else), plus the 
    aspect_ratio
    and 
    duration
    you chose from the Step-2 probe.
  3. The estimated cost — call 
    estimate_cost
    for the Step-7 
    generate_reference_video
    call and quote the result. If the estimate errors, say the cost is unknown and flag that 4K is the top-price tier if that's what's selected — do not silently skip the number.
Then wait. Three outcomes:
  • Approve → proceed to Step 7 unchanged.
  • Revise — the user corrects a detail, the change clause, or the resolution → update the Step-5 prompt (re-reading specific sheets if the correction demands it) and re-present the gate.
  • Abort / no answer → do not generate. Never treat silence as approval.
Only skip this gate if the user explicitly pre-authorized the spend in this session ("just run it, don't ask", a standing instruction to render without confirmation). Having provided the clip and the change is NOT pre-authorization — that's just Stage 0 input.
渲染是成本高昂的步骤，一旦执行便无法撤销。在本次会话中，未经用户明确批准绝不可调用
generate_reference_video
。需在一条消息中展示以下内容：
  1. 步骤5的完整提示词——原文展示，以便用户在产生成本前发现错误细节（面部、手势、时机）。
  2. 生成配置——服务商
    seedance
    、模型
    state.seedance_model
    、分辨率
    state.resolution
    （明确说明默认1080p，除非用户要求其他分辨率），以及步骤2探测得到的
    aspect_ratio
    和
    duration
    。
  3. 预估成本——调用
    estimate_cost
    获取步骤7
    generate_reference_video
    调用的成本并告知用户。若预估出错，说明成本未知，并标记若选择4K则为最高价格 tier——不可跳过成本说明。
然后等待用户回应。有三种结果：
  • 批准→直接执行步骤7。
  • 修改——用户修正细节、修改条款或分辨率→更新步骤5的提示词（若修正需要，重新读取特定联络图），然后重新展示确认环节。
  • 中止/无回应→不生成视频。绝不可将沉默视为批准。
仅当用户在本次会话中明确预先授权消费（例如：“直接运行，不要询问”、“无需确认直接渲染”的长期指令）时，才可跳过此环节。提供视频片段和修改效果并不等同于预先授权——这只是阶段0的输入。

Step 7 — Generate (Seedance reference-to-video) (
generate_reference_video
)

步骤7 — 生成视频（Seedance参考视频转视频）（
generate_reference_video
）

Call 
generate_reference_video
with the recipe matched to 
state.resolution
:
  • provider
    : 
    seedance
  • seedance_model
    : 
    state.seedance_model
     — set back in Stage 0 (
    standard
    for 
    1080p
    /
    4k
    , REQUIRED since 
    fast
    /
    mini
    cap at 720p; 
    fast
    for 
    720p
    ).
  • resolution
    : 
    state.resolution
     — 
    1080p
    unless Stage 0 / the Step-6 gate settled on 
    4k
    or 
    720p
    .
  • reference_videos
    : 
    [state.clip_url]
     — the original footage as the motion/style anchor (Seedance accepts up to 3 videos).
  • reference_images
    : optional — style/creature/identity anchors (e.g. a generated reference image), only if you have one.
  • prompt
    : the Step-5 prompt (uses the 
    @Video1
     token to reference the input clip; no max length, so be exhaustive).
  • aspect_ratio
    : 
    auto
     (or match the source from Step 2).
  • duration
    : matched to the source, OR set 
    auto_duration
    : 
    true
    .
Do NOT pass 
negative_prompt
 (not supported on seedance — the call is rejected) and do NOT pass any fps param (it doesn't exist).
调用
generate_reference_video
，配置与
state.resolution
匹配：
  • provider
    : 
    seedance
  • seedance_model
    : 
    state.seedance_model
    ——阶段0已设置（1080p/4K使用
    standard
    ，必须遵守，因为
    fast
    /
    mini
    最高仅支持720p；720p使用
    fast
    ）。
  • resolution
    : 
    state.resolution
    ——默认1080p，除非阶段0/步骤6确认环节确定为4K或720p。
  • reference_videos
    : 
    [state.clip_url]
    ——原视频作为运动/风格锚点（Seedance最多支持3个视频）。
  • reference_images
    : 可选——风格/生物/身份锚点（例如生成的参考图），仅当你有相关素材时使用。
  • prompt
    : 步骤5的提示词（使用**
    @Video1
    **标记引用输入视频；无长度限制，需详尽）。
  • aspect_ratio
    : 
    auto
    （或匹配步骤2的源视频设置）。
  • duration
    : 匹配源视频，或设置
    auto_duration
    : 
    true
    。
请勿传入
negative_prompt
（Seedance不支持——调用会被拒绝），且请勿传入任何fps参数（该参数不存在）。

Step 8 — Deliver

步骤8 — 交付

If the call returns inline, you have the video URL. If it returns 
{ task_id, status: running/background }
, poll 
task_status(task_id)
in a tight loop until 
completed
/ 
failed
/ 
cancelled
. On completion, return the video URL to the user. Note: the output CDN may be egress-blocked for in-session download — so deliver the URL itself rather than trying to fetch the bytes locally.
若调用返回内嵌视频，你将获得视频URL。若返回
{ task_id, status: running/background }
，则循环调用
task_status(task_id)
直到状态变为
completed
/
failed
/
cancelled
。完成后，将视频URL返回给用户。注意：输出CDN可能对会话内下载进行出口限制——因此直接交付URL即可，无需尝试本地获取字节数据。

Failure modes

故障排查

symptomcause → fix
Clip too long / too largeUpload still works for large files; if Seedance rejects on duration, trim the source to the segment that matters, or set 
auto_duration: true
and match a shorter 
duration
.
No face / subject found in the readA sheet may not show the subject clearly — re-run 
analyze_media
on the specific sheet(s) covering the frames where the subject is visible (use the stamped frame indices), or rebuild the sheets without downscaling so detail is preserved. Do NOT drop to a sampled extraction — every frame stays on a sheet.
ffmpeg missing / 
drawtext
unavailable		The run environment needs local 
ffmpeg
; if the build lacks the 
drawtext
filter, fall back to plain 
scale=480:-1,tile=5x5
(sheets without stamped indices — still read every frame).
Identity / shot drift (different face, room, or camera move in the output)The prompt description was not exhaustive enough. Go back to Step 4–5 and add the missing locked details (more on face, gestures, camera move, lighting) from the contact-sheet read — Seedance only preserves what the prompt names. Re-render = new spend: re-pass the Step-6 gate with the revised prompt before firing again.
Requested resolution rejected / output downgraded
seedance_model
must be 
standard
for 
1080p
or 
4k
— 
fast
/
mini
silently cap at 720p. If the wrong-param call already completed (and was charged), the corrected call is a second render — re-pass the Step-6 gate before re-firing; if the call was rejected outright (nothing charged), re-fire the corrected call under the original approval.
Speech / audio not preserved or change off-beatRun BOTH 
transcribe_audio
(speech + timing) and 
analyze_media
on the audio (music/SFX/ambience), then describe the dialogue + lip-movement beats and pin the time-coded change to the right audio cue/beat in the prompt so the re-render stays in sync.
Seedance ignores the requested changeStrengthen the time-coded change clause in Step 5 — make it more specific and explicitly time-anchored ("at Ns the change triggers"). The revised prompt is a new, never-approved prompt and the re-render is new spend: re-pass the Step-6 gate before firing again.
Job fails after a long runIf it ran several minutes before failing, the content already cleared the safety pass — the failure is infrastructural; re-fire the same call (the user's Step-6 approval covers retrying the identical, already-approved call — no need to re-gate).
症状原因→修复方案
视频过长/过大大文件仍可正常上传；若Seedance因时长拒绝处理，则将源视频裁剪至关键片段，或设置
auto_duration: true
并匹配更短的
duration
参数。
读取时未检测到面部/主体某张联络图可能未清晰展示主体——重新对覆盖主体可见帧的特定联络图调用
analyze_media
（使用标记的帧索引），或不缩小帧尺寸重建联络图以保留细节。请勿改为抽样提取——每一帧都必须包含在联络图中。
ffmpeg缺失/
drawtext
不可用		运行环境需装有本地ffmpeg；若版本不支持
drawtext
滤镜，则退化为仅使用
scale=480:-1,tile=5x5
（联络图无帧索引标记——仍需读取每一帧）。
身份/镜头偏移（输出视频中面部、场景或镜头运动不同）提示词描述不够详尽。返回步骤4-5，从联络图读取结果中添加缺失的锁定细节（更多关于面部、手势、镜头运动、光线的描述）——Seedance仅保留提示词中明确提及的内容。重新渲染会产生新成本：重新执行步骤6确认环节，获得批准后再重新生成。
请求的分辨率被拒绝/输出分辨率降级1080p或4K必须使用
seedance_model
为
standard
——
fast
/
mini
会自动将分辨率限制为720p。若错误参数调用已完成（且已扣费），修正后的调用为第二次渲染——需重新执行步骤6确认环节后再生成；若调用被直接拒绝（未扣费），则在原批准下重新发起修正后的调用。
语音/音频未保留或修改效果节拍错位同时运行
transcribe_audio
（语音+时间戳）和对音频调用
analyze_media
（音乐/音效/环境音），然后在提示词中描述对话+唇动节拍，并将带时间码的修改效果绑定到正确的音频提示/节拍，确保重新渲染的内容保持同步。
Seedance忽略请求的修改效果强化步骤5中的时间码修改条款——使其更具体并明确时间锚点（“在N秒时触发修改”）。修改后的提示词为新的未批准提示词，重新渲染会产生新成本：重新执行步骤6确认环节后再生成。
任务长时间运行后失败若运行数分钟后失败，说明内容已通过安全审核——故障为基础设施问题；重新发起相同调用（用户步骤6的批准涵盖重新尝试已批准的相同调用——无需重新确认）。

One-liner recap

一句话总结

Extract EVERY frame locally with ffmpeg → tile into 25-per-sheet (5×5) contact sheets and analyze every sheet → understand the audio (transcribe speech + analyze music/SFX/ambience) → write an exhaustive Seedance-faithful prompt that locks the original and time-codes the change to the right audio beat → agreement gate: show the prompt + recipe (resolution 1080p by default, 4K/720p on request) + 
estimate_cost
and wait for approval → re-render the same shot via 
generate_reference_video
(
seedance
, model matched to resolution, original as 
reference_videos
, 
@Video1
in the prompt, no 
negative_prompt
).
通过本地ffmpeg提取所有帧→拼接成每25帧一张（5×5）的联络图并分析每张图→理解音频内容（转录语音+分析音乐/音效/环境音）→编写符合Seedance规范的详尽提示词，锁定原视频元素并将修改效果按时间码对齐到正确音频节拍→确认环节：展示提示词+配置（默认1080p，按需支持4K/720p）+
estimate_cost
并等待批准→通过
generate_reference_video
重新渲染同一镜头（服务商
seedance
，模型匹配分辨率，原视频作为
reference_videos
，提示词中使用
@Video1
，不传入
negative_prompt
）。",