Metadata-Version: 2.4
Name: seedance-2-api
Version: 0.1.0
Summary: A comprehensive Python wrapper for the Seedance 2.0 API.
Author: Anil Matcha
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: python-dotenv
Requires-Dist: mcp[cli]
Dynamic: license-file
Dynamic: requires-python

# Seedance 2.0 API: Python Wrapper for ByteDance's AI Video Generator

[![GitHub stars](https://img.shields.io/github/stars/Anil-matcha/Seedance-2.0-API.svg)](https://github.com/Anil-matcha/Seedance-2.0-API/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)

The most comprehensive Python wrapper for the **Seedance 2.0 API** (developed by ByteDance), delivered via [muapi.ai](https://muapi.ai). Generate cinematic, high-fidelity AI videos from text prompts and static images with the world's most advanced video generation model.

Here is a comprehensive guide on using Seedance 2.0 API https://medium.com/@anilmatcha/seedance-2-0-api-complete-developer-guide-text-to-video-image-to-video-python-sdk-1479f5e5491f

## 🚀 Why Use Seedance 2.0 API?

Seedance 2.0 is the industry-leading **Sora alternative** developed by ByteDance, offering unparalleled video quality and motion consistency.

- **Cinematic Quality**: Generate 2K resolution AI videos with realistic physics and lighting.
- **Superior Motion Control**: Advanced camera movement and character consistency for professional results.
- **Multimodal API**: Supports Text-to-Video (T2V), Image-to-Video (I2V), and Video Extension.
- **Developer-First**: Fast processing via the MuAPI infrastructure with a simple Python SDK.

## 🌟 Key Features of Seedance 2.0 API

- ✅ **Seedance 2.0 Text-to-Video (T2V)**: Transform complex descriptive prompts into stunning AI video clips.
- ✅ **Seedance 2.0 Image-to-Video (I2V)**: Animate any static image with precise motion control using `images_list`.
- ✅ **Seedance 2.0 Omni-Reference**: Condition a video on any combination of image, video, and audio references in one request.
- ✅ **Seedance 2.0 Character**: Generate a multi-panel character sheet (front, back, side, action pose, expressions) from 1–3 reference photos. Use `@character:<id>` inline in any prompt, or pass the sheet directly as an anchor image for tighter face fidelity via `consistent_video()`.
- ✅ **Seedance 2.0 Video-Edit**: Edit existing videos using text prompts and reference images for stylized results.
- ✅ **File Upload**: Directly upload local images and videos using the `upload_file` method, supporting seamless use in generation tasks.
- ✅ **Video Extension**: Seamlessly extend existing clips while maintaining consistent style and characters.
- ✅ **High-Resolution Output**: Support for `basic` and `high` (2K) quality settings.
- ✅ **Flexible Aspect Ratios**: Optimized for `16:9`, `9:16` (TikTok/Reels), `4:3`, and `3:4`.

---

## 🛠 Installation

```bash
# Clone the Seedance 2.0 API repository
git clone https://github.com/Anil-matcha/Seedance-2.0-API.git
cd Seedance-2.0-API

# Install required dependencies
pip install -r requirements.txt
```

### Configuration
Create a `.env` file in the root directory and add your [MuAPI](https://muapi.ai) API key:
```env
MUAPI_API_KEY=your_muapi_api_key_here
```

---

## 🤖 Seedance 2.0 MCP Server (New!)

You can now use Seedance 2.0 as an **MCP (Model Context Protocol)** server. This allows AI models (like Claude Desktop or Cursor) to directly invoke Seedance tools.

### Running the MCP Server
1. Ensure `MUAPI_API_KEY` is set in your environment.
2. Run the server:
   ```bash
   python3 mcp_server.py
   ```
3. To test with the MCP Inspector:
   ```bash
   npx -y @modelcontextprotocol/inspector python3 mcp_server.py
   ```

---

## 💻 Quick Start with Seedance 2.0 API (Python)

```python
from seedance_api import SeedanceAPI

# Initialize the Seedance 2.0 client
api = SeedanceAPI()

# 1. Generate Video from Text (T2V) using Seedance 2.0 API
print("Generating AI Video using Seedance 2.0...")
submission = api.text_to_video(
    prompt="A cinematic slow-motion shot of a cyberpunk city in the rain, neon lights reflecting on puddles, 8k resolution",
    aspect_ratio="16:9",
    duration=5,
    quality="high"
)

# 2. Wait for completion
result = api.wait_for_completion(submission['request_id'])
print(f"Success! View your Seedance 2.0 video here: {result['url']}")
```

---

## 📡 API Endpoints & Reference

### 1. Seedance 2.0 Text-to-Video (T2V)
**Endpoint**: `POST https://api.muapi.ai/api/v1/seedance-v2.0-t2v`

Supports `@character:<id>` inline in the prompt — see [Character Workflow](#-character-workflow) below.

```bash
curl --location --request POST "https://api.muapi.ai/api/v1/seedance-v2.0-t2v" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data-raw '{
      "prompt": "A majestic eagle soaring over the snow-capped Himalayas",
      "aspect_ratio": "16:9",
      "duration": 5,
      "quality": "high"
  }'
```

### 2. Seedance 2.0 Image-to-Video (I2V)
**Endpoint**: `POST https://api.muapi.ai/api/v1/seedance-v2.0-i2v`

Reference images with `@image1`, `@image2`, etc. in the prompt. Supports `@character:<id>` — characters are automatically appended to `images_list`.

```bash
curl --location --request POST "https://api.muapi.ai/api/v1/seedance-v2.0-i2v" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data-raw '{
      "prompt": "Make the clouds move slowly across the sky",
      "images_list": ["https://example.com/mountain.jpg"],
      "aspect_ratio": "16:9",
      "duration": 5,
      "quality": "basic"
  }'
```

### 3. Seedance 2.0 Omni-Reference
**Endpoint**: `POST https://api.muapi.ai/api/v1/seedance-2.0-omni-reference`

Condition a single video generation on any combination of image, video, and audio references. Use `@character:<id>` inline in the prompt to inject a character (see section below).

```bash
curl --location --request POST "https://api.muapi.ai/api/v1/seedance-2.0-omni-reference" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data-raw '{
      "prompt": "A dramatic chase scene through a neon city",
      "aspect_ratio": "16:9",
      "duration": 5,
      "images_list": ["https://example.com/scene_ref.jpg"],
      "video_files": ["https://example.com/style_ref.mp4"]
  }'
```

### 4. Seedance 2.0 Character (Consistent Character Sheets)
**Endpoint**: `POST https://api.muapi.ai/api/v1/seedance-2-character`

Create a multi-panel character sheet (front, back, side profile, action pose, facial expressions, accessories) at 4K / 21:9 from 1–3 reference photos of a real person.

Once the sheet is generated you can use it two ways:
- **`@character:<request_id>`** inline in any T2V, I2V, or Omni-Reference prompt
- Pass `outputs[0]` (the sheet image URL) directly as `@image1` in an I2V request for tighter face fidelity

| Field | Type | Required | Description |
|---|---|---|---|
| `images_list` | array of URLs | Yes | 1–3 photos of the reference person |
| `prompt` | string | Yes | Desired outfit/style for the character |

```bash
curl --location --request POST "https://api.muapi.ai/api/v1/seedance-2-character" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data-raw '{
      "images_list": ["https://example.com/person.jpg"],
      "prompt": "cyberpunk jacket with neon accents"
  }'
```

**Cost:** $0.18 per character sheet

For a full guide including the direct sheet-anchored I2V workflow, see [CHARACTER_CONSISTENCY.md](CHARACTER_CONSISTENCY.md).

### 5. Seedance 2.0 Video-Edit
**Endpoint**: `POST https://api.muapi.ai/api/v1/seedance-v2.0-video-edit`
```bash
curl --location --request POST "https://api.muapi.ai/api/v1/seedance-v2.0-video-edit" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data-raw '{
      "prompt": "The cat walks through a garden",
      "video_urls": ["https://example.com/video.mp4"],
      "images_list": ["https://example.com/image.jpg"],
      "aspect_ratio": "16:9",
      "quality": "basic",
      "remove_watermark": false
  }'
```

---

## 🎭 Character Consistency Workflow

Create a fictional character from reference photos and maintain their identity across multiple video scenes.

Two approaches are available — see [CHARACTER_CONSISTENCY.md](CHARACTER_CONSISTENCY.md) for a full guide.

### Option A — `@character:<id>` inline (simplest)

```python
from seedance_api import SeedanceAPI
api = SeedanceAPI()

# Step 1 — generate a character sheet (1–3 reference photos)
char = api.create_character(
    images_list=["https://example.com/person.jpg"],
    outfit_description="cyberpunk jacket with neon accents, glowing visor",
)
char_id = char["request_id"]
api.wait_for_completion(char_id)  # wait for sheet to render

# Step 2 — reference the character inline in any prompt
video = api.text_to_video(
    prompt=f"@character:{char_id} rides a motorcycle through a neon-lit city at night",
    aspect_ratio="16:9",
    duration=5,
)
result = api.wait_for_completion(video["request_id"])
print(f"Video: {result['outputs'][0]}")

# Multiple characters in one prompt
char2_id = "another-completed-character-request-id"
video2 = api.text_to_video(
    prompt=f"@character:{char_id} and @character:{char2_id} face off in a neon-lit arena",
    aspect_ratio="16:9",
    duration=5,
)
```

### Option B — `consistent_video()` (tighter face fidelity)

Pass the character sheet directly as the anchor image for Image-to-Video generation.

```python
# Get the sheet URL after character creation
sheet_result = api.wait_for_completion(char_id)
sheet_url = sheet_result["outputs"][0]

# Generate with the sheet as anchor
video = api.consistent_video(
    sheet_url=sheet_url,
    prompt="@image1 draws their weapon in slow motion, dramatic lighting",
    aspect_ratio="16:9",
    duration=5,
    quality="high",
)
result = api.wait_for_completion(video["request_id"])
print(f"Video: {result['outputs'][0]}")
```

> **Tip**: `@character:<id>` works in T2V, I2V, and Omni-Reference prompts. Use `consistent_video()` when face similarity is critical.

---

## 📖 Documentation & Guides

For a comprehensive walkthrough, check out the **[Seedance 2.0 API: Complete Developer Guide](https://medium.com/@anilmatcha/seedance-2-0-api-complete-developer-guide-text-to-video-image-to-video-python-sdk-1479f5e5491f)** on Medium. This guide covers advanced use cases, prompt engineering, and best practices for high-quality video generation.

| Method | Parameters | Description |
| :--- | :--- | :--- |
| `text_to_video` | `prompt`, `aspect_ratio`, `duration`, `quality`, `remove_watermark` | Generate video from text. Supports `@character:<id>` in prompt. |
| `image_to_video` | `prompt`, `images_list`, `aspect_ratio`, `duration`, `quality`, `remove_watermark` | Animate images. Supports `@image1`/`@character:<id>` in prompt. |
| `omni_reference` | `prompt`, `aspect_ratio`, `duration`, `quality`, `images_list`, `video_files`, `audio_files` | Multi-modal reference video generation. |
| `create_character` | `images_list` (1–3), `outfit_description`, `character_name` | Generate a 4K character sheet from reference photos. Returns `request_id`; `outputs[0]` is the sheet URL. |
| `consistent_video` | `sheet_url`, `prompt`, `aspect_ratio`, `duration`, `quality`, `extra_images` | I2V with the character sheet as anchor (`@image1`). Tighter face fidelity than `@character:<id>`. |
| `video_edit` | `prompt`, `video_urls`, `images_list`, `aspect_ratio`, `quality`, `remove_watermark` | Edit existing videos with prompts and images. |
| `watermark_remover`| `video_url` | Remove MuAPI watermark from a Seedance video. |
| `watermark_remover_pro`| `video_url` | Remove MuAPI watermark from a Seedance video (Pro version). |
| `text_to_video_480p`| `prompt`, `aspect_ratio`, `duration`, `quality` | Generate a 480p video from text (faster/cheaper). |
| `image_to_video_480p`| `prompt`, `images_list`, `aspect_ratio`, `duration`, `quality` | Generate a 480p video from an image (faster/cheaper). |
| `extend_video` | `request_id`, `prompt`, `duration`, `quality` | Extend an existing Seedance video segment. |
| `upload_file` | `file_path` | Upload a local file (image or video) to MuAPI for use in generation tasks. |
| `get_result` | `request_id` | Check task status for the Seedance API. |
| `wait_for_completion` | `request_id`, `poll_interval`, `timeout` | Blocking helper for Seedance generation tasks. |

---

## 🔗 Official Resources
- **Developer Guide**: [Seedance 2.0 API: Complete Tutorial](https://medium.com/@anilmatcha/seedance-2-0-api-complete-developer-guide-text-to-video-image-to-video-python-sdk-1479f5e5491f)
- **Playground**: [Seedance 2.0 I2V Playground](https://muapi.ai/playground/seedance-v2.0-i2v)
- **Extension Tool**: [Seedance 2.0 Extend Playground](https://muapi.ai/playground/seedance-v2.0-extend)
- **API Provider**: [MuAPI.ai](https://muapi.ai)

## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

**Keywords**: Seedance 2.0 API, ByteDance Seedance, AI Video Generator, Text-to-Video AI, Image-to-Video API, Seedance Python SDK, Seedance V2 API, Sora Alternative, MuAPI, Video Generation API, Cinematic AI Video, AI Video Creation, ByteDance Video AI, Seedance API Documentation, Seedance I2V, Seedance T2V, AI Movie Generator, AI Animation API, Python Video API, Seedance 2.0 Tutorial.
