# Video Generation: Models, Prompting & Scene Chaining

## Script Planning

For longer, cohesive videos, plan the FULL SCRIPT before generating:

### 1. Scene Breakdown
- **Scenes:** break story into segments
  - Sora: 4 / 8 / 12 seconds per scene
  - Veo: 4-8 seconds per scene
  - Seedance: 4-15 seconds per scene (native audio with lip-sync)
- **Camera:** shot type (wide, close-up, tracking), angles, movement
- **Transitions:** how each scene connects to the next
- **Consistency:** character descriptions, color palette, visual style

## Scene Chaining Technique

To create seamless multi-scene videos:

### Scene 1 (text-to-video)

```python
videos_generate(prompt="...", model="veo-3.1-generate-preview")
```

### Scene 2+ (image-to-video)

```python
videos_frames_capture(video_file_id="scene1_file_id", frame_position="last")
videos_generate(prompt="continuation: ...", image_file_id="captured_frame_id")
```

Repeat: extract last frame → generate next scene.

### Stitching Scenes Together

After generating all scenes, combine them:

```python
videos_stitch(video_file_ids=["scene1_id", "scene2_id", "scene3_id"])

videos_stitch(
    video_file_ids=["scene1_id", "scene2_id", "scene3_id"],
    transition="crossfade",
    crossfade_duration=0.5,
)
```

## Prompt Structure

Each scene prompt should include:

- "Continuation of previous scene" (for scenes 2+)
- Consistent character / setting descriptions
- Specific action for this segment
- Camera movement direction

## Control Principles (most important)

- Treat API params as the **container** and prompt text as the **content**:
  - `model`, `size` / `aspect_ratio`, and `duration_seconds` must be set explicitly in the tool call.
  - Do not expect prose like "make it longer" or "make it vertical" to override API parameters.
- Use detail for control, brevity for exploration:
  - Short prompts give more creative variation.
  - Detailed prompts improve consistency and shot control.
- Iterate in small steps:
  - Change one major variable at a time (camera, lighting, action, or palette).
  - Keep what works fixed and only modify the target dimension.

## Key Parameters

| Parameter | Description |
|-----------|-------------|
| `image_file_id` | Use for image-to-video (scene continuity) |
| `videos_frames_capture` | Extract frames with `frame_position="last"` \| `"first"` \| `"middle"` |
| `size` | For Sora only. One of: `"720x1280"`, `"1280x720"`, `"1024x1792"`, `"1792x1024"` |
| `aspect_ratio` | For Veo only. One of: `"16:9"` or `"9:16"` |
| `duration_seconds` | Sora: 4, 8, or 12 seconds only. Veo: 4-8 seconds |

## Important Input Rules

- Use exact values accepted by the tool schema. Do not send aliases like `landscape`, `portrait`, `720p`, or `1080p`.
- For Sora, prefer `size` and do not send `aspect_ratio`.
- For Veo, prefer `aspect_ratio` and do not send `size`.
- For Seedance, use `aspect_ratio` and optionally `resolution`. Do not pass `size`.
- Keep the same `size` / `aspect_ratio` across chained scenes for continuity.

## Model Selection Guide

**When the user mentions a specific model name, always use that model.** Map user requests to the correct `model` parameter:

| User says | `model` parameter |
|-----------|-------------------|
| "use seedance", "seedance video" | `"seedance-2"` |
| "fast seedance" | `"seedance-2-fast"` |
| "use sora", "sora video" | `"sora-2"` |
| "sora pro" | `"sora-2-pro"` |
| "use veo", "veo video" | `"veo-3.1-generate-preview"` |
| "fast veo" | `"veo-3.1-fast-generate-preview"` |

## Model-Specific Parameter Matrix

- **Sora models (`sora-2`, `sora-2-pro`)**
  - Allowed sizing parameter: `size`
  - Allowed `size` values: `"720x1280"`, `"1280x720"`, `"1024x1792"`, `"1792x1024"`
  - Do not pass `aspect_ratio`
  - Practical default pair: `"1280x720"` or `"720x1280"`
