# Seedance 2.5 API

> Seedance 2.5 — high-quality AI video generation.

- **Provider**: ByteDance
- **Model id**: `bytedance-seedance-2-5`
- **Modality**: video
- **Price**: 11.16–55.9 credits /sec

## Overview

Seedance 2.5 is called in two steps: create a generation task, then poll the task until the result is ready.

## Authentication

All requests require a Bearer Token in the request header:

```
Authorization: Bearer YOUR_API_KEY
```

## Create Task

`POST https://you.bot/api/v1/generate`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| modelId | string | Yes | Model id: `bytedance-seedance-2-5` |
| input | object | Yes | Input parameters object (see below) |
| callbackUrl | string | No | https URL we POST the finished task to. Signed with `X-Webhook-Signature` once you create a webhook signing key in Dashboard → Settings |

### input object parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| prompt | string | No | The text prompt or description for the video. Max 30000 characters. (example: Create a **20-second photorealistic cinematic action sequence**, 16:9. A black classic American muscle sports car cruises fast along a dramatic coastal highway… — full value in the request example) |
| reference_image_urls | string[] | No | A list of input image URLs. (image URL) |
| reference_video_urls | string[] | No | A list of input video URLs. Furthermore, the total length of the three videos must not exceed 30 seconds. (image URL) |
| reference_audio_urls | string[] | No | A list of input audio URLs. Furthermore, the total length of the three audios must not exceed 30 seconds. (image URL) |
| first_frame_url | string | No | Image URL |
| last_frame_url | string | No | Image URL |
| duration | number | No | Video duration in seconds. (range 4-30) (default: 5) |
| resolution | string | No | The output video resolution. (options: 480p \| 720p \| 1080p) (default: 720p) |
| aspect_ratio | string | No | The aspect ratio of the generated video. (options: 16:9 \| 4:3 \| 1:1 \| 3:4 \| 9:16 \| 21:9 \| adaptive) (default: adaptive) |
| output_format | string | No | Video output format. (options: mp4 \| mov) (default: mp4) |
| generate_audio | boolean | No | Whether to generate AI audio synchronized with the video. (true/false) (default: true) |
| return_last_frame | boolean | No | Whether to return the last frame of the video. When draft=true, this parameter cannot be set to true. (true/false) (default: false) |
| nsfw_checker | boolean | No | A configurable parameter. Defaults to true in the Playground. (true/false) (default: true) |

### Request example

