### Workflow Guide Documentation

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

A comprehensive guide to step-by-step workflows, covering setup, use case understanding, five generation workflows (A-E), advanced features, troubleshooting, and best practices. Includes an end-to-end example with output.

```markdown
workflow-guide.md (18 KB)
  - Complete step-by-step workflows
  - Phase 1: Setup & Configuration
  - Phase 2: Understanding your use case
  - Phase 3: Five generation workflows (A-E)
  - Phase 4: Advanced features (batch, audio, multiple images)
  - Phase 5: Troubleshooting
  - Phase 6: Best practices
  - End-to-end example with output
```

--------------------------------

### Complete Setup for Script Mode with Verification

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/configuration.md

This example demonstrates setting the XSKILL_API_KEY and then verifying the setup by running a balance check command. It's useful for ensuring your script mode is correctly configured.

```bash
# 1. Set API key
export XSKILL_API_KEY="sk-proj_abc123def456..."

# 2. Verify setup (optional)
python .cursor/skills/seedance2-api/scripts/seedance_api.py balance

# Output should show:
# Balance Information
# Balance: 1250.50 credits
# Monthly Usage: 749.50 credits
# Plan: pro
```

--------------------------------

### README.md Overview

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

The README.md file provides an overview, quick start guide, common tasks, patterns, and constraints. It also includes integration examples for Claude Code, Python, and Bash, along with support resources and API stability notes.

```markdown
README.md (11 KB)
  - Overview, quick start, common tasks, patterns, constraints
  - Integration examples (Claude Code, Python, Bash)
  - Support resources and API stability notes
```

--------------------------------

### Configuration.md Details

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Configuration.md covers environment variables such as XSKILL_API_KEY and SEEDANCE_API_KEY. It explains execution mode detection (MCP vs Script) and provides setup examples for Bash, Docker, and CI/CD, along with polling configuration and troubleshooting.

```markdown
configuration.md (5.9 KB)
  - Environment variables (XSKILL_API_KEY, SEEDANCE_API_KEY)
  - Execution mode detection (MCP vs Script)
  - Setup examples for Bash, Docker, CI/CD
  - Polling configuration and troubleshooting
```

--------------------------------

### Text-to-Image Prompt Example

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/workflow-guide.md

Example of a detailed text prompt for generating an image. Focus on subject, action, setting, and style.

```text
"A serene mountain landscape at sunset, golden light,
 calm lake reflection, misty atmosphere, oil painting style"
```

--------------------------------

### First Frame Only Video Generation

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

This example generates a video starting from a specified first frame. The `filePaths` array should contain only the URL of the first frame.

```python
submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "prompt": "Camera smoothly zooms out, character walks away",
    "functionMode": "first_last_frames",
    "filePaths": ["https://cdn.example.com/first_frame.png"],
    "ratio": "16:9",
    "duration": 8,
    "model": "seedance_2.0_fast"
  }
)
```

--------------------------------

### Install requests library

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/tools-and-commands.md

Ensure the Python requests library is installed for script execution.

```bash
# Verify requests library
pip install requests
```

--------------------------------

### Generate Video with Python Client

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/README.md

Submit a video generation task using the Python client. This example shows how to initialize the client and submit a task with parameters.

```python
from xskill_api import Client

client = Client(api_key=os.environ["XSKILL_API_KEY"])

task = client.submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "prompt": "A cat playing with a ball",
    "ratio": "16:9",
    "duration": 10
  }
)

# Poll and retrieve
```

--------------------------------

### Balance Information Response

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Example JSON response from the `get_balance` tool.

```json
{
  "balance": 1250.50,
  "currency": "credits",
  "usage_this_month": 749.50,
  "plan": "pro"
}
```

--------------------------------

### Task Usage Example

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/types.md

Demonstrates how to submit a task and retrieve its ID, status, and creation timestamp. Also shows how to query for task results or errors based on the status.

```python
# After submitting a task
task = submit_task(model_id="st-ai/super-seed2", parameters={...})
print(task["task_id"])
print(task["status"])
print(task["created_at"])

# When querying for results
result = get_task(task["task_id"])
if result["status"] == "completed":
  print(result["result"]["video_url"])
elif result["status"] == "failed":
  print(result["error"]["message"])
```

--------------------------------

### Balance Information Script Mode Response

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Example console output for account balance when using the script mode.

```text
Balance Information
Balance: 1250.50 credits
Monthly Usage: 749.50 credits
Plan: pro
```

--------------------------------

### Example Good Prompt for Image/Video Generation

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/workflow-guide.md

This prompt demonstrates how to specify cinematic style, duration, aspect ratio, reference assets, camera movement, lighting, and audio.

```text
Cinematic cinematic sci-fi style, 15 seconds, 16:9. 
@image_file_1 as main character in white spacesuit. 
Character walks across alien landscape with bioluminescent plants.
Camera follows character with smooth tracking motion.
Dramatic golden and blue lighting, volumetric atmosphere.
@audio_file_1 plays as epic background music.
```

