# Prompt patterns

Two kinds of prompt: the keyframe (a still, GPT Image 2) decides everything you see; the motion prompt (Seedance) only decides how it moves. Put the effort into the keyframe.

## Keyframe prompt anatomy

`build-requests.mjs` wraps your `keyframe_prompt` as: "A still frame from a cinematic brand film. {your text} {reference sentences} {No other people…} {locks.look} Photorealistic, true-to-life anatomy and proportions. No text, no logos, no watermark."

Write `keyframe_prompt` in this order, one or two sentences each:
1. Shot size and angle: "Medium shot from behind and slightly to her right, three-quarter back view, waist up".
2. Subject and the frozen moment: "{{CAST}}, wearing {{WARDROBE}}, sits on the edge of the deck with her lower legs in the water, leaning back on her hands".
3. Where the face is: "her face turned away towards the sea so only the line of her cheek shows".
4. Place: "{{LOCATION}}" plus what this frame shows of it.
5. Light: direction, quality, time of day.
6. Lens and composition: focal length, where the subject sits in the frame, how big ("full figure at about 40 percent of frame height").

Stills that worked in testing (Kaia Island sample, `assets/shot-list-example.json` has every prompt in full):
- Aerial: "Cinematic drone aerial photograph, early morning … seen from about 120 metres up at a 35 degree downward angle … rule of thirds, villas in the lower right third".
- Walk: "walks barefoot away from the camera along the weathered teak boardwalk … The long linen shirt hangs loosely to mid-thigh and covers her hips … Camera low behind her at hip height, 35mm lens".
- Underwater: "The camera rests near the white sandy bottom and looks up towards the bright surface … she glides across the frame … seen from the side and below as a graceful, softly lit silhouette; her face is turned up towards the surface and hidden".
- Silhouette: "camera facing into the low sun … She is backlit: her figure and face are a dark silhouette with only a thin warm rim of light along her outline".

## Tasteful framing

Write it into the keyframe prompt; do not rely on the model's defaults. These rules come from the two stills rejected while making the sample.
- Wardrobe covers by default: put a shirt, wrap or robe over swimwear for walking, arrival and interior shots; swimwear alone only in water, at the pool or in silhouette.
- Pin the garment: "the long linen shirt hangs loosely to mid-thigh and covers her hips". Do not ask for wind lifting a shirt or skirt; that produced a frame showing the swimsuit bottom (jetty attempt 1).
- No framing centred on hips or buttocks. Following a swimmer from behind and below with a 24 mm lens did exactly that (underwater attempt 2); the used angle is from below, the figure small and in silhouette against the sun.
- Swimwear only in full-figure or side views; no tight body crops.
- Write "Tasteful, editorial" in swimwear and resortwear prompts, and check every clip (not only the still) for wardrobe drift: a shirt that slips or opens, straps that change, fabric that lifts.

## Motion prompt anatomy (Seedance 2.5 image-to-video)

One sentence each, in this order, all slow and specific:
1. Subject action, complete for the whole duration: "She walks slowly away from the camera along the boardwalk at a relaxed, natural pace."
2. Camera: one move only: "the camera follows behind her on a smooth gimbal at the same speed, keeping her centred."
3. Environment motion: "the hem of her shirt moves gently in the breeze, small ripples cross the water."
4. Guards: "She never turns around. No other people anywhere. One continuous shot, no cuts, real-time speed."

Camera moves that work: slow drone glide forward, slow descent, gimbal follow at walking pace, very slow push-in, slow lateral dolly, slow rise with gentle rotation (overhead), tilt to follow, locked off with slight handheld drift.

Camera moves that cause trouble: fast orbits around a person (face and body morph), arcs that reveal new background (extra people appear), whip pans, zooms through objects, "dramatic" anything.

## What causes morphing, and the fix