- **Veo models (`veo-3.1-generate-preview`, `veo-3.1-fast-generate-preview`)**
  - Allowed sizing parameter: `aspect_ratio`
  - Allowed `aspect_ratio` values: `"16:9"`, `"9:16"`
  - Do not pass `size`
- **Seedance models (`seedance-2`, `seedance-2-fast`)**
  - Allowed sizing parameters: `aspect_ratio` and `resolution`
  - Allowed `aspect_ratio` values: `"16:9"`, `"9:16"`, `"1:1"`, `"4:3"`, `"3:4"`
  - Allowed `resolution` values: `"480p"`, `"720p"`
  - Supports `generate_audio=true` for native audio with lip-sync
  - Do not pass `size`

## Duration Limits

- **Sora:** 4, 8, or 12 seconds per generation. Use scene chaining + `videos_stitch` for longer videos.
- **Veo:** 4, 5, 6, 7, or 8 seconds per generation.
- **Seedance:** 4-15 seconds per generation (most flexible). Supports `generate_audio=true` for native audio with lip-sync.

## High-Control Prompt Template

Use this structure when you want predictable output:

```text
Style/Tone: [realistic, cinematic, animation, documentary, etc.]
Subject/World: [who/what is in frame, key visual anchors]
Camera: [shot size + angle + movement]
Lighting/Palette: [light direction + 3-5 color anchors]
Action Beats:
- [beat 1 with timing/count]
- [beat 2 with timing/count]
- [beat 3 with timing/count]
Audio/Dialogue: [short lines or ambient cues]
Constraints: [no logos/brands, no text overlays, etc.]
```

# Video Generation: Post-Production (Subtitles, Audio, Overlays, Clipping)

## Subtitle / Caption Workflow

### Full pipeline: Video → Transcript → Subtitles → Burned Video

```python
transcript = videos_transcribe(file_id="video_file_id")

subs = videos_subtitles_generate(file_id="video_file_id", transcript=transcript, format="srt")

videos_subtitles_burn(
    video_file_id="video_file_id",
    subtitle_file_id=subs.file_id,
    style="bold_outline",
    position="bottom",
)
```

### Subtitle Styles

| Style | Effect |
|-------|--------|
| `default` | Plain white text |
| `bold_outline` | Bold white with black outline (recommended) |
| `shadow` | White text with drop shadow |
| `box` | White text on semi-transparent black box |

## Text Overlays

Add titles, lower-thirds, CTAs, and other graphics:

```python
videos_text_overlays_add(
    video_file_id="video_file_id",
    overlays=[
        {
            "text": "Episode 1: The Beginning",
            "start_time": 0.0,
            "end_time": 3.0,
            "position": "center",
            "font_size": 48,
            "color": "white",
            "background": "black@0.5",
        },
        {
            "text": "Subscribe for more!",
            "start_time": 10.0,
            "end_time": 14.0,
            "position": "bottom-right",
            "font_size": 28,
        },
    ],
)
```

### Overlay Positions

`top`, `bottom`, `center`, `top-left`, `top-right`, `bottom-left`, `bottom-right`

## Voiceover / Narration

Generate natural-sounding voiceover with TTS and add it to any video:

```python
audio = audio_speech_generate(
    text="Welcome to our product. Here's how it works...",
    voice="nova",
    model="tts-1",
)

videos_audio_add(
    video_file_id="video_id",
    audio_file_id=audio.file_id,
    mode="replace",
)

videos_audio_add(
    video_file_id="video_id",
    audio_file_id=audio.file_id,
    mode="mix",
    audio_volume=0.8,
)
```

### Available Voices

`alloy`, `ash`, `coral`, `echo`, `fable`, `nova` (recommended), `onyx`, `sage`, `shimmer`

## Highlighted Captions (TikTok / Reels Style)

Add word-by-word highlighted captions that light up as spoken:

```python
videos_captions_burn_highlighted(
    video_file_id="video_id",
    style="tiktok",
    highlight_color="#3B82F6",
    base_color="white",
    words_per_group=3,
    position="center",
)

videos_captions_burn_highlighted(
    video_file_id="video_id",
    style="karaoke",
    highlight_color="yellow",
    base_color="white",
    background="black@0.6",
    words_per_group=4,
    position="bottom",
)
```

