# Prompt patterns

The keyframe (GPT Image 2) decides what the teaser looks like; the motion prompt (Seedance) only decides what moves. Approve every keyframe before any video is paid for.

## Locks

Write once in teaser.json and reuse through tokens:
- `locks.place` (`{{PLACE}}`): architecture, materials, setting. "a long, low chalet of dark weathered timber and grey stone with steep snow-covered roofs and tall glass gable windows, in a snowy clearing in dark spruce forest below jagged peaks".
- `locks.people` (`{{PEOPLE}}`): fictional adults only; build, hair, clothes colours. "a couple in their thirties in chunky cream and oatmeal wool sweaters".
- `locks.look`: written by build-shot-list.mjs from the grade.

Generate shot 1 (the aerial) first, approve it, and set `references.place` to it (unless the user gave real photos of the place). Every later keyframe then uses it as a reference, so the building, materials and mountains match from shot to shot.

## Keyframe prompt anatomy

build-requests.mjs wraps your text as: "A vertical 9:16 still frame from a cinematic travel teaser. {your text} {reference sentences} {Nobody in frame / No other people} {locks.look} Photorealistic, true-to-life scale and anatomy. No text, no signage, no logos, no watermark."

Write `keyframe_prompt` as: shot size and angle → subject → what in the frame will move (snow, steam, flames) → light → lens and where things sit in the vertical frame.

The Vael Lodge sample (every prompt in full in `assets/shot-list-example.json`):
- Aerial: "drone aerial photograph at blue hour in deep winter … Seen from about 80 metres up at a 40 degree downward angle; the lodge sits in the lower third of the frame, the peaks fill the top."
- Detail: "Outside one of its tall timber-framed windows: fat snowflakes drift down in front of the glass, the window panes glow warm amber, frost feathers the corners … a snow-capped iron lantern with a lit candle … Nobody in frame. 85mm lens."
- Amenity: "A small cedar barrel sauna … beside a wooden hot tub; thick white steam rises and swirls from the hot tub into the cold blue air, lit warm amber by a lantern."
- People: "seen from behind and slightly to the side, her head resting on his shoulder … both faces turned towards the fire and away from the camera."
- Hero: "the same lodge as in the reference image … seen from ground level in the snowy meadow … The lantern-lit path leads from the bottom of the frame up to the warmly glowing lodge … 24mm lens, camera low to the snow."

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

One camera move, what moves in the scene, guards:
- "Cinematic drone shot at blue hour: the drone descends slowly and glides forward towards the glowing lodge, smooth and steady; light snow falls, chimney smoke drifts, the lantern flames flicker. One continuous shot, no cuts, no people, no text."
- "Fat snowflakes drift slowly down past the frosted window; the candle flame in the lantern flickers gently; the warm room inside glows. The camera makes a very slow push-in."
- "The couple sits still by the fire, her head resting on his shoulder; he gently strokes her arm; the fire crackles and flickers … Their faces stay turned towards the fire, away from the camera."

Camera moves that work in 4 s: slow drone glide or descent, very slow push-in, slow rise, slow lateral move, low push along a path. Avoid orbits around people, whip pans, zooms through windows, and "fast" anything.

## Tasteful framing

Hot tubs, pools, saunas and beaches are where travel reels go wrong. Write these into the prompt:
- People are dressed by default: knitwear, robes, linen, a towel wrap. Swimwear only in the water or in silhouette, and then from behind or the side, full figure or shoulders-up in the water.
- Pin the garment: "the robe stays closed", "the shirt hangs to mid-thigh". No wind-lifted shirts, skirts or towels.
- Never centre the frame on hips or buttocks; no low angles from behind on a swimsuit.
- Couples: affectionate and calm (a head on a shoulder, an arm around), nothing more.
- Check every clip for wardrobe drift: a robe that opens, a strap that changes, fabric that lifts mid-shot. Trim or re-roll.

## Faces and the Seedance safety check

Seedance on fal refuses start frames with a clearly visible realistic face (`content_policy_violation`, "likenesses of real people"), even for fictional people. Show people from behind, in profile shadow, in silhouette or small in frame. This also keeps the teaser about the place, and lets viewers imagine themselves there.

## Failure modes and fixes

| You see | Cause | Fix |
|---|---|---|
| The building changes shape between shots | No place reference, or a weak one | Set `references.place` to the approved aerial or the user's photo; re-roll the still |
| Extra people appear in windows or on paths | The camera reveals new background | "Nobody in frame" / "No other people anywhere"; slower, shorter camera moves |
| Signs, menus, logos with garbled letters | Text invited by the scene | "No text, no signage"; choose details without lettering |
| Snow or rain falls upward or stops mid-shot | Overlong or conflicting motion | One weather instruction, "falls gently downward", 4 s clips |
| Steam or smoke freezes | Too little motion asked | Name the movement: "rolls and swirls upward" |
| Fire looks like a video loop | Fire too large in frame | Keep the fire a light source, people or room in focus |
| An object grows huge as the camera passes it (lantern, branch) | Push-in through foreground objects | Trim before it fills the frame, or ask for a slower push that stops short |
| Odd gestures or a turn to camera at the end | The action ends before the clip | Give an action for the whole clip and trim the end |

## Drafts and finals

- Drafts: Seedance 2.0 mini image-to-video at 480p (about $0.07/s, so about $0.29 per 4 s shot). They show whether the frame is accepted and whether the motion reads; judge the idea, not the polish.
- Finals: Seedance 2.5 image-to-video at 720p (about $0.47/s, about $1.89 per 4 s shot), `generate_audio: true` (same price), `bitrate_mode: "high"`, `codec: "H264"`.

## Fail path

Max 3 attempts per shot. Change one thing each time and say which: the motion prompt, the trim, or the keyframe. View every attempt's contact sheet beside its keyframe. After three, use the best attempt trimmed to its clean part and tell the user what still differs.

Alternative video models, if Seedance keeps failing a shot or the user insists on a visible face (tested 2026-10-16 on one face-forward synthetic close-up; test one short draft first, and expect a slightly different look that the grade only partly evens out):
- Kling 3 turbo pro, `fal-ai/kling-video/v3/turbo/pro/image-to-video`, about $0.14/s. Fields: `prompt`, `image_url`, `duration` "3"–"15", optional `multi_prompt`; no `resolution`, `end_image_url`, `generate_audio`, `bitrate_mode` or `codec`. Accepted the face and kept it for 3 s; returned 1920 × 1080 (or 1080 × 1920) with a sound track.
- Veo 3.1, `fal-ai/veo3.1/image-to-video`, $0.20/s silent or $0.40/s with audio. Fields: `prompt`, `image_url` (16:9 or 9:16, at least 720p), `duration` "4s"/"6s"/"8s", `resolution`, `generate_audio`, `aspect_ratio`, optional `negative_prompt`. Accepted the face, but it drifted toward a different person within 4 s.
All clips must share one aspect ratio for assemble-teaser.mjs; larger clips are scaled down to the smallest.