Seedance Video Studio

Turn raw material into a finished short video. This skill covers the whole path: reading
the material, researching the right visual reference, writing a prompt that actually earns
a good render, driving the Volcengine Ark Seedance API, and pulling the finished MP4 back
to disk.

It also carries working knowledge of film language - the shot grammar behind why one
camera move lands and another one does not - so a request like "make it feel like a
Wong Kar-wai film" becomes something a model can actually render, rather than a
compliment that goes nowhere.

It works in two modes, and the second one matters because it means the skill is useful
even before anyone has an API key.

Step 1 - Decide which mode you are in

Check the environment before promising anything:

python3 scripts/video_studio.py doctor

doctor reports the Python version, whether ARK_API_KEY is set, and whether the
endpoint authenticates. Exit code 0 means generation is available. Non-zero means fall
back to prompt-only mode, or help the user get a key.

If there is no key, do not stall the task. Produce the prompt, then tell the user in one
sentence what to set to unlock generation.

Three tools ship with this skill:

Step 2 - Understand the material

Work out what the user actually handed over before writing a single word of prompt:

• Text only - the idea is theirs; your job is to make it concrete and visual
• Image only - read the image and propose a direction; this is where the most value is created
• Image + text - reconcile them; if they conflict, say so rather than silently picking one
• First + last frame - the motion between them is the whole story; describe the journey, not the endpoints
• Reference images - the user wants a style or subject carried over, not the image animated

Step 3 - Anchor to references

Skip only when the request is already fully specified and simple. Run this loop whenever
the user names a film, a director, a style, a mood, or a genre - or says anything like
"make it look like X" or "I want it to feel premium".

R1 - Research

Use web_search. Query patterns that actually return usable material:

Collect two to four references. Record concrete techniques, not impressions.
"The lighting felt moody" is useless. "Low-key lighting, one hard side light, cold
grade" is usable.

R2 - Deconstruct

Break each reference into the eight variables from
references/cinematography.md: shot size, angle, movement,
composition, focal length, lighting, color, editing rhythm.

Then name the mechanism - what specifically makes it work? The push-in that compresses
distance? The negative space that isolates? The warm-cool split that adds depth? Write the
mechanism down. Impressions cannot become prompts; mechanisms can.

R3 - Translate

Map the mechanism onto what a generative model can actually execute. This is where most
attempts fail - film references assume long takes and permanently consistent actors,
neither of which holds here. Read section 10 of
references/cinematography.md before translating.

The three hard gaps: 3-5 second stable clip length, no inherent cross-shot consistency,
and fragile complex motion.

R4 - Exceed

Apply one of the four moves from references/shot-library.md:

Then ask: can the viewer tell this is copied? If yes, it failed. Rewrite.

Copyright boundary

Learn the technique; do not reproduce the frame.

• Technique is free. Camera movement, lighting approach, composition logic and color
  strategy are not protected - study and reuse them freely.
• Specific protected expression is not. Recreating a distinctive copyrighted
  character, a branded product, a recognizable shot-for-shot sequence, or a real person's
  likeness is off limits. Decline those.
• Naming a film as a style reference is normal and fine. Rendering that film's actual
  footage, characters, or logo is not.
• When in doubt, name the mechanism instead of the film: 低饱和冷调 + 极慢推镜 + 大面积负空间
  beats 做成和银翼杀手一样.

What "exceed" can and cannot mean

Be straight with the user rather than overselling it.

Can exceed a film reference on: single-shot visual density (light, texture and grade
dialed in precisely); speed and cost (minutes, not a shoot day); combinations no real
production would attempt.

Cannot exceed on: narrative complexity inside one shot (3-5s, one idea per shot);
cross-shot continuity without deliberate constraints; complex multi-subject staging.

So "exceed" means a stronger shot, assembled into a sequence - not out-directing a
director inside a single 5-second clip. Say it plainly. A user who understands the
boundary gets a better result than one who was promised cinema and handed a clip.

Step 4 - Write the prompt

The prompt must be in Chinese. Seedance is tuned for Chinese. The conversation with
the user can be in any language; the prompt that goes into the API is always Chinese.

A prompt that renders well has four layers, roughly in this order:

1. Subject and action - who or what, doing what, where
2. Camera work - shot scale, movement, speed. Pull terms from
   references/prompt-cookbook.md; do not invent vocabulary