--------------------------------

### Submit Task with Multiple Assets

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

This example demonstrates submitting a task with multiple image, video, and audio assets. Use distinct placeholders like `@image_file_1`, `@video_file_1`, and `@audio_file_1` in the prompt to reference these assets.

```python
submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "prompt": "Animation style, underwater scene. @image_file_1 as main character, @image_file_2 as coral formation backdrop. Follow @video_file_1 camera movement. @audio_file_1 plays as ambient music. Character gracefully swims through coral, light rays penetrate from above",
    "functionMode": "omni_reference",
    "image_files": [
      "https://cdn.example.com/character.png",
      "https://cdn.example.com/coral.png"
    ],
    "video_files": ["https://cdn.example.com/camera_move.mp4"],
    "audio_files": ["https://cdn.example.com/ambient.mp3"],
    "ratio": "16:9",
    "duration": 10,
    "model": "seedance_2.0"
  }
)
```

--------------------------------

### Submit Task via Command Line

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

This command-line example shows how to submit a video generation task using the provided Python script. The parameters are passed as a JSON string.

```bash
python .cursor/skills/seedance2-api/scripts/seedance_api.py submit \
  --model "st-ai/super-seed2" \
  --params '{ \
    "prompt": "Cinematic sci-fi, @image_file_1 as astronaut walking on Mars...", \
    "functionMode": "omni_reference", \
    "image_files": ["https://cdn.example.com/astronaut.png"], \
    "ratio": "16:9", \
    "duration": 15, \
    "model": "seedance_2.0_fast" \
  }'
```

--------------------------------

### Omni Reference Mode API Response Example

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

An example JSON response after submitting a task for video generation in omni reference mode. It includes the task ID and submitted parameters.

```json
{
  "task_id": "string",
  "status": "pending",
  "model_id": "st-ai/super-seed2",
  "created_at": "2026-06-04T00:00:00Z",
  "parameters": {
    "prompt": "Cinematic sci-fi style...",
    "functionMode": "omni_reference",
    "image_files": ["https://cdn.example.com/img1.png"],
    "video_files": [],
    "audio_files": [],
    "ratio": "16:9",
    "duration": 15,
    "model": "seedance_2.0_fast"
  }
}
```

--------------------------------

### Generate Reference Images for Video Workflow

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/README.md

Generate reference images using the text-to-image model as the first step in a two-stage video generation workflow. This example demonstrates submitting a task for image generation.

```python
# 1. Generate reference images
img_task = submit_task(
  model_id="fal-ai/bytedance/seedream/v4.5/text-to-image",
  parameters={"prompt": "Astronaut on Mars", "image_size": "landscape_16_9"}
)

```

--------------------------------

### Bash Error Handling Example

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Example demonstrating error handling in Bash for API interactions. This snippet would typically be found within the 'errors.md' file.

```bash
API_URL="http://example.com/api/v1/tasks"
PAYLOAD='{"prompt": "A futuristic city"}'

response=$(curl -s -w "\n%{http_code}" -X POST -H "Content-Type: application/json" -d "$PAYLOAD" "$API_URL")
http_code=$(echo "$response" | tail -n 1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
    echo "Success: $body"
else
    echo "Error: HTTP Status Code $http_code"
    echo "Response Body: $body"
    # Parse JSON body for specific error details if needed
fi

```

--------------------------------

### Submit Task with Uploaded Image URL

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Example of submitting a task using the URL returned from an image upload.

```python
submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "image_files": [result["url"]],  # Use returned URL
    ...
  }
)
```

--------------------------------

### Install Seedance 2.0 API Skill

Source: https://github.com/hexiaochun/seedance2-api/blob/main/README.md

Use this command to add the Seedance 2.0 API skill to your project. This command is compatible with various AI agents.

```bash
npx skills add https://github.com/hexiaochun/seedance2-api --skill seedance2-api
```

--------------------------------

### Task Status Response (Completed)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Example JSON response when a task has successfully completed. Includes the result, such as a video URL.

```json
{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "model_id": "st-ai/super-seed2",
  "created_at": "2026-06-04T12:30:45Z",
  "result": {
    "video_url": "https://cdn.example.com/video_output.mp4",
    "duration": 10,
    "ratio": "16:9",
    "file_size_mb": 124.5
  }
}
```

--------------------------------

### Test Seedance API Balance (Script Mode)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/workflow-guide.md

Run a Python script to check your account balance and plan details using the Seedance API. This verifies the API setup.

```bash
python .cursor/skills/seedance2-api/scripts/seedance_api.py balance
# Output should show account balance and plan
```

--------------------------------

### TaskResult Usage Examples

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/types.md

Illustrates how to access results for different task types. For text-to-image tasks, it shows iterating through image URLs and sizes. For video generation, it displays the video URL, duration, and file size.

