# Find via Glob tool
glob: .cursor/skills/seedance2-api/scripts/seedance_api.py

See [reference.md](reference.md) for detailed templates and examples.

## Step 4: Generate Reference Images (If Needed)

If the user has no existing assets, use Seedream 4.5 to generate character art, scenes, first/last frames, etc.

### Text-to-Image

<details>
<summary><b>MCP Method</b></summary>

Call `submit_task` tool:
- model_id: `fal-ai/bytedance/seedream/v4.5/text-to-image`
- parameters:
  - prompt: detailed image description (English works best)
  - image_size: choose based on video aspect ratio
  - num_images: number needed (1–6)

</details>

<details>
<summary><b>Script Method</b></summary>

</details>

### Image Editing (Modify Existing Images)

<details>
<summary><b>MCP Method</b></summary>

Call `submit_task` tool:
- model_id: `fal-ai/bytedance/seedream/v4.5/edit`
- parameters:
  - prompt: editing instructions (use Figure 1/2/3 to reference images)
  - image_urls: array of input image URLs
  - image_size: output size

</details>

<details>
<summary><b>Script Method</b></summary>

</details>

### Poll Image Results

Images typically complete in 1–2 minutes.

<details>
<summary><b>MCP Method</b></summary>

Call `get_task` tool to check status:
- First query after 30 seconds
- Then every 30 seconds
- Extract image URL when status is `completed`

</details>

<details>
<summary><b>Script Method</b></summary>

**Single query:**

</details>

### image_size Reference

| Aspect Ratio | Recommended image_size | Note |
|--------------|------------------------|------|
| 16:9 | landscape_16_9 | Landscape |
| 9:16 | portrait_16_9 | Portrait |
| 4:3 | landscape_4_3 | Landscape |
| 3:4 | portrait_4_3 | Portrait |
| 1:1 | square_hd | Square |
| 21:9 | landscape_16_9 | Approximate ultrawide |

## Step 5: Compose the Final Prompt

Merge the storyboard structure and reference images into the final prompt:

- Use `@image_file_1`, `@image_file_2`, etc. to reference images in the image_files array
- Use `@video_file_1`, etc. to reference videos in the video_files array
- Use `@audio_file_1`, etc. to reference audio in the audio_files array

**Reference syntax example:**

**Important:** The Nth URL in `image_files` maps to `@image_file_N`. `video_files` and `audio_files` are independently numbered.

## Step 6: Submit Video Task

**Handle asset URLs:**
- Seedream-generated images: URL already available, use directly
- User-provided web images: use directly
- User-provided local images: upload first to get URL (see upload methods below)

### Upload Local Images

<details>
<summary><b>MCP Method</b></summary>

Call `upload_image` tool: image_url or image_data

</details>

<details>
<summary><b>Script Method</b></summary>

</details>

### Submit Seedance 2.0 Task (Omni Reference Mode)

<details>
<summary><b>MCP Method</b></summary>

Call `submit_task` tool:
- model_id: `st-ai/super-seed2`
- parameters:
  - prompt: the full prompt from Step 5
  - functionMode: `omni_reference` (default, can be omitted)
  - image_files: reference image URL array (up to 9, order matches @image_file_1/2/3...)
  - video_files: reference video URL array (up to 3, total duration ≤ 15s)
  - audio_files: reference audio URL array (up to 3)
  - ratio: aspect ratio (`16:9` / `9:16` / `1:1` / `21:9` / `4:3` / `3:4`)
  - duration: integer length (`4`–`15`)
  - model: `seedance_2.0_fast` (default, faster) or `seedance_2.0` (standard quality)

</details>

<details>
<summary><b>Script Method</b></summary>

</details>

### Submit Seedance 2.0 Task (First & Last Frames Mode)

<details>
<summary><b>MCP Method</b></summary>

Call `submit_task` tool:
- model_id: `st-ai/super-seed2`
- parameters:
  - prompt: video description prompt
  - functionMode: `first_last_frames`
  - filePaths: image URL array (0 = text-to-video, 1 = first frame, 2 = first & last frames)
  - ratio: aspect ratio
  - duration: integer length
  - model: `seedance_2.0_fast` or `seedance_2.0`

</details>

<details>
<summary><b>Script Method</b></summary>

</details>

## Step 7: Poll for Video Results

Video generation takes approximately 10 minutes.

<details>
<summary><b>MCP Method</b></summary>

Polling strategy:
1. After submission, inform the user: "Video is generating, estimated ~10 minutes"
2. First query after **60 seconds** via `get_task`
3. Then every **90 seconds**
4. Report status to the user after each query

</details>

<details>
<summary><b>Script Method</b></summary>

**Recommended: auto-poll (runs in foreground, interval 30s, timeout 600s):**

Progress is printed to stderr; final JSON result is printed to stdout when complete.

**Manual single query:**