## Video Clipping

Extract segments from longer videos:

```python
videos_clips_extract(
    video_file_id="long_video_id",
    start_time=45.0,
    end_time=60.0,
)
```

# UGC Video Reference

Use `ugc_videos_create` for any of: TikTok/UGC ads, continuous POV creator videos, how-to/tutorial videos, unboxings, routines, before/after demos, product showcases, product reviews, testimonials, TV spots, "wild card" scroll-stoppers, or virtual try-ons. The tool wraps prompt structure, model selection, and product/avatar reference handling.

## Modes

| Mode | Structure | Default aspect | Default duration |
|------|-----------|----------------|------------------|
| `ugc` | casual presenter-to-camera product mention | 9:16 | 8s |
| `ugc_how_to` | quick tutorial with visible steps | 9:16 | 8s |
| `ugc_unboxing` | package reveal + first impression close-ups | 9:16 | 8s |
| `product_showcase` | polished product-first highlight (cinematic) | 16:9 | 12s |
| `product_review` | presenter opinion + proof point | 9:16 | 8s |
| `tv_spot` | broadcast-style ad with cinematic polish | 16:9 | 12s |
| `wild_card` | unexpected visual hook around the product | 9:16 | 8s |
| `ugc_virtual_try_on` | organic mirror/handheld try-on | 9:16 | 8s |
| `virtual_try_on` | polished model-led try-on | 9:16 | 8s |

Each mode declares required beats and default camera + voice. Override with `aspect_ratio`, `duration_seconds`, `camera`, and `voice_style`.

## Backend selection

Default generation uses `veo-3.1-fast-generate-preview`. Pass `model` explicitly when you need a different backend:

- `model="veo-3.1-fast-generate-preview"`: default, fastest Veo route
- `model="veo-3.1-generate-preview"`: higher-quality Veo route
- `model="sora-2"` or `model="sora-2-pro"`: OpenAI Sora route
- `model="seedance-2"` or `model="seedance-2-fast"`: Seedance route

Explicit `model` selection always wins. The tool no longer switches to Sora just because voice or background sound is requested.

## Style templates

Use `style_template` for machine-friendly TikTok/social formats:

| Template | Use when |
|----------|----------|
| `tiktok_ugc` | General TikTok/Reels creator ad |
| `continuous_pov` | One continuous selfie/POV video without abrupt product-only cutaways |
| `creator_review` | Creator opinion with a proof point |
| `unboxing` | Package opening and first impression |
| `routine` | Product inside a daily routine |
| `before_after` | Before/result proof format |
| `problem_solution` | Quick problem then product solution |
| `how_to` | Short tutorial with visible steps |
| `testimonial` | Sincere creator testimonial |
| `product_demo` | Product function demo with creator context |
| `trend_remix` | Trend-inspired format anchored to the product benefit |

## Beat fields

Pass any of these to override mode defaults:

- `hook` — opening line
- `setting` — scene/setting description
- `action` — what happens / demonstration
- `emotion` — emotional tone
- `voice_style` — voiceover or presenter style
- `background_sound` — ambient sound or music
- `camera` — camera/framing notes
- `cta` — closing call-to-action

## Inputs

- `product` — `ProductContext` (product name, brand, references for image-to-video)
- `avatars` — `list[MediaInput]` of presenter references; the strongest one becomes the start frame for image-to-video
- `avatar_file_id` or `avatar_url` — direct presenter/start-frame avatar reference for CLI-friendly calls

## Example

```python
ugc_videos_create(
    product=ProductContext(
        name="Ember Travel Mug",
        category="insulated travel mug",
        references=[MediaInput(file_id="file_image_gen_..._mug")],
    ),
    avatars=[MediaInput(file_id="file_image_gen_..._presenter")],
    style_template="unboxing",
    model="veo-3.1-fast-generate-preview",
    hook="I just got this mug and the packaging already feels premium",
    action="Opens the mailer, reveals the mug, shows the leakproof lid",
    emotion="Excited but natural first impression",
    voice_style="conversational, unscripted",
    background_sound="quiet kitchen ambience",
    cta="Try it for your morning commute",
    duration_seconds=8,
)
```