| Cause | What you see | Fix |
|---|---|---|
| The action ends before the clip does | Hands float, odd gestures, the subject turns to camera in the last seconds | Describe an action that fills the whole duration, add "then stays still"; trim the end in assembly |
| Head turns and faces | Face changes identity mid-turn | Keep the face away; "never turns towards the camera" |
| Hands near the face | Melted fingers | Keep hands in hair, on surfaces or in water; trim moments where hands cross the face |
| Fast motion | Smearing, rubbery limbs | "slow", "gentle", "real-time speed"; shorter durations |
| Text or labels in frame | Letters crawl | No text in keyframes; for product labels, slow push-in only and check every frame |
| Several people crossing | Bodies merge | One subject per shot, or a still couple |
| Big camera move on a close-up | Background warps | Close-ups get locked off or very slow push-in |
| Long durations | Drift and new elements | 4–6 s per shot; never more than 8 s for a person shot |

## Drafts versus finals

- Draft each shot on Seedance 2.0 mini at 480p (about $0.07 per second): it tells you whether the start frame is accepted (face check), whether the action reads, and whether anything spawns. It is a different, weaker model: judge the idea, not the polish.
- Then the final on Seedance 2.5 image-to-video at 720p (about $0.47 per second) with the same keyframe and the motion prompt adjusted from what the draft showed. 2.5 can still produce a stray gesture or a late turn; look at the contact sheet and trim, or re-roll once with one change.
- `generate_audio: true` costs nothing extra on Seedance 2.5; it gives ambient sound (waves, wind, fire) you can keep with `--audio clips`. Never ask for speech or lip-sync.

## Examples for other kinds of brand

- Drink pour (insert/signature): keyframe "Close-up, 85mm: a hand tilts {{PRODUCT}} and pours into a frosted glass on a dark stone bar, the liquid mid-pour, warm side light". Motion "The liquid pours steadily into the glass, foam rises, condensation beads run down; the camera holds still. The bottle and its label stay unchanged."
- Skincare: "A drop of serum falls from the dropper of {{PRODUCT}} onto a fingertip …" Motion "very slow push-in, the drop lands and spreads; the bottle stays still and unchanged."
- City night (establishing): "Drone shot at blue hour over a narrow old-town street, warm café lights …" Motion "The drone drifts slowly forward above the street, lights flicker gently, a few tiny distant pedestrians walk."
- Food (close): "Close-up of hands tearing a warm loaf, steam rising, flour on a wooden board, window light" — motion "The hands pull the bread apart slowly, steam curls up, crumbs fall."
- Fashion (arrival): "Full-length, 35mm, a model walks away down a sunlit stone colonnade in {{WARDROBE}} …" — motion "She walks slowly away, the fabric swings with each step, the camera follows at the same pace."

## Fail path (any single shot)

Max 3 attempts per shot. Change one thing per attempt and say which: (1) the motion prompt (simpler action, add a guard), (2) the trim points, (3) the keyframe itself (new still). Look at each attempt's contact sheet beside the keyframe. After three, use the best attempt trimmed to its clean part and tell the user what still differs.

If Seedance 2.5 keeps failing a shot, or the shot must show a face (Seedance refuses visible realistic faces), animate that shot with another model and grade it with the rest; the look will differ a little, so test one short draft first:
- Kling 3 turbo pro, `fal-ai/kling-video/v3/turbo/pro/image-to-video`, about $0.14 per second. Fields: `prompt`, `image_url`, `duration` as a string from "3" to "15", optional `multi_prompt`; there is no `resolution`, `end_image_url`, `generate_audio`, `bitrate_mode` or `codec`. Tested 2026-10-16 on a face-forward synthetic close-up: accepted, same face held for 3 s, returned 1920 × 1080 with a sound track (assemble-film.mjs scales it down to the other clips).
- Veo 3.1, `fal-ai/veo3.1/image-to-video`, $0.20 per second silent or $0.40 with audio. Fields: `prompt`, `image_url` (16:9 or 9:16, at least 720p, otherwise cropped), `duration` "4s", "6s" or "8s", `resolution` "720p"/"1080p", `generate_audio`, `aspect_ratio`, optional `negative_prompt`. Tested on the same close-up: accepted, but the face drifted toward a different person within 4 s, so keep Veo face beats short and check them frame by frame.
All clips must share one aspect ratio (assemble-film.mjs refuses a mix).