```python
# Text-to-image result
result = get_task("task_image123")
if result["status"] == "completed":
  for image in result["result"]["images"]:
    print(f"Image: {image['url']}")
    print(f"Size: {image['size']}")

# Video generation result
result = get_task("task_video123")
if result["status"] == "completed":
  print(f"Video: {result['result']['video_url']}")
  print(f"Duration: {result['result']['duration']}s")
  print(f"Size: {result['result']['file_size_mb']}MB")
```

--------------------------------

### Task Status Response (Pending/Processing)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Example JSON response when a task is still pending or processing. Includes current progress if available.

```json
{
  "task_id": "task_abc123xyz",
  "status": "processing",
  "model_id": "st-ai/super-seed2",
  "created_at": "2026-06-04T12:30:45Z",
  "progress": 45
}
```

--------------------------------

### Task Status Check Example

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/types.md

Shows how to check the status of a task and handle different outcomes, such as displaying results for completed tasks, error messages for failed tasks, or progress for processing tasks.

```python
task = get_task("task_xyz123")

if task["status"] == "completed":
  print("Done!")
  image_urls = task["result"]["images"]
elif task["status"] == "failed":
  print(f"Error: {task['error']['message']}")
elif task["status"] == "processing":
  print(f"Progress: {task.get('progress', 'unknown')}%" )
```

--------------------------------

### Submit Task in Omni Reference Mode

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/types.md

Submits a task using the 'omni_reference' function mode, allowing flexible use of image and audio reference files. Demonstrates parameter setup.

```python
# Omni reference mode
submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "prompt": "@image_file_1 as character, @audio_file_1 as music",
    "functionMode": "omni_reference",
    "image_files": ["https://..."],
    "audio_files": ["https://..."]
  }
)
```

--------------------------------

### Image Editing and Enhancement (seedream-image-editing)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Documentation for the image editing and enhancement model. Covers figure reference syntax, error handling, limitations, and usage examples.

```APIDOC
## Image Editing and Enhancement

### Description
Edits and enhances existing images using the fal-ai/bytedance/seedream/v4.5/edit model.

### Parameters
Supports figure reference syntax for multiple images. Refer to `types.md` for data structures and `endpoints.md` for formats.

### Error Handling
Refer to `errors.md` for detailed error codes, trigger conditions, and recovery strategies.

### Limitations
Refer to `endpoints.md` for known limitations.

### Usage Examples
Refer to `endpoints.md` for complete usage examples.
```

--------------------------------

### Example: Rate Limiting with Task Polling

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/errors.md

This Python code demonstrates how to handle rate limiting by ensuring a minimum delay between task queries. It waits for a specified duration if the time since the last query is less than the limit.

```python
import time

task = submit_task(...)  # Returns task_id
last_query = time.time()

while True:
  # Rate limit: wait at least 30 seconds between queries
  now = time.time()
  if now - last_query < 30:
    time.sleep(30 - (now - last_query))
  
  result = get_task(task["task_id"])
  last_query = time.time()
  
  if result["status"] in ["completed", "failed"]:
    break
```

--------------------------------

### INDEX.md Navigation

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

INDEX.md serves as a complete navigation guide and search index. It supports task-based lookup, details file organization and key concepts, and provides quick links to all resources.

```markdown
INDEX.md (11 KB)
  - Complete navigation guide and search index
  - Task-based lookup (I want to...)
  - File organization and key concepts
  - Quick links to all resources
```

--------------------------------

### Adhering to Maximum Video Duration Limit

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/errors.md

Provides examples for the 'max_video_duration_exceeded' error, ensuring the combined duration of all reference videos does not surpass 15 seconds. Use this when the total video length exceeds the limit.

```python
# Wrong - 20 seconds total
submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "video_files": [
      "video1.mp4",  # 8 seconds
      "video2.mp4",  # 7 seconds
      "video3.mp4"   # 5 seconds
      # Total: 8 + 7 + 5 = 20 > 15
    ]
  }
)

# Correct - 15 seconds total
submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "video_files": [
      "video1.mp4",  # 8 seconds
      "video2.mp4",  # 7 seconds
      # Total: 8 + 7 = 15 = limit
    ]
  }
)
```

--------------------------------

### Python Error Handling Example

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Example demonstrating error handling in Python for API interactions. This snippet would typically be found within the 'errors.md' file.

```python
import requests

try:
    response = requests.post(API_URL, json=payload)
    response.raise_for_status()  # Raise an exception for bad status codes
    result = response.json()
except requests.exceptions.RequestException as e:
    print(f"An error occurred: {e}")
    # Handle specific error codes or types here
    if hasattr(e, 'response') and e.response is not None:
        error_data = e.response.json()
        print(f"API Error: {error_data.get('code')}: {error_data.get('message')}")

```

--------------------------------

