@slatesvideo/shared 0.1.0 → 0.3.0

package/skills/slates-prompting-flux-2-max.md

@@ -0,0 +1,106 @@
+---
+name: slates-prompting-flux-2-max
+description: How to prompt FLUX.2 Max (Black Forest Labs image model). Read before calling slates_generate_image with model flux-2-max, or slates_edit_image with editModel flux-2-max. FLUX.2 wants front-loaded structure, real camera vocabulary, and positive-only phrasing — no negative prompts, no tag soup.
+---
+
+# FLUX.2 Max — prompting
+
+Black Forest Labs' top image model, routed via fal.ai. In Slates: `slates_generate_image` with `model: flux-2-max` (REQUIRES projectId — no headless path), priced per resolution (1k/2k/4k — call `slates_estimate_generation_cost` for current numbers, never quote from memory). Strengths vs Nano Banana 2: photoreal texture, less censored, precise hex-color control, strong typography. Reference images route through FLUX's edit endpoint and carry a lower per-model cap than NB2's 14.
+
+## Core structure — front-load what matters
+
+```
+Subject + Action + Style + Context
+```
+
+Word order is weight. FLUX.2 attends hardest to the start of the prompt: main subject → key action → critical style → essential context → secondary details.
+
+**Length:** 10-30 words for concept tests, 30-80 words for most work, 80+ only for genuinely complex scenes.
+
+## Photorealism: name real gear, not "professional photo"
+
+The single biggest realism lever is concrete camera vocabulary:
+
+```
+Shot on Hasselblad X2D, 80mm lens, f/2.8, natural lighting
+Shot on Sony A7IV, 35mm, golden hour, shallow depth of field
+Kodak Portra 400, natural grain, organic colors
+```
+
+Era cues work the same way: "early digital camera, slight noise, flash photography, candid" reads 2000s digicam; "film grain, warm color cast, soft focus" reads 80s.
+
+For portraits add: natural skin texture, realistic pores, subtle imperfections, soft diffused lighting.
+
+## No negative prompts — reframe positively
+
+FLUX.2 has no negative prompt support. Describe the presence you want, not the absence:
+
+- ❌ "no blur" → ✅ "sharp focus throughout"
+- ❌ "no people" → ✅ "empty scene"
+- ❌ "no harsh shadows" → ✅ "soft, diffused lighting"
+
+## Hex colors — bind them to objects
+
+FLUX.2 matches hex codes, but only when each code is attached to a specific object:
+
+```
+walls in hex #C4725A, sofa in #1B6B6F, accent pillows #E8A847
+gradient starting with color #02eb3c and finishing with color #edfa3c
+```
+
+❌ "use #FF0000 somewhere" — unbound colors land inconsistently.
+
+## Text rendering
+
+Quote the exact text, then place and style it:
+
+```
+The text 'OPEN' appears in red neon letters above the door
+Logo text 'ACME' in color #FF5733, ultra-bold decorative serif, centered
+```
+
+Specify placement relative to other elements, font family feel (serif / sans / script), and relative size ("large headline," "small body copy").
+
+## JSON prompting for production work
+
+For multi-element scenes that must come out exactly right (product shots, infographics, brand work), FLUX.2 parses structured JSON prompts:
+
+```json
+{
+  "scene": "Professional studio product photography on polished concrete",
+  "subjects": [{ "description": "matte black ceramic mug with steam", "position": "center foreground" }],
+  "style": "commercial product photography",
+  "color_palette": ["#1B1B1B", "#E8A847"],
+  "lighting": "three-point softbox, soft diffused highlights",
+  "camera": { "lens-mm": 85, "f-number": "f/5.6" }
+}
+```
+
+Use natural language for exploration, JSON when the layout is locked and you're matching a spec.
+
+## Reference images (edit path)
+
+In Slates, pass `referenceAssetIds` on `slates_generate_image` — FLUX routes them through its edit endpoint. Label every reference's role in the prompt text ("subject from image 1, style from image 2, background from image 3"); unlabeled references get blended unpredictably. For surgical changes to one existing image use `slates_edit_image` with `editModel: flux-2-max` (note: FLUX edits ignore extra referenceAssetIds — that's NB2-only).
+
+## Character consistency across a series
+
+Define the character exhaustively once, then repeat those exact descriptors verbatim in every subsequent prompt. FLUX has no memory between generations — the repeated description IS the consistency mechanism.
+
+## Common failure modes + fixes
+
+| Failure | Fix |
+|---|---|
+| Generic "AI look" on photoreal | Name a camera body + lens + f-stop instead of "professional photo" |
+| Colors drift from brand spec | Bind each hex code to a named object |
+| Text garbled | Quote the exact string, specify font feel + placement + size |
+| Multi-reference blend chaos | Label each reference's role explicitly in the prompt |
+| Wanted element missing | Move it earlier in the prompt — order is weight |
+
+## Pre-flight: references arrive inline, refer by code
+
+When you pass `referenceAssetIds`, the first call returns the references **inline as image content blocks** with a cost estimate and `requires_confirm: true`. Look at them — revise the prompt if they suggest a different composition or style — then re-call with `confirm=true`. Refer to each asset by its short code (`IMG-A12 — Beach Sunset`) when talking to the user; it matches the badge on their gallery thumbnail.
+
+## Sources
+
+- [Black Forest Labs — FLUX.2 Prompting Guide](https://docs.bfl.ml/guides/prompting_guide_flux2)
+- [fal.ai — FLUX.2 [max] Prompt Guide](https://fal.ai/learn/devs/flux-2-max-prompt-guide)

package/skills/slates-prompting-kling-v3.md

@@ -0,0 +1,160 @@
+---
+name: slates-prompting-kling-v3
+description: How to prompt Kling V3.0 (Kuaishou). Read before calling slates_generate_video with kling-v3.0-std, kling-v3.0-pro, or kling-v3.0-omni. Kling has dialogue + SFX + ambient native syntax (Omni adds multi-character dialogue and language codes). Multi-shot rules differ from Seedance/Veo — don't cross syntaxes.
+---
+
+# Kling V3.0 — prompting
+
+Kuaishou's video model. Three tiers: `kling-v3.0-std` (general use, no audio), `kling-v3.0-pro` (higher visual quality, no audio), `kling-v3.0-omni` (multi-character dialogue + audio-visual co-generation).
+
+Up to 15s. Multi-shot supported (up to 6 cuts in 15s total). Strong on image-to-video — preserves identity, layout, and text from the input image well.
+
+## Subject definition rule (verbatim, fal blog)
+
+> "Define your core subjects clearly at the beginning of the prompt and keep descriptions consistent across shots."
+
+## Dialogue syntax
+
+```
+Character says, "exact words here"
+```
+
+Use quotation marks for precise speech. Languages (Omni only): EN, ZH, JA, KO, ES.
+
+## Voice direction formula (Omni)
+
+```
+Gender + Age Range + Voice Quality + Speech Rate + Emotional Tone + Language
+```
+
+Example:
+```
+[Character A: Detective, mid-40s, raspy voice, slow cadence, weary]: "I've seen this before."
+```
+
+Tone phrases that fire:
+- `speaking in a hushed, trembling whisper`
+- `shouting with commanding authority`
+- `clear, fearful voice`
+- `with a trembling voice, "I'm scared"`
+
+## The `Immediately` keyword (Omni only)
+
+Without `Immediately`, Kling adds a natural conversational beat between speakers. With it, dialogue is back-to-back. Use when timing matters.
+
+```
+[Alice]: "Get down!" Immediately, [Bob]: "Where?"
+```
+
+## Speaker label discipline
+
+Unique labels per character. **No pronouns or synonyms after first introduction** — they cause voice drift.
+
+✅ `[Character A: Black-suited Agent]` ... `[Character A: Black-suited Agent]: "Stop."`
+❌ `[Agent]... then he says...`
+
+## Multi-character dialogue (Omni)
+
+```
+Alice says in English, "Hello!" Then Bob replies in Spanish, "¡Hola!"
+```
+
+## Sound effects, ambient noise, music
+
+```
+SFX: thunder cracks, footsteps approaching
+Ambient noise: city traffic, birds chirping, ocean waves
+Background music: tense orchestral strings, low cello
+```
+
+SFX accepts physical-cause specificity:
+- ✅ `SFX: heavy boots on wet pavement, distant siren wailing`
+- ❌ `SFX: footsteps`
+
+## Image-to-video guidance
+
+**Verbatim (fal blog):**
+> "Treat the input image as an anchor. Kling 3.0 excels at preserving the identity, layout, and text details. Focus prompts on how the scene evolves *from* the image: subtle movements, camera motion, or environmental changes."
+
+**Don't re-describe what's already in the image.** Focus on motion, changes, evolution.
+
+## Multi-shot — what makes them hit
+
+**Hard cap: total duration ≤ 15s across all shots. Max 6 cuts.**
+
+Hit conditions:
+- Shot labels are explicit: `Shot 1:`, `Shot 2:`
+- One primary action per shot
+- Subject described identically in each shot block
+- Camera move per shot is **one verb**, not a chain
+- Per-shot blocks: 30-60 words
+
+Miss conditions:
+- Compressing narrative into one paragraph
+- Pronoun-only references after the first shot
+- Mixing camera moves within a shot ("pan then orbit then push in")
+- Extreme wide → extreme close in adjacent shots without reference images
+
+## Element references (Omni)
+
+Upload 2-4 multi-angle reference photos per character/object. Tag inline:
+
+```
+@element1 is the protagonist (refs: front, side, back angles).
+@element2 is the antagonist.
+```
+
+## Negative prompting — has a real field
+
+Kling exposes `negative_prompt` on the fal endpoint (different from Seedance which has none). Default block to start from:
+
+```
+blurry, low quality, watermark, text overlay, distorted hands, extra fingers,
+duplicate limbs, unnatural skin texture, overly saturated colors, lens flare,
+floating objects, inconsistent shadows, jittery, flickering, morphing face
+```
+
+Layer scene-specific suppressions on top.
+
+## Cinematic tactics
+
+- **Motion adverb precision** modulates motion energy directly: `slowly`, `rapidly`, `gently`, `explosively`
+- **Camera vocabulary that registers as instructions:** profile shot, tracking, following, freezing, panning, "moving in sync with the subject"
+- **One primary camera move per shot** — never stack
+
+## Tier choice
+
+- **Standard**: general use, no audio
+- **Pro**: higher visual quality, no audio
+- **Omni**: multi-character dialogue, audio-visual co-gen, language codes, `@elementN` references
+
+Pick by capability: need dialogue/audio → Omni; need maximum visual quality silent → Pro; everything else → Standard. Prices change — call `slates_estimate_generation_cost` or `slates_list_available_models` for current numbers before choosing a tier.
+
+## Benchmark prompt structure
+
+```
+[Character A: <role>, <voice quality>]: "<line>." Immediately, [Character B: <role>, <voice quality>]: "<reply>."
+Ambient noise: <soundscape>.
+Camera <single move>.
+```
+
+Cinematic example (paraphrasing fal blog patterns):
+> "Shot 1: Wide establishing shot of a neon-lit alleyway in heavy rain, steam rising from grates. Camera slowly tracks forward.
+> Shot 2: Medium shot of a detective in a trench coat ducking under an awning, water dripping from his hat brim. [Detective: weary, raspy]: 'I knew she'd come back.' Ambient noise: distant traffic, rain on metal.
+> Shot 3: Close-up on his eyes, narrowing as headlights flash across his face."
+
+## Pre-flight: references arrive inline, refer by code
+
+When you call `slates_generate_video` with `firstFrameAssetId` or `ingredientAssetIds`, the first call returns those references **inline as image content blocks** alongside cost + `requires_confirm: true`. Look at them, revise prompt if needed, then re-call with `confirm=true`. Kling Omni multi-character with several ingredient images especially benefits — confirm each character image lands cleanly before spending.
+
+When talking to the user about the gen, refer to each reference by its short code: `IMG-A12 — Detective Closeup`. The user sees that code as a gallery badge.
+
+- ✅ "I'm anchoring on **IMG-A12** as the detective and **IMG-A18** as the alleyway environment — Omni will handle the line delivery in EN."
+- ❌ "I'm using the detective image and the alley one..." (which alley? Three exist.)
+
+## Sources
+
+- [fal.ai — Kling 3.0 Prompting Guide](https://blog.fal.ai/kling-3-0-prompting-guide/)
+- [Vidguru — Kling 3.0 Omni Guide](https://www.vidguru.ai/blog/kling-3.0-omni-guide.html)
+- [AcceptPrompt — Kling 3 Prompt Guide](https://www.acceptprompt.com/blog/kling-3-prompt-guide)
+- [DataCamp — Kling 3.0 Tutorial](https://www.datacamp.com/tutorial/kling-3-0)

package/skills/slates-prompting-lip-sync.md

@@ -0,0 +1,169 @@
+---
+name: slates-prompting-lip-sync
+description: How to set up Kling lip-sync. Read before calling slates_generate_lip_sync. Two flows — video→video re-dub and image→video avatar — with different inputs, pricing, and gotchas. Voice catalog, framing rules, audio file constraints, and which tier to pick.
+---
+
+# Kling lip-sync — setup guide
+
+Two distinct flows, both 5-second outputs:
+
+| Flow | Source | Model | Cost (5s) | Use case |
+|------|--------|-------|-----------|----------|
+| Re-dub | video clip | kling-lip-sync-video | $0.11 | Replace dialogue on an existing talking head |
+| Avatar standard | still image | ai-avatar/v2/standard | $0.42 | Animate a portrait into a talking avatar |
+| Avatar pro | still image | ai-avatar/v2/pro | $0.86 | Higher facial fidelity for hero shots |
+
+Pick `sourceType` deliberately — it decides the pricing tier and the underlying endpoint.
+
+## Choosing video vs avatar
+
+Use **video** (re-dub) when:
+- A talking-head clip already exists (Slates-generated, recorded, or imported)
+- The mouth/face is already moving and only the audio needs to change
+- $0.11 is hard to beat for short dialogue replacement
+
+Use **avatar** when:
+- Only a still portrait exists
+- The character needs to come alive from a single image
+- Identity + face fidelity matter (avatar-pro for hero shots, standard for everything else)
+
+## Source asset constraints
+
+### Video flow (`sourceType: 'video'`)
+- Format: mp4 or mov
+- Duration: 2–10s (lip-sync output is always 5s — long videos get trimmed)
+- Resolution: 720p or 1080p (480p will be rejected)
+- Max file size: 100MB
+- Face must be visible and roughly facing camera. Profile shots fail.
+- Existing audio is replaced.
+
+### Avatar flow (`sourceType: 'image'`)
+- Min 512×512, PNG/JPG/WebP
+- **Face occupies 60–70% of frame.** This is the single biggest avatar quality lever.
+- Eyes open, mouth neutral, looking near-camera. Side profile = bad output.
+- Single subject, clean background. Group photos confuse the face anchor.
+
+## Audio source
+
+Two ways to drive the lips:
+
+### TTS (`audioMethod: 'tts'`)
+- Pass `ttsText` (the words spoken)
+- Optional: `ttsVoice` (default `oversea_male1`), `ttsLanguage` (default EN), `ttsSpeed` (default 1.0)
+- **Hard cap: 120 characters of text.** Longer = silently truncated.
+- Languages: EN, ZH, JA, KO, ES
+
+### Upload (`audioMethod: 'upload'`)
+- Pass `audioFilePath` — absolute path to an audio file on the user's machine
+- Format: mp3, wav, m4a, ogg, aac
+- Max 5MB
+- Duration: 2–60s (output is 5s — longer audio gets trimmed)
+- Single clean voice. Music underneath, multiple speakers, or noisy mics produce garbage lips.
+
+Prefer upload for production-quality voice. TTS for fast iteration / placeholder dialogue.
+
+## Voice catalog (TTS)
+
+Reliable English voices (verified working on the fal endpoint as of 2026):
+
+| Voice ID | Description |
+|----------|-------------|
+| `oversea_male1` | Male, English — default, stable |
+| `commercial_lady_en_f-v1` | Female commercial English |
+| `uk_boy1` | Young man, UK accent |
+| `uk_man2` | Man, UK accent |
+| `uk_oldman3` | Older man, UK accent |
+| `calm_story1` | Storyteller / narrator |
+
+Avoid `reader_en_m-v1` — listed in fal.ai docs but returns "Voice id not found" in production.
+
+Full 48-voice list (ZH, JA, KO included): https://fal.ai/models/fal-ai/kling-video/lipsync/text-to-video/api
+
+## Speech-rate notes
+
+`ttsSpeed` range 0.5–2.0:
+- 0.8–1.0: natural conversational
+- 1.1–1.3: punchy ad delivery
+- 1.4+: rushed, clips consonants
+- 0.6–0.7: slow, weighty (good for dramatic lines)
+
+Default 1.0 unless the line specifically calls for slower or faster cadence.
+
+## Avatar prompt usage
+
+The `prompt` parameter on avatar-v2 (standard + pro) is **scene context**, not motion direction. The mouth animation comes from the audio — the prompt sets ambiance, lighting, micro-expression.
+
+Good:
+- `Soft rim light, warm office, gentle confident smile between sentences.`
+- `Cool blue evening light through a window, focused intent expression.`
+
+Bad (the model ignores motion verbs):
+- ❌ `She turns her head, raises an eyebrow, then speaks.`
+- ❌ `Hand gestures while talking.`
+
+Default `"."` is fine if you have nothing useful to add.
+
+## Tier selection — avatar standard vs pro
+
+**Use standard** when:
+- Drafts, A/B testing voices, internal review reels
+- Wide / medium shots where face isn't the focal point
+- Cost matters more than micro-expression fidelity
+
+**Use pro** when:
+- Final ads where the avatar's face fills the screen
+- The character is named / branded — identity drift kills the take
+- You're already paying $1+ for the surrounding video pipeline
+
+Don't default to pro. The $0.44 delta per take adds up across iteration.
+
+## Common failure modes
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Lip movement looks "rubber" / disconnected | Source face <60% of frame | Re-crop the still tighter |
+| Voice doesn't match character age/gender | Default voice id used | Pick from voice catalog |
+| Output truncated mid-word | TTS text >120 chars | Shorten or chain two takes |
+| Garbled mouth on uploaded audio | Background music / multi-voice | Use clean dialogue-only audio |
+| "Voice id not found" 422 | Hit `reader_en_m-v1` | Switch to `oversea_male1` |
+| Avatar eyes drift / cross | Source had closed/angled eyes | Pick a frame with neutral open eyes |
+| Generation completes but lips don't move | Profile shot / face >70° off-axis | Use a near-frontal portrait |
+
+## Cost discipline
+
+- Video re-dub at $0.11 is the cheapest dialogue iteration in the entire Slates stack — use it for voice A/B testing
+- Avatar standard at $0.42 is fine for medium use
+- Avatar pro at $0.86 trips the >$0.50 confirm gate — explicit user OK required every time
+- All 5s. There is no shorter option.
+
+## Workflow patterns
+
+**Voice A/B test (cheap):**
+1. Generate one base talking-head video clip with Veo or Seedance (~$1.20)
+2. Run `slates_generate_lip_sync` with `sourceType: 'video'` against 3–5 different `ttsVoice` values
+3. Total cost: $1.20 + (5 × $0.11) = $1.75 to compare voices
+
+**Brand avatar from a single portrait:**
+1. Generate or upload the hero portrait (face fills frame, eyes open, neutral mouth)
+2. Avatar standard for first-pass dialogue takes
+3. Avatar pro only on the final selected take
+
+**Avoid:**
+- Avatar pro on first iteration (waste — facial fidelity isn't visible until you've locked the line)
+- TTS for final ads (production should use real voice or cloned voice — the upload flow)
+- Uploading raw recordings — clean noise + level the file first, lip detection is sensitive
+
+## Confirm gate: cost + codes, no inline preview
+
+Lip-sync is mechanical — the model re-syncs the chosen source to the chosen audio. The confirm response carries the source asset's code so you can announce it in chat.
+
+- ✅ "Lip-syncing **IMG-A12 — Founder Portrait** to the new line. $0.86 on avatar-pro. Confirm?"
+- ❌ "Using the founder image..." (which? Three exist.)
+
+Don't second-guess the source. If the output is wrong, iterate on source choice or audio, not on a refinement prompt (there isn't one).
+
+## Sources
+
+- [fal.ai — Kling LipSync API](https://fal.ai/models/fal-ai/kling-video/lipsync/text-to-video/api)
+- [fal.ai — AI Avatar v2 Standard](https://fal.ai/models/fal-ai/kling-video/ai-avatar/v2/standard/api)
+- [fal.ai — AI Avatar v2 Pro](https://fal.ai/models/fal-ai/kling-video/ai-avatar/v2/pro/api)

package/skills/slates-prompting-motion-transfer.md

@@ -0,0 +1,148 @@
+---
+name: slates-prompting-motion-transfer
+description: How to set up Kling Motion Control (motion transfer). Read before calling slates_generate_motion_transfer. Reference image (character) + driving video (motion source) → new video of the character performing the motion. Asset selection rules, character_orientation choice, std vs pro tier, and prompt usage.
+---
+
+# Kling Motion Control — setup guide
+
+Take a still **target image** (your character) and a **source video** (the motion you want), produce a new 5s video of your character performing the source video's motion.
+
+| Tier | Cost (5s) | Use case |
+|------|-----------|----------|
+| std (`kling-mc-std-5s`) | $0.95 | General motion transfer |
+| pro (`kling-mc-pro-5s`) | $1.26 | Cleaner anatomy, better identity preservation |
+
+Both tiers trip the >$0.50 confirm gate. User OK required every time.
+
+## Inputs
+
+- `sourceVideoAssetId` — driving video. **Must be a realistic human** with clear proportions. Anime/cartoon/CG driving videos fail.
+- `targetImageAssetId` — character to be animated. Can be any style (cartoon, anime, realistic, painted).
+- Both must already exist as assets in the project. Use `slates_list_assets` to find them or upload first.
+
+## Source video constraints
+
+- Realistic human (not animated, not CG)
+- Entire body OR upper body visible — head must not be obstructed
+- Subject occupies a clear share of the frame
+- Single primary subject. Multi-person driving videos confuse the motion anchor.
+- Clean motion — choppy / cut-edited driving videos produce jittery output
+
+Good driving video sources:
+- Reference dance footage with one subject
+- Walking / gesture / posing clips
+- Talking-head footage when paired with character_orientation: 'video'
+
+Bad driving video sources:
+- Music videos with multi-shot edits
+- Anime / animation clips
+- Heavily stylized footage with smoke / particles obscuring the body
+- Footage where the subject's head leaves frame mid-clip
+
+## Target image constraints
+
+- Character body proportions clearly visible
+- Character occupies >5% of image area (not a tiny figure in a wide shot)
+- Single character. Group images break the identity anchor.
+- Any artistic style works — cartoon, anime, painted, realistic, 3D render
+
+Avoid:
+- Extreme close-up of just the face (no body to drive)
+- Character partially cropped at the waist when the driving video is full-body
+- Multiple characters
+
+## character_orientation — the most-missed choice
+
+This single parameter changes the output dramatically. Pick deliberately.
+
+| Value | Output framing | Max source duration | Best for |
+|-------|----------------|---------------------|----------|
+| `video` | Matches driving video framing | Up to 30s source | Complex full-body motion (dance, action, athletics) |
+| `image` | Matches target image framing | Up to 10s source | Camera moves, simpler motion, preserving original composition |
+
+**Default `video`** when the driving video has the look you want (most cases).
+
+Switch to `image` when the target image's composition is the brand asset and the motion is secondary (e.g., a hero shot of a character that needs subtle gesture, not a full performance).
+
+## Tier choice — std vs pro
+
+**std ($0.95)** for:
+- Drafts, motion exploration, blocking
+- Group scenes where the character isn't a hero shot
+- When the budget is tight and the motion is the focus
+
+**pro ($1.26)** for:
+- Final hero takes
+- Branded characters where identity drift = unacceptable
+- Anatomically complex motion (limbs crossing, fast direction changes)
+- Anime / cartoon target images — pro handles non-realistic styles better
+
+Don't default to pro. The $0.31 delta compounds fast across iteration.
+
+## Prompt usage (optional)
+
+The `prompt` field is **scene/style refinement**, not motion direction. The motion comes from the driving video — the prompt sets ambiance, lighting, additional detail.
+
+Good:
+- `Soft afternoon sunlight, dust motes in the air, vintage warm color grade.`
+- `Clean studio backdrop, sharp focus on the character.`
+
+Bad (model ignores motion verbs — they're already in the driving video):
+- ❌ `She spins faster and jumps higher.`
+- ❌ `Add more energy to the dance.`
+
+Leave it empty if you don't have a specific atmospheric note.
+
+## Common failure modes
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| Limbs distort / extra fingers | std tier, complex motion | Switch to pro |
+| Character identity drifts | Target image cropped too tight | Use a fuller-body target |
+| Output looks "stuck" / minimal motion | Driving video subject too small in frame | Pick a driving video where the subject fills more of the frame |
+| Cartoon target turns realistic | std tier on stylized art | Switch to pro — handles non-realistic styles better |
+| Garbled output entirely | Anime / CG driving video | Use realistic human driving footage |
+| Wrong framing on output | character_orientation set wrong | Try the other value |
+| Background bleeds through character | Target image had complex background | Use a target with cleaner background separation |
+
+## Workflow patterns
+
+**Reference dance to brand character:**
+1. Generate or upload the brand character as a still image (clean background, full body, single subject)
+2. Find driving footage — a clean reference video of the dance you want
+3. Upload both as project assets
+4. Run motion transfer with `motionModel: 'kling-mc-pro'`, `characterOrientation: 'video'`
+5. Total cost: $1.26 per 5s take
+
+**Subtle motion on a hero portrait:**
+1. Use the locked hero portrait as the target image
+2. Pick a driving video with subtle gesture (head turn, slight posture shift)
+3. `characterOrientation: 'image'` to preserve the portrait's framing
+4. std tier is fine for this case — motion isn't dramatic
+
+**Avoid:**
+- Pro tier on first iteration — waste, switch to it once the motion + framing combo is locked
+- Cartoon driving videos — guaranteed failure
+- Cropped or partial target characters — identity will drift
+- Long driving videos when output is 5s — pick the best 5s of the source upfront
+
+## Cost discipline
+
+- 5 seconds, no shorter option
+- Both tiers trip the >$0.50 confirm gate — every call needs explicit user OK
+- Iteration is expensive: 4 takes at pro = $5.04. Lock framing + driving video before tier-up to pro.
+- Always run a single std take first to validate the motion + framing combo before committing to pro
+
+## Confirm gate: cost + codes, no inline preview
+
+Motion transfer is mechanical — the model deterministically applies source motion to target image. Both tiers trip the >$0.50 confirm gate; the response includes the asset codes for source and target so you can announce them in chat.
+
+- ✅ "Transferring motion from **VID-V3** onto **IMG-A12 — Detective Closeup**. $1.26, confirm?"
+- ❌ "Using the walk video and the detective image..." (multiple of each in the project.)
+
+Don't second-guess the assets the user picked — the model executes the transfer. If the output is wrong, iterate on motion source or target choice, not on a refinement prompt.
+
+## Sources
+
+- [fal.ai — Kling Motion Control V3 Standard](https://fal.ai/models/fal-ai/kling-video/v3/standard/motion-control)
+- [fal.ai — Kling Motion Control V3 Pro](https://fal.ai/models/fal-ai/kling-video/v3/pro/motion-control)