```json
{
  "modelId": "bytedance-seedance-2-5",
  "input": {
    "prompt": "Create a **20-second photorealistic cinematic action sequence**, 16:9.\n\nA black classic American muscle sports car cruises fast along a dramatic coastal highway at sunset. Ocean cliffs on one side, glowing orange sky, waves crashing below. Premium Hollywood action-film look.\n\nKeep the same car, driver, motorcycles and environment consistent throughout.\n\n**0–4s — BEAUTY HOOK**\nLow cinematic tracking shot beside the black muscle car as it speeds smoothly along the ocean road. Warm sunset reflections slide across the polished bodywork. Camera briefly moves near the front wheel, then rises to reveal the vast coastline.\n\nDeep engine growl, wind and ocean ambience.\n\n**4–8s — AMBUSH**\nTwo black motorcycles suddenly approach from behind, one on each side.\n\nThe riders accelerate naturally and pull alongside the car.\n\nOne rider raises a handgun and fires several shots toward the vehicle.\n\nVisible muzzle flashes. Bullets strike the metal door and rear body panels, creating sparks and small physical impact marks.\n\nThe driver reacts immediately and accelerates.\n\nNo bullets magically passing through geometry.\n\n**8–12s — HIGH-SPEED CHASE**\nDynamic rear tracking shot.\n\nThe muscle car races through sweeping coastal curves while both motorcycles pursue closely.\n\nOne motorcycle moves beside the car while the second tries to overtake.\n\nThe car swerves to avoid another burst of gunfire.\n\nTires maintain realistic road contact. Suspension reacts to steering and road surface. Vehicles have believable weight, inertia and momentum.\n\nCamera stays fast and aggressive but physically possible.\n\n**12–15s — CRASH**\nThe car enters a sharp curve too fast.\n\nIts rear tire clips a broken roadside barrier.\n\nClear physical impact.\n\nThe vehicle loses balance, rolls violently across the asphalt and comes to rest upside down.\n\nMetal bends, glass breaks and sparks scatter.\n\nFuel ignites underneath the wreckage.\n\nA large fire begins around the overturned car.\n\nThe motorcycles brake hard in the distance.\n\n**15–18s — SUPERNATURAL REVEAL**\nThrough thick smoke and flames, the driver slowly crawls out of the wreckage and rises to his feet.\n\nHis clothes are burned and damaged.\n\nAs he walks calmly through the fire, his human face transforms into a **bare supernatural skull surrounded by violent blue-white electrical arcs**.\n\nElectricity crawls across the skull, shoulders and arms.\n\nThe flames behind him illuminate the bone structure.\n\nHe keeps walking forward without rushing.\n\nCamera slowly pushes toward him.\n\n**18–20s — FINAL SHOT**\nExtreme dramatic low angle.\n\nThe skull-faced figure stops close to camera.\n\nElectricity explodes around his body.\n\nHe smoothly draws a handgun, raises it directly toward the lens and fires.\n\nBright muzzle flash fills the frame.\n\nImmediate hard cut to black.\n\n**STYLE**\nPhotorealistic Hollywood supernatural action film, realistic vehicle dynamics, grounded crash physics, sunset coastline, dramatic fire and smoke, detailed metal destruction, cinematic sparks, blue-white electrical energy, rich orange-versus-blue contrast, volumetric lighting, realistic motion blur, premium blockbuster cinematography.\n\n**PHYSICS PRIORITY**\nRealistic tire contact, suspension, momentum, collisions, crash weight, falling debris and human movement. Every action must have a visible physical cause.\n\n**CAMERA**\nLow tracking shots, chase-camera movement, controlled handheld energy, dramatic push-in and final low-angle close-up. Use clean cinematic cuts. Never pass through cars, roads or characters.\n\n**AVOID**\nFloating vehicles, impossible drifting, weightless crashes, random explosions, teleporting motorcycles, duplicated riders, morphing car geometry, floating debris, broken anatomy, random camera teleportation, subtitles, text, logos or watermark.",
    "reference_image_urls": [
      "https://you.bot/examples/grok-imagine-text-to-image.jpg"
    ],
    "reference_video_urls": [
      "https://you.bot/examples/gemini-omni.mp4"
    ],
    "reference_audio_urls": [
      "https://you.bot/examples/suno-v4-5.mp3"
    ],
    "first_frame_url": "https://you.bot/examples/grok-imagine-text-to-image.jpg",
    "last_frame_url": "https://you.bot/examples/grok-imagine-text-to-image.jpg",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "adaptive",
    "output_format": "mp4",
    "generate_audio": true,
    "return_last_frame": false,
    "nsfw_checker": true
  }
}
```

### Response example

```json
{
  "taskId": "281e5b0…f39b9",
  "creditsCharged": 155.75
}
```

## Query Task

`GET https://you.bot/api/v1/task/{taskId}?model=bytedance-seedance-2-5`

When `state` is `success`, the output is in `resultUrls`: `{ "state": "success", "resultUrls": [ ... ] }`. (Text models return inline in the create response.)

## Error Codes

| Code | Description |
|------|-------------|
| 200 | Request successful |
| 400 | Invalid request parameters |
| 401 | Authentication failed — check API Key |
| 402 | Insufficient account balance |
| 403 | IP not allowed for this key, or the key is restricted to other models |
| 404 | Task not found, or it has expired |
| 409 | Duplicate request — an identical submit arrived moments ago. Nothing was charged; retry is safe |
| 413 | Payload too large — see the character and file-size limits for this model |
| 429 | Rate limit exceeded — retry after the Retry-After header |
| 500 | Internal server error |
| 504 | Upstream timed out — nothing was delivered; retry is safe |