3. Light and texture - time of day, light source, color grade, material feel
4. Rhythm and mood - pacing, emotional beat, what the viewer should feel at the cut

Keep it tight. A 5-second clip cannot carry eight ideas. Pick one subject, one camera
move, one emotional beat.

For ready-made shot structures, start from a template in
references/shot-library.md instead of a blank page. Each
one gives the intent, a fill-in-the-blanks Chinese prompt, and a way to push past the
original.

The quality gate

Before submitting, run the prompt through this filter. If it fails, rewrite - do not
generate and hope.

• Is anything surprising in it? Frame-accurate renderings of the obvious are forgettable.
• Is there a change? Even in five seconds there should be an A to B, not a static slice of life.
• Would you describe it to a friend? If not, it is not interesting enough yet.

Iterate two or three times here. A rewrite costs nothing; a render costs money and a
minute of waiting.

Step 5 - Submit and retrieve

# Text to video
python3 scripts/video_studio.py create \
  -p "清晨的深圳湾，一只白鹭掠过水面，晨雾未散，镜头缓慢横移跟随" \
  --ratio 16:9 --duration 5 --wait --download ~/Videos

# Image to video (adaptive ratio keeps the source shape)
python3 scripts/video_studio.py create \
  -p "镜头缓慢推近，画面中的人物微微转头看向窗外，光线从冷转暖" \
  -i photo.jpg --ratio adaptive --duration 5 --wait --download ~/Videos

# First and last frame - run check-pair first, see the dedicated section below
python3 scripts/video_studio.py create \
  -p "花苞紧闭、花瓣收拢，随时间缓缓绽开、颜色由浅粉渐深，最后完全盛开，镜头极缓慢推近，晨光暖色调" \
  --image bud.jpg --last-frame bloom.jpg --ratio adaptive --duration 6 --wait --download ~/Videos

# Reference images carry style across
python3 scripts/video_studio.py create \
  -p "保持参考图的青绿山水笔触风格，画中的舟缓缓顺流而下" \
  --ref-images ref1.jpg ref2.jpg --wait --download ~/Videos

# Inspect the request without spending a call
python3 scripts/video_studio.py create -p "..." --dry-run

Always pass --wait --download <dir> for interactive work. Submitting without --wait
returns a task id that has to be polled separately, which is only useful for batching.

Job management

python3 scripts/video_studio.py status <task_id>        # inspect one job
python3 scripts/video_studio.py wait <task_id> --download ./out
python3 scripts/video_studio.py list --status succeeded
python3 scripts/video_studio.py delete <task_id>        # cancel or remove
python3 scripts/video_studio.py models                  # model table and defaults

Add --json to any command for machine-readable output. Add --dry-run to create to
inspect the exact payload - it never sends credentials or media to the network.

First / last frame workflow

This mode fails more often than any other, and nearly always for a reason that was
visible before submitting anything. Two checks come first:

# 1. Can these two frames survive being interpolated?
python3 scripts/image_prep.py check-pair first.jpg last.jpg

# 2. If the geometry disagrees, normalise it before submitting
python3 scripts/image_prep.py pair-fit first.jpg last.jpg --ratio 16:9 --out-dir ./frames

check-pair returns a 0-100 compatibility score and a suggested duration. Treat anything
below 55 as a signal to fix the frames rather than to hope harder. pair-fit repairs
geometry; it cannot repair content that is too far apart - that needs a new frame or two
separate shots.

Then write the prompt as start -> path -> end. Describing only the two endpoints
leaves the model to invent the middle, and that is where drift and morphing come from.

The last frame is a guide, not a pixel lock. Expect the final frame to approach your
target in composition, subject and mood - not to match it exactly. When you need
frame-exact continuity, make it two shots and cut them together.

Full guidance, mid-motion verbs, a duration table and worked examples:
references/frame-transition.md.

Setup

Only needed for generate mode. Prompt-only mode works with no setup at all.

1. Create an API key at the Volcengine Ark console.
2. Export it - never paste a key into a file that gets shared:

# macOS / Linux / Git Bash
export ARK_API_KEY="your-key-here"

# Windows PowerShell
$env:ARK_API_KEY = "your-key-here"

3. Confirm: python3 scripts/video_studio.py doctor

Interpreter name. Examples throughout use python3. On Windows the interpreter is
normally python - substitute it if python3 is not recognised.