### Setting XSKILL_API_KEY for Authentication

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/errors.md

Shows how to set the `XSKILL_API_KEY` environment variable for script mode authentication. This is crucial for resolving 'authentication_failed' errors.

```bash
# Verify XSKILL_API_KEY is set:
# echo $XSKILL_API_KEY

# If empty, set it:
# export XSKILL_API_KEY="sk-your-key"
```

--------------------------------

### Completed Task Status Response

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Example response when a task has successfully completed.

```text
Task ID: task_abc123xyz
Status: completed
Result:
{
  "video_url": "https://cdn.example.com/video_output.mp4",
  "duration": 10,
  "ratio": "16:9",
  "file_size_mb": 124.5
}
```

--------------------------------

### Tools and Commands Documentation

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Documentation for MCP tools (submit_task, get_task, upload_image, get_balance) and Script commands (submit, query, poll, upload, balance). Includes parameter tables, response formats, and execution mode detection logic.

```markdown
tools-and-commands.md (9.9 KB)
  - MCP tools: submit_task, get_task, upload_image, get_balance
  - Script commands: submit, query, poll, upload, balance
  - Parameter tables and response formats
  - Execution mode detection logic
```

--------------------------------

### Processing Task Status Response

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Example response when a task is still processing.

```text
Task ID: task_abc123xyz
Status: processing
Progress: 45%
Created: 2026-06-04T12:30:45Z
```

--------------------------------

### Set XSKILL_API_KEY if Empty

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/configuration.md

If the XSKILL_API_KEY is not set, use this command to export it. This is part of the troubleshooting process for configuration errors.

```bash
export XSKILL_API_KEY="sk-your-key"
```

--------------------------------

### Verify XSkill API Key Configuration

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/workflow-guide.md

Check if the XSKILL_API_KEY environment variable is set correctly by printing its first 20 characters.

```bash
echo $XSKILL_API_KEY | head -c 20
# Output should show first 20 chars of key
```

--------------------------------

### Verify XSKILL_API_KEY in a New Shell Session

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/configuration.md

After setting the XSKILL_API_KEY, open a new shell session and verify that the key is correctly loaded and accessible. This confirms persistent configuration.

```bash
bash
echo $XSKILL_API_KEY  # Should show your key
```

--------------------------------

### Task Status Response (Failed)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Example JSON response when a task has failed. Includes an error code and message.

```json
{
  "task_id": "task_abc123xyz",
  "status": "failed",
  "model_id": "st-ai/super-seed2",
  "created_at": "2026-06-04T12:30:45Z",
  "error": {
    "code": "invalid_prompt",
    "message": "Prompt contains unsupported content"
  }
}
```

--------------------------------

### Video Generation with Reference Images (MCP Mode)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

This Python snippet illustrates submitting a video generation task using reference images. It includes steps for checking balance, uploading reference images, and submitting the task with specific parameters.

```python
# Step 1: Check balance
balance = get_balance()
if balance["balance"] < 100:
  print(f"Low balance: {balance['balance']} credits")
  exit(1)

# Step 2: Upload reference images
print("Uploading reference images...")
ref1_result = upload_image(image_url="https://example.com/character.png")
ref2_result = upload_image(image_url="https://example.com/background.png")

print(f"Image 1: {ref1_result['url']}")
print(f"Image 2: {ref2_result['url']}")

# Step 3: Submit video task
print("Submitting video task with references...")
task = submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "prompt": "@image_file_1 as main character, @image_file_2 as background. Character walks through scene, camera pans smoothly, dynamic lighting",
    "functionMode": "omni_reference",
    "image_files": [ref1_result["url"], ref2_result["url"]],
    "ratio": "16:9",
    "duration": 10,
    "model": "seedance_2.0"
  }
)

print(f"Video task: {task['task_id']}")
print("Video is generating, estimated ~10 minutes...")

# Step 4: Poll (handled by application loop or auto-poll tool)
```

--------------------------------

### Get Task Status (Script Mode)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Retrieves the status and output of a previously submitted task using its unique identifier.

```APIDOC
## Get Task Status (Script Mode)

### Description
Retrieves the status and output of a previously submitted task using its unique identifier.

### Method
`query` (Command-line script)

### Endpoint
`python .cursor/skills/seedance2-api/scripts/seedance_api.py query --task-id "task_id"`

### Parameters
#### Path Parameters
None

#### Query Parameters
* `--task-id` (string) - Required - Task identifier from `submit` command

### Request Example
```bash
python .cursor/skills/seedance2-api/scripts/seedance_api.py query --task-id "task_abc123xyz"
```

### Response
#### Success Response (Status: Processing)
- **Task ID** (string) - The identifier of the task.
- **Status** (string) - The current status of the task (e.g., 'processing').
- **Progress** (string) - The completion progress of the task (e.g., '45%').
- **Created** (string) - The timestamp when the task was created.

#### Success Response (Status: Completed)
- **Task ID** (string) - The identifier of the task.
- **Status** (string) - The current status of the task (e.g., 'completed').
- **Result** (object) - The result of the task, containing details like video URL, duration, ratio, and file size.

#### Response Example (Processing)
```
Task ID: task_abc123xyz
Status: processing
Progress: 45%
Created: 2026-06-04T12:30:45Z
```

#### Response Example (Completed)
```json
{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "result": {
    "video_url": "https://cdn.example.com/video_output.mp4",
    "duration": 10,
    "ratio": "16:9",
    "file_size_mb": 124.5
  }
}
```
```

--------------------------------

### Get Task Status (MCP Tool)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

Use this command with the MCP tool to retrieve the status of a specific video generation task.

```python
get_task(task_id="task_vid456")
```

--------------------------------

### End-to-End Video Generation Workflow

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/workflow-guide.md

This comprehensive Python script demonstrates the complete process of generating a 10-second video. It includes submitting a task for a reference image, polling for its completion, then submitting a video task using the reference image and audio, and finally polling for the video's completion.

```python
import time

# Step 1: Generate reference image of dancing cat
print("1. Generating cat character image...")
cat_task = submit_task(
  model_id="fal-ai/bytedance/seedream/v4.5/text-to-image",
  parameters={
    "prompt": "Orange tabby cat with expressive eyes, mid-dance pose, dynamic energy, 3D rendered style",
    "image_size": "landscape_16_9",
    "num_images": 1
  }
)

# Poll for image
while True:
  result = get_task(cat_task["task_id"])
  if result["status"] == "completed":
    cat_image_url = result["result"]["images"][0]["url"]
    print(f"   Cat image ready: {cat_image_url}")
    break
  elif result["status"] == "failed":
    print(f"   Failed: {result['error']['message']}")
    exit(1)
  time.sleep(10)

# Step 2: Submit video task with reference and audio
print("2. Generating video with music...")
video_task = submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "prompt": """Fun, colorful 3D animation style, 10 seconds, 16:9.
@image_file_1 as orange tabby cat dancing.
Cat spins and jumps to upbeat music, joyful expressions.
Bright, colorful background with light effects.
Camera zooms and pans following cat's movement.
@audio_file_1 plays as upbeat dance music.
Dynamic, playful energy throughout.""",
    "functionMode": "omni_reference",
    "image_files": [cat_image_url],
    "audio_files": ["https://cdn.example.com/upbeat-dance-music.mp3"],
    "ratio": "16:9",
    "duration": 10,
    "model": "seedance_2.0_fast"
  }
)

# Step 3: Poll for video
print("3. Generating video (estimated 10 minutes)...")
start = time.time()
while True:
  result = get_task(video_task["task_id"])
  elapsed = int(time.time() - start)
  
  if result["status"] == "completed":
    video_url = result["result"]["video_url"]
    size_mb = result["result"]["file_size_mb"]
    print(f"\n✓ Video ready!")
    print(f"   URL: {video_url}")
    print(f"   Size: {size_mb}MB")
    print(f"   Time taken: {elapsed}s")
    break
  elif result["status"] == "failed":
    print(f"\n✗ Failed: {result['error']['message']}")
    exit(1)
  else:
    progress = result.get("progress", "?")
    print(f"   [{elapsed}s] Status: {result['status']}, Progress: {progress}%")
    time.sleep(30)
```

--------------------------------

### Get Task Result

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

Retrieves the status and results of a previously submitted video generation task using its unique task ID.

```APIDOC
## GET /task/{task_id}

### Description
Queries the status and results of a video generation task. Use the task ID obtained from the submission response to track progress and retrieve the final video URL upon completion.

### Method
GET

### Endpoint
/task/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The unique identifier for the video generation task.

### Response
#### Success Response (Status: `pending` or `processing`)
- **task_id** (string) - The ID of the task.
- **status** (string) - The current status of the task (`pending`, `processing`).
- **progress** (integer) - The completion progress in percentage (0-100).

### Response Example (Processing)
```json
{
  "task_id": "task_vid456",
  "status": "processing",
  "progress": 62
}
```

#### Success Response (Status: `completed`)
- **task_id** (string) - The ID of the task.
- **status** (string) - The status of the task, which is `completed`.
- **result** (object) - Contains the details of the generated video.
  - **video_url** (string) - URL to the generated video file.
  - **duration** (integer) - Duration of the video in seconds.
  - **ratio** (string) - Aspect ratio of the video.
  - **file_size_mb** (number) - Size of the video file in megabytes.

### Response Example (Completed)
```json
{
  "task_id": "task_vid456",
  "status": "completed",
  "result": {
    "video_url": "https://cdn.example.com/output_video.mp4",
    "duration": 15,
    "ratio": "16:9",
    "file_size_mb": 124.5
  }
}
```

### Status Values
| Status | Meaning |
|--------|---------|
| `pending` | Task queued, waiting to start |
| `processing` | Video generation in progress |
| `completed` | Video generated successfully |
| `failed` | Task failed; check error details |
```

--------------------------------

### Get Task Result

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedream-text-to-image.md

Queries the status and results of a previously submitted text-to-image generation task using its unique task ID.

```APIDOC
## GET /task/{task_id}

### Description
Query the status and results of a submitted task.

### Method
GET

### Endpoint
/task/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The unique identifier of the task to query.

### Response
#### Success Response (200)
**When status is `pending` or `processing`:**
- **task_id** (string) - The task identifier.
- **status** (string) - The current status of the task (`pending` or `processing`).
- **progress** (integer) - The completion progress in percentage.

**When status is `completed`:**
- **task_id** (string) - The task identifier.
- **status** (string) - The task status, indicating `completed`.
- **result** (object) - Contains the generated images.
  - **images** (array) - A list of generated images.
    - **url** (string) - The URL to access the generated image.
    - **size** (string) - The resolution of the generated image (e.g., "1920x1080").

#### Response Example
**Pending/Processing:**
```json
{
  "task_id": "task_xyz123",
  "status": "processing",
  "progress": 45
}
```

**Completed:**
```json
{
  "task_id": "task_xyz123",
  "status": "completed",
  "result": {
    "images": [
      {
        "url": "https://cdn.example.com/image_001.png",
        "size": "1920x1080"
      }
    ]
  }
}
```

#### Error Response Example
```json
{
  "task_id": "task_xyz123",
  "status": "failed",
  "error": {
    "code": "invalid_prompt",
    "message": "Prompt contains unsupported content"
  }
}
```
```

--------------------------------

### Submit Task with Fast Seedance Model

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/types.md

Submits a task using the 'seedance_2.0_fast' model for quicker previews. Demonstrates setting the 'model' parameter for speed optimization.

```python
# Quick preview
submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "prompt": "...",
    "model": "seedance_2.0_fast"  # Default, faster
  }
)
```

--------------------------------

### Script Mode Error Response

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Example stderr output when a task submission fails in script mode. Indicates an error code and reason.

```bash
Error: invalid_prompt
Prompt violates content policy or is empty
```

--------------------------------

### Check Balance (Script Mode)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Execute the `balance` command to display account balance information in the console.

```bash
python .cursor/skills/seedance2-api/scripts/seedance_api.py balance
```

--------------------------------

### Get Task Status (MCP Mode)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Retrieves the status and results of a submitted task using the `get_task` tool. This is used in MCP mode.

```APIDOC
## Get Task Status (MCP Mode)

### Description
Retrieves the status and results of a submitted task using the `get_task` tool. This is used in MCP mode.

### Tool
`get_task`

### Signature
```
get_task(task_id: string) → Task
```

### Request Example
```python
result = get_task(task_id="task_abc123xyz")
```

### Response (Status: Pending/Processing)
```json
{
  "task_id": "task_abc123xyz",
  "status": "processing",
  "model_id": "st-ai/super-seed2",
  "created_at": "2026-06-04T12:30:45Z",
  "progress": 45
}
```

### Response (Status: Completed)
```json
{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "model_id": "st-ai/super-seed2",
  "created_at": "2026-06-04T12:30:45Z",
  "result": {
    "video_url": "https://cdn.example.com/video_output.mp4",
    "duration": 10,
    "ratio": "16:9",
    "file_size_mb": 124.5
  }
}
```

### Response (Status: Failed)
```json
{
  "task_id": "task_abc123xyz",
  "status": "failed",
  "model_id": "st-ai/super-seed2",
  "created_at": "2026-06-04T12:30:45Z",
  "error": {
    "code": "invalid_prompt",
    "message": "Prompt contains unsupported content"
  }
}
```

### Status Transitions
- `pending` → `processing` → `completed` or `failed` (terminal)

### Polling Strategy
- First query: Wait 30–60 seconds after submission
- Subsequent queries: Every 30 seconds (video) or 10 seconds (image)
- Timeout: 180–600 seconds depending on operation
```

--------------------------------

### Get Task Status (Completed)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

This JSON response signifies a completed video generation task. It includes the `video_url` and other metadata about the generated video.

```json
{
  "task_id": "task_vid456",
  "status": "completed",
  "result": {
    "video_url": "https://cdn.example.com/output_video.mp4",
    "duration": 15,
    "ratio": "16:9",
    "file_size_mb": 124.5
  }
}
```

--------------------------------

### Get Task Status (Processing)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

This JSON response indicates that a video generation task is currently in progress. The `progress` field shows the completion percentage.

```json
{
  "task_id": "task_vid456",
  "status": "processing",
  "progress": 62
}
```

--------------------------------

### Reference Assets in Prompts

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

Utilize this syntax within prompts to reference specific image, video, or audio files from provided arrays.