The result is a `UGCVideoResponse` with:
- `operation_id` (chat UI and Prefab compiler self-poll via `videos_status_check`)
- `mode`, `style_template`, `product_name`, `hook` (rendered above the video)
- `storyboard` and `compiled_prompt` (so the chat card can show the structure)

# Video Prompting (per backend)

Each video backend rewards a different prompt structure. When calling `videos_generate` directly (not via `ugc_videos_create`), shape the prompt to the model you're using.

## Sora (`sora-2`, `sora-2-pro`)
- Shape: storyboard scene with action beats.
- Required sections: subject/scene → action beats → camera/framing → lighting/palette → audio/dialogue.
- Avoid: vague style stacks, asking for duration/aspect in prose, more than ~2 scene changes in one clip.

## Veo (`veo-3.1-generate-preview`, `veo-3.1-fast-generate-preview`)
- Shape: a single clear scene.
- Required sections: shot → scene → character details → action → lighting → style (+ optional dialogue).
- Avoid: ambiguous subjects, multiple unrelated events, quoted dialogue syntax (just write what's said).

## Seedance (`seedance-2`, `seedance-2-fast`)
- Shape: shot type, subject, what moves, environment, camera, lighting/style.
- Required sections: shot_type → subject → motion → environment → camera → lighting_style.
- Cap camera moves at 2 per clip. One strong subject per clip.
- Avoid: rewriting everything during iteration — change one variable at a time.

## Kling (image-to-video)
- Shape: motion only.
- Required sections: camera_move → action_beats → ambient_motion.
- Do not redescribe what's in the input image — clothing, appearance, product details. The image already carries that.
- Avoid: complex cinematic jargon, competing visual instructions.

## Universal rules

- Keep model-specific sizing parameters consistent: Sora uses `size` (e.g. `1280x720`), Veo and Seedance use `aspect_ratio` (e.g. `16:9`).
- Don't pass `aspect_ratio` to Sora or `size` to Veo/Seedance.
- For chained scenes, capture the last frame and pass it as `image_file_id` in the next call.

# Video Generation: End-to-End Production Workflows

## UGC / TikTok Production Workflow

Complete workflow for producing UGC-style content:

1. **Script:** plan scenes, dialogue, and visual style
2. **Generate:** create each scene with `videos_generate`
3. **Review:** use `videos_analyze` to check each scene for quality
4. **Chain:** extract last frames with `videos_frames_capture`, generate next scenes
5. **Stitch:** combine all scenes with `videos_stitch`
6. **Narrate:** generate voiceover with `audio_speech_generate` + `videos_audio_add`
7. **Caption:** add TikTok-style captions with `videos_captions_burn_highlighted`
8. **Overlay:** add titles / CTAs with `videos_text_overlays_add`
9. **Final review:** use `videos_analyze` on the final video for quality check

### Example: Narrated UGC Video

```python
videos_generate(prompt="...", model="veo-3.1-generate-preview")

audio = audio_speech_generate(text="Your narration script here...", voice="nova")

videos_audio_add(video_file_id="generated_video_id", audio_file_id=audio.file_id)

videos_captions_burn_highlighted(video_file_id="narrated_video_id", style="tiktok")
```

### Example: Podcast to Short-Form Clips

```python
transcript = videos_transcribe(file_id="podcast_video_id")

analysis = videos_analyze(
    file_id="podcast_video_id",
    question="Identify the 3 most memorable / quotable moments with timestamps",
    analysis_type="scene_breakdown",
)

videos_clips_extract(video_file_id="podcast_video_id", start_time=120.0, end_time=150.0)
videos_clips_extract(video_file_id="podcast_video_id", start_time=340.0, end_time=365.0)

videos_stitch(video_file_ids=["clip1_id", "clip2_id"])

videos_captions_burn_highlighted(video_file_id="stitched_id", style="tiktok")
```