Optional environment variables: ARK_MODEL (override the default model), ARK_BASE_URL
(custom endpoint), ARK_TIMEOUT (HTTP timeout in seconds, default 60).

video_studio.py and trend_scout.py use only the Python standard library, so they run
on a bare Python 3.8 or newer. image_prep.py does its checks with the standard library
alone, and unlocks cropping and frame normalisation when Pillow is present:

python3 -m pip install pillow   # optional - unlocks crop / fit / pair-fit

Model selection

Default is doubao-seedance-2-0-260128 (Seedance 2.0). If the account is not enabled for
it, fall back rather than failing:

Run python3 scripts/video_studio.py models for the live table. A 403 usually means the
model is not enabled on that account - switch models before assuming the key is broken.

Resolution defaults to quality

--resolution defaults to the highest setting the chosen model supports, capped at
1080p. Leaving it unset does not hand the decision to the model - it hands it to the
platform default, which is typically 720p or lower.

That silent downgrade is the most common reason a well-written prompt comes back looking
soft. Pass -r 720p when you want faster, cheaper renders. Reach for -r 2k
deliberately, never by default.

Platform limits

The script checks these before submitting, so violations surface as clear local errors
instead of opaque API rejections.

Local files are inlined as base64, so nothing needs to be hosted publicly.

Content safety red lines

These are platform policy, not preferences. Refuse and explain rather than attempting
and getting the account flagged.

• No real, identifiable people's faces submitted as material, and no prompt that
  recreates a specific real person's likeness.
• No sexualized content involving minors. Refuse outright, in every framing.
• No content that defames, harasses, or impersonates a real individual.
• No deepfake-style swaps of real people into scenarios they did not participate in.
• Flag anything that looks like it is heading toward fraud, defamation, or non-consensual
  intimate imagery, and decline.

When a request trips a red line, say which line and offer a legitimate alternative
direction - a generic subject, an illustrated style, a stock-like composition. Do not
just refuse and stop.

Troubleshooting

Run doctor first; it isolates most failures. Then match the message:

Generation typically takes 30 to 180 seconds depending on resolution and model. Polling
every 15 seconds is a reasonable default.

Trend Scout - batch collection and analysis

scripts/trend_scout.py collects public content and turns it into prompt intelligence.
Reach for it when the user wants to know what is currently working, as opposed to
generating one specific clip.

Two layers, answering different questions:

A finding worth remembering. Ranking feeds carry titles and blurbs, not shot
descriptions. A real run against 55,000 characters of Bilibili ranking data matched
shot-language terminology 3 times - a density of 0.05 per 1000 characters. The report
states this up front, because pretending otherwise wastes the user's time. Ranking data
informs what to make; it never tells you how to write the prompt.

python3 scripts/trend_scout.py sources                     # built-in sources + blocklist
python3 scripts/trend_scout.py check <url>                 # is this URL fetchable?
python3 scripts/trend_scout.py scout --urls urls.txt --out report.md --delay 3
python3 scripts/trend_scout.py scout --seed --out report.md
python3 scripts/trend_scout.py analyze --input .trend_scout --out report.md

The output is a report, never an automatic edit. Trend data is noisy and a bad merge
would pollute every future prompt. The user reviews the report and decides what - if
anything - goes into prompt-cookbook.md.

Compliance posture

State this plainly to the user; do not soften it.

• The script refuses known-prohibited domains (Douyin, Kuaishou, Xiaohongshu, Weibo,
  TikTok, Instagram, Facebook, Zhihu) and says why, rather than attempting and failing.
• It respects robots.txt, rate-limits per domain, caps pages per domain, and stops a
  domain immediately on 403 / 429.
• It never bypasses a captcha, login wall, signature, or paywall, and never sends
  credentials.
• This is not a scraper for the platforms the user probably has in mind. When asked
  to scrape Douyin or Xiaohongshu, explain that the risk is legal rather than merely
  technical - unfair-competition law, and potentially criminal-code exposure for
  circumventing technical measures - then route them to official open APIs or licensed
  data services.
• When platform-scale analysis is genuinely needed, point at the licensed data
  connectors available in this environment (FastMoss, Tec-Do and similar) rather than
  attempting a custom crawler.

Reference material

Read in this order when the task is creative; jump straight to the API doc when it is
mechanical.

The creative references are written in Chinese, because the prompt vocabulary they exist
to supply is Chinese. The mechanism descriptions stay readable regardless of what
language the conversation is in.