```plaintext
@image_file_1   → First image in image_files array
@image_file_2   → Second image in image_files array
@image_file_9   → Ninth image in image_files array
@video_file_1   → First video in video_files array
@audio_file_1   → First audio in audio_files array
```

```plaintext
@image_file_1 as main character, follow @video_file_1 camera movement, with @audio_file_1 as background music
```

--------------------------------

### Check account balance with get_balance MCP tool

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/tools-and-commands.md

Retrieve information about your remaining API credits, currency, monthly usage, and current plan.

```python
balance_info = get_balance()
print(f"Remaining balance: {balance_info['balance']} {balance_info['currency']}")
print(f"Usage this month: {balance_info['usage_this_month']}")
```

--------------------------------

### Submit Task with Reference Image

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

Use this snippet to generate a video using a reference image for character appearance. Ensure the image URL is correctly provided in `image_files`.

```python
submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "prompt": "Cinematic realistic sci-fi style, 15 seconds, 16:9. @image_file_1 as character reference, walking through a futuristic city with neon lights, smooth camera pan from left to right, morning light casting long shadows",
    "functionMode": "omni_reference",
    "image_files": ["https://cdn.example.com/astronaut.png"],
    "ratio": "16:9",
    "duration": 15,
    "model": "seedance_2.0_fast"
  }
)
```

--------------------------------

### Video Generation (seedance-video-generation)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Documentation for video generation, supporting two modes: omni_reference and first_last_frames. Includes parameter details, asset reference syntax, and limitations.

```APIDOC
## Video Generation

### Description
Generates videos using the st-ai/super-seed2 model with two distinct modes: `omni_reference` and `first_last_frames`.

### Parameters
Complete parameter documentation is available. Supports asset reference syntax like `@image_file_N` and `@video_file_N`.

### Aspect Ratio and Quality
Refer to `types.md` for supported aspect ratios and quality variants.

### Limitations
Includes limitations on file sizes, durations, and unsupported features. Refer to `endpoints.md` for details.

### Timing
Generation can take 10-15 minutes depending on the mode and complexity.
```

--------------------------------

### Upload Image from URL (MCP Mode)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Use the `upload_image` tool to upload an image by providing its URL. The returned URL should be used in subsequent task submissions.

```python
result = upload_image(
  image_url="https://example.com/source_image.png"
)
```

--------------------------------

### Submit Task (Omni Reference Mode)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedance-video-generation.md

Submits a video generation task using the omni_reference mode, allowing for reference images and other assets to guide the generation.

```APIDOC
## POST /task/submit (Omni Reference Mode)

### Description
Submits a video generation task using the omni_reference mode. This mode allows for the use of reference images, videos, and audio files to guide the video generation process.

### Method
POST

### Endpoint
/task/submit

### Parameters
#### Request Body
- **model_id** (string) - Required - The ID of the model to use for generation (e.g., "st-ai/super-seed2").
- **parameters** (object) - Required - Parameters for the video generation task.
  - **prompt** (string) - Required - The text prompt describing the desired video content, motion, and camera movement. Can include references to assets like `@image_file_1`.
  - **functionMode** (string) - Required - Must be set to `"omni_reference"`.
  - **image_files** (string[]) - Optional - An array of URLs to image files to be used as references.
  - **video_files** (string[]) - Optional - An array of URLs to video files to be used as references or for camera movement.
  - **audio_files** (string[]) - Optional - An array of URLs to audio files to be used as background music or sound effects.
  - **ratio** (string) - Optional - The aspect ratio of the video (e.g., `"16:9"`, `"1:1"`). Defaults to `"16:9"`.
  - **duration** (integer) - Optional - The desired duration of the video in seconds. Range: 4–15. Defaults to 5.
  - **model** (string) - Optional - The specific rendering model to use (e.g., `"seedance_2.0_fast"`, `"seedance_2.0"`). Defaults to `"seedance_2.0_fast"`.

### Request Example
```json
{
  "model_id": "st-ai/super-seed2",
  "parameters": {
    "prompt": "Cinematic realistic sci-fi style, 15 seconds, 16:9. @image_file_1 as character reference, walking through a futuristic city with neon lights, smooth camera pan from left to right, morning light casting long shadows",
    "functionMode": "omni_reference",
    "image_files": ["https://cdn.example.com/astronaut.png"],
    "ratio": "16:9",
    "duration": 15,
    "model": "seedance_2.0_fast"
  }
}
```

### Response
(Details on response structure for task submission are not provided in the source, typically returns a task ID.)
```

--------------------------------

### Get Task Result (MCP Tool)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedream-text-to-image.md

Retrieve the status and results of a submitted task using its ID with the MCP tool. This is useful for monitoring generation progress.

```python
get_task(task_id="task_xyz123")
```

--------------------------------

### Upload Image from Local File (Script Mode)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/endpoints.md

Use the `upload` command with the `--image-path` flag to upload a local image file.

```bash
python .cursor/skills/seedance2-api/scripts/seedance_api.py upload \
  --image-path "/path/to/local/image.png"
```

--------------------------------

### Seedance Video Generation Model

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Documentation for video generation with two modes: omni_reference and first_last_frames. Includes complete parameter documentation, asset reference syntax, aspect ratio and quality variant reference, and limitations.

```markdown
seedance-video-generation.md (12 KB)
  - Video generation with two modes (omni_reference, first_last_frames)
  - Complete parameter documentation
  - Asset reference syntax (@image_file_N, @video_file_N, etc.)
  - Aspect ratio and quality variant reference
  - Limitations (file limits, durations, unsupported features)
```

--------------------------------

### Upload Local Image for Video Reference

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/workflow-guide.md

Uploads a local image file to be used as a reference for video generation. Returns the URL of the uploaded image.

```python
upload_result = upload_image(image_path="/path/to/character.png")
reference_image_1 = upload_result["url"]
```

--------------------------------

### MCP Tool Error Response Example

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/tools-and-commands.md

When a task fails using MCP tools, the 'get_task' command returns an error object detailing the failure code and message.

```json
{
  "task_id": "task_xyz123",
  "status": "failed",
  "error": {
    "code": "invalid_prompt",
    "message": "Prompt contains unsupported content"
  }
}
```

--------------------------------

### Tool Reference Table

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/INDEX.md

Lists available tools, their execution modes (MCP or Script), their location within the documentation, and their primary purpose.

```text
| Tool | Mode | Location | Purpose |
|------|------|----------|---------|
| `submit_task` | MCP | [tools-and-commands.md](api-reference/tools-and-commands.md#submit_task) | Submit task |
| `get_task` | MCP | [tools-and-commands.md](api-reference/tools-and-commands.md#get_task) | Check status |
| `upload_image` | MCP | [tools-and-commands.md](api-reference/tools-and-commands.md#upload_image) | Upload image |
| `get_balance` | MCP | [tools-and-commands.md](api-reference/tools-and-commands.md#get_balance) | Check balance |
| `submit` | Script | [tools-and-commands.commands.md#submit) | Submit task |
| `query` | Script | [tools-and-commands.md](api-reference/tools-and-commands.md#query) | Check status |
| `poll` | Script | [tools-and-commands.md](api-reference/tools-and-commands.md#poll) | Auto-poll task |
| `upload` | Script | [tools-and-commands.md](api-reference/tools-and-commands.md#upload) | Upload image |
| `balance` | Script | [tools-and-commands.md](api-reference/tools-and-commands.md#balance) | Check balance |
```

--------------------------------

### Monitor task status with get_task MCP tool

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/tools-and-commands.md

Query the status and results of a submitted task using its task_id. This example shows a loop to poll for completion or failure.

```python
while True:
  result = get_task(task_id="task_abc123")
  if result["status"] == "completed":
    print("Done!", result["result"])
    break
  elif result["status"] == "failed":
    print("Error:", result["error"]["message"])
    break
  else:
    print(f"Status: {result['status']}")
    time.sleep(30)
```

--------------------------------

### Seedream Text-to-Image Model

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Documentation for the text-to-image generation model. Includes parameters, request/response formats, timing information (1-2 min), polling recommendations, and an image size reference table.

```markdown
seedream-text-to-image.md (5.5 KB)
  - Text-to-image generation model documentation
  - Parameters, request/response formats
  - Timing (1-2 min), polling recommendations
  - Image size reference table
```

--------------------------------

### Get Task Result (Python Script)

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/seedream-text-to-image.md

Query the status of a task using the Python script by providing the task ID. This allows for programmatic monitoring of image generation.

```bash
python .cursor/skills/seedance2-api/scripts/seedance_api.py query \
  --task-id "task_xyz123"
```

--------------------------------

### Seedream Image Editing Model

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/DOCUMENTATION_SUMMARY.txt

Documentation for the image editing and enhancement model. Covers figure reference syntax for multiple images, error handling, limitations, and complete usage examples.

```markdown
seedream-image-editing.md (5.6 KB)
  - Image editing and enhancement model
  - Figure reference syntax for multiple images
  - Error handling and limitations
  - Complete usage examples
```

--------------------------------

### Submit Video with Audio Reference

Source: https://github.com/hexiaochun/seedance2-api/blob/main/_autodocs/api-reference/workflow-guide.md

Submit a video generation task that includes an audio file as a reference. The audio file is provided via the 'audio_files' parameter, and can be referenced in the prompt.

```python
# Submit video with audio
task = submit_task(
  model_id="st-ai/super-seed2",
  parameters={
    "prompt": "Cinematic video with @audio_file_1 as background music...",
    "audio_files": ["https://cdn.example.com/music.mp3"],
    "ratio": "16:9",
    "duration": 10
  }
)
```