# Seedance 2.5

Tell the whole story in one pass — 30 seconds of connected shots with native sound.

- Model ID: `bytedance/seedance-2.5/text-to-video`
- Provider: ByteDance
- Modality: text → video
- Type: Text to Video
- Status: stable
- Delivery: async
- Max resolution: 1080p
- Output format: mp4
- Aspect ratios: 1:1, 4:3, 3:4, 16:9, 9:16, 21:9, adaptive

## Authentication

Send your API key in the `X-API-Key` header.

The same key reads the org balance at `GET https://api.dev.pika.art/billing/balance`, which is free to call and confirms the request can be paid for before you submit it.

## Endpoint

```
POST https://api.dev.pika.art/v1/media/bytedance/seedance-2.5/text-to-video
```

## Reference uploads

To use a local file (image, audio, or video) as a model input, first request a presigned upload URL: `POST /v1/media/uploads` with the `X-API-Key` header and a JSON body `{ "content_type": "image/png", "size_bytes": 12345 }`, where `size_bytes` is the file's exact byte length. The response returns `upload_url` (temporary, valid for 5 minutes), `headers`, and `url` (the permanent Pika URL). PUT the file bytes to `upload_url` sending the returned `headers` verbatim — both `Content-Type` and `Content-Length` are signed, and storage returns a bare 403 if either is missing or differs. Then pass `url` into fields such as `image`, `image_url`, `end_image_url`, `image_urls`, `first_frame_image`, or `mask_image_url`.

## Generate

`POST /v1/media/bytedance/seedance-2.5/text-to-video`

```bash
curl -X POST https://api.dev.pika.art/v1/media/bytedance/seedance-2.5/text-to-video \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "draft": false,
  "prompt": "A fashion editorial in motion. ONE continuous unbroken take, no cuts. The camera moves constantly but always smoothly, on a crane and dolly — long fluid arcs, motivated reframes, no handheld shake, no whip pans, no speed ramps. Scene: a bare lilac room — lilac walls, lilac wool carpet, white baseboard, a long sheer lilac curtain at the left of frame. In the centre stands an ironing board with pale lilac legs and a lilac cotton cover. Draped over it is one large square silk scarf printed in dusty rose pink and olive green, a fine botanical pattern with a broad olive border: the left half lies perfectly flat and pressed with its edge hanging crisply over the rounded nose, the right half gathered into a soft billowing heap spilling over the far end. A wide polished chrome cuff bracelet stands upright on the pressed section, mirror-finish, warping the pink and lilac around it. A fine silver chain lies beside it and trails off the left edge, pooling on the carpet. Action: the curtain swells inward as a draught enters the room. The gathered folds on the right stir, then begin to rise — the silk lifting off the board and unfurling itself, opening out into a full square that floats and turns in the air above the ironing board, the printed botanicals rippling as it revolves. The loosened chain slides off the edge and drops to the carpet in a bright coil. The chrome cuff rocks, topples onto its side and rolls slowly along the bare lilac board cover toward the nose, reflections spinning across it. The silk keeps rising, drifting toward the window and the curtain, then falls all at once, settling flat across the empty board exactly as it was pressed at the start. Camera: begin low and close on the chrome cuff, the pressed silk and the hanging chain, then rise and arc left around the nose of the board as the curtain moves. As the silk lifts, crane upward with it, turning to follow the scarf as it revolves in the air, holding it centred while the lilac room rotates behind. Descend with the falling chain in one continuous move, level out into a low tracking shot beside the rolling cuff, then crane back up and pull out into a wide, symmetrical frontal of the board just as the silk settles onto it. Look: soft diffuse daylight through the curtain, no hard shadows, a tight palette of lilac, dusty pink and olive. Shot on 35mm film, 80mm lens, medium depth of field, fine natural grain, low contrast, liquid sheen on the silk. Photographic and physically real, like an Hermès still-life campaign — no digital gloss. The room is empty; there is no iron and no person. Audio: quiet room tone, a curtain drawing against the wall, silk snapping open and rustling as it turns in the air, a chain dropping onto carpet, chrome rolling on padded cloth, the soft whump of fabric landing, nothing else.",
  "duration": 10,
  "resolution": "720p",
  "generate_audio": true,
  "watermark": false,
  "ratio": "16:9"
}'
```

### Request body

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `draft` | boolean | no | false | Render a 480p draft preview. A draft can be finalized at 1080p through 'bytedance/seedance-2.5/draft-to-video' within 7 days, charged as its own job. |
| `prompt` | string | yes | - | Text prompt describing the video to generate. |
| `duration` | enum | yes | - | Video length in seconds (4-30), or 'auto' to let the model choose. |
| `resolution` | enum | no | 720p | Output resolution (480p/720p/1080p for 2.5). |
| `generate_audio` | boolean | no | true | Whether to generate audio for the video. |
| `watermark` | boolean | no | false | Whether to add a watermark to the output video. |
| `output_format` | enum | no | - | Output container format. |
| `bitrate_mode` | enum | no | - | Output encode bitrate. 'high' produces a larger, higher-bitrate file; defaults to 'standard'. |
| `ratio` | enum | no | - | Output aspect ratio. |

#### Example body

```json
{
  "draft": false,
  "prompt": "A fashion editorial in motion. ONE continuous unbroken take, no cuts. The camera moves constantly but always smoothly, on a crane and dolly — long fluid arcs, motivated reframes, no handheld shake, no whip pans, no speed ramps. Scene: a bare lilac room — lilac walls, lilac wool carpet, white baseboard, a long sheer lilac curtain at the left of frame. In the centre stands an ironing board with pale lilac legs and a lilac cotton cover. Draped over it is one large square silk scarf printed in dusty rose pink and olive green, a fine botanical pattern with a broad olive border: the left half lies perfectly flat and pressed with its edge hanging crisply over the rounded nose, the right half gathered into a soft billowing heap spilling over the far end. A wide polished chrome cuff bracelet stands upright on the pressed section, mirror-finish, warping the pink and lilac around it. A fine silver chain lies beside it and trails off the left edge, pooling on the carpet. Action: the curtain swells inward as a draught enters the room. The gathered folds on the right stir, then begin to rise — the silk lifting off the board and unfurling itself, opening out into a full square that floats and turns in the air above the ironing board, the printed botanicals rippling as it revolves. The loosened chain slides off the edge and drops to the carpet in a bright coil. The chrome cuff rocks, topples onto its side and rolls slowly along the bare lilac board cover toward the nose, reflections spinning across it. The silk keeps rising, drifting toward the window and the curtain, then falls all at once, settling flat across the empty board exactly as it was pressed at the start. Camera: begin low and close on the chrome cuff, the pressed silk and the hanging chain, then rise and arc left around the nose of the board as the curtain moves. As the silk lifts, crane upward with it, turning to follow the scarf as it revolves in the air, holding it centred while the lilac room rotates behind. Descend with the falling chain in one continuous move, level out into a low tracking shot beside the rolling cuff, then crane back up and pull out into a wide, symmetrical frontal of the board just as the silk settles onto it. Look: soft diffuse daylight through the curtain, no hard shadows, a tight palette of lilac, dusty pink and olive. Shot on 35mm film, 80mm lens, medium depth of field, fine natural grain, low contrast, liquid sheen on the silk. Photographic and physically real, like an Hermès still-life campaign — no digital gloss. The room is empty; there is no iron and no person. Audio: quiet room tone, a curtain drawing against the wall, silk snapping open and rustling as it turns in the air, a chain dropping onto carpet, chrome rolling on padded cloth, the soft whump of fabric landing, nothing else.",
  "duration": 10,
  "resolution": "720p",
  "generate_audio": true,
  "watermark": false,
  "ratio": "16:9"
}
```

### Accepted values

| Param | Values | Default |
| --- | --- | --- |
| `resolution` | `480p`, `720p`, `1080p` | `720p` |
| `output_format` | `mp4`, `mov` | — |
| `bitrate_mode` | `standard`, `high` | — |
| `ratio` | `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `21:9`, `adaptive` | — |

Returns a job object, not the final output — normally with status `queued`. If you're at your concurrency limit, the job stays `queued` until a slot frees up, then starts on its own. Store the `id` and poll until a terminal state. A rejected submit (insufficient balance, rate limit, unpriceable input) still returns the job object, with status `failed` and `error` set. An `Idempotency-Key` replay returns the existing job in its current state — including `failed`, so retry a failure with a fresh key, never the same one.

### Response

**200 OK · queued**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "queued"
}
```

## Poll status

`GET /v1/media/jobs/{request_id}`

```bash
curl https://api.dev.pika.art/v1/media/jobs/{request_id} \
  -H "X-API-Key: YOUR_API_KEY"
```

Poll the job by id until it reaches a terminal state: `completed` or `failed`.

### The job object

- `id` (string): Unique identifier for the job.
- `status` (enum): One of `queued`, `running`, `completed`, `failed`.
- `output` (object): Present once the job completes.
  - `media_type` (enum): `video`.
  - `output.video.url` (string): URL of the generated video.
- `error` (object): Present if the job failed. `error.code` is the stable machine-readable value to branch on — one of `invalid_input`, `content_moderation`, `provider_error`, `provider_timeout`, `provider_unavailable`, `rate_limited`, `insufficient_balance`, `membership_required`, `cycle_limit_exceeded`, `admission_suspended`, `timed_out`, `internal`. Unrecognized values normalize to `provider_error`. `error.message` is diagnostic text and varies.
- `usage` (object): Units the provider reported for the job, such as `video_output_tokens`, `image_output_tokens`, `input_tokens`, or `output_seconds`. Present once the job is terminal, carries only the units the job reports, and is `null` when nothing was reported. It may not reproduce the charge, because some pricing components are fixed by the request; the charge is authoritative.
- `billing` (object): What the job charged. Present once the job is terminal, `null` on the submit response and on webhooks. `billing.state` is one of `settled`, `pending`, `unavailable`. `settled` carries `charge_micro_usd`, the amount collected in micro-USD (the balance's unit), `0` included. `pending` means the charge is still settling: retry at 1s, 2s, then 5s. `unavailable` means the billing read failed on Pika's side: retry no sooner than 30s. Record spend only when `state` is `settled`, keyed by job id; a `billing` of `null` is not a charge.

### Response

**200 OK · running**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "running"
}
```

**200 OK · completed**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "completed",
  "output": {
    "media_type": "video",
    "video": {
      "url": "https://api.dev.pika.art/v1/files/video_8f3a2c91.mp4",
      "content_type": "video/mp4"
    }
  },
  "usage": {
    "video_output_tokens": 50638
  },
  "billing": {
    "state": "settled",
    "charge_micro_usd": 372189
  }
}
```

**200 OK · failed**

```json
{
  "id": "media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0",
  "status": "failed",
  "error": {
    "code": "provider_error",
    "message": "upstream generation failed"
  },
  "billing": {
    "state": "settled",
    "charge_micro_usd": 0
  }
}
```

A completed job carries its download URL in `output`. `GET /v1/media/jobs/{request_id}/content` returns that same URL as `{ "url": "..." }` for clients that only kept the id; it answers `409` until the job completes.

## Errors

Errors use conventional HTTP status codes and always return JSON, in one of two shapes. Request-level errors (auth, unknown path, schema validation, idempotency conflict) are `{"message": "..."}`. Submit rejections that occur after the job row is created (insufficient balance, rate limit, unpriceable input, dispatch unavailable) return the full failed job envelope — branch on `error.code`, and retry with a fresh `Idempotency-Key`, since a failed job replays on its key.

- 401 Unauthorized — The API key is missing or invalid. Body: `{"message":"Invalid API key"}`
- 403 Forbidden — An inactive key is rejected with a `{"message"}` body. A submit that the org balance or postpaid cycle limit cannot cover is rejected after the job row exists and returns the failed job envelope. `GET /billing/balance` separates the two: a `200` means the key is active, so the rejection was the balance or the cycle limit. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"insufficient_balance","message":"Insufficient org balance"}}`
- 404 Not Found — No job with that id exists in your org, or the media path names an unknown vendor/model/function. Body: `{"message":"media job not found"}`
- 409 Conflict — The result was requested before the job completed, or an Idempotency-Key header was reused with a different body. Body: `{"message":"media job is not ready"}`
- 422 Unprocessable Entity — The request body failed validation: an invalid enum value, a missing required field, a wrong type, or malformed JSON. The JSON message names the offending field. A schema-valid parameter combination that cannot be priced instead fails after job creation and returns the failed job envelope with error code `invalid_input`. Body: `{"message":"duration: Input should be less than or equal to 15"}`
- 429 Too Many Requests — You've hit your per-minute or per-day request limit, or your org's job queue is full. Returned as the failed job envelope. If there's a Retry-After header, wait that long, then retry with a fresh Idempotency-Key. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"rate_limited","message":"rate limit exceeded: rpm"}}`
- 503 Service Unavailable — The model rail or a backend dependency is temporarily unavailable. Returned as the failed job envelope; retry with backoff and a fresh Idempotency-Key. Body: `{"id":"media_8f3a2c91-5b7d-4e0a-9c26-31d4f2a8e6b0","status":"failed","error":{"code":"provider_unavailable","message":"media dispatch unavailable"}}`

## Pricing

Video output is metered in tokens, and the token count scales with pixel count — a lower per-token rate at a higher resolution is **not** a lower price. Compare the derived per-second cost, not the rate per 1M tokens.

| Tier | $ / 1M tokens | Video tokens / sec | $ / sec | $ / 5s clip |
| --- | --- | --- | --- | --- |
| 480p · standard | 11.235 | 10,000 | 0.1124 | 0.56 |
| 480p · draft | 11.235 | 10,000 | 0.1124 | 0.56 |
| 720p · standard | 11.235 | 21,600 | 0.2427 | 1.21 |
| 1080p · standard | 12.285 | 48,600 | 0.5971 | 2.99 |

The derived columns use each resolution's nominal token rate; billing settles on the token count the model actually reports.

Only successful generations are charged.

Check the balance against this price before submitting: `GET https://api.dev.pika.art/billing/balance` returns `balance_micro_usd`, which is US dollars multiplied by 1,000,000, and `postpaid` when the org bills by invoice instead. For an active postpaid org, compare the price against `postpaid.cycle.remaining_micro_usd` rather than the prepaid balance. Report a shortfall to the user rather than submitting a request the balance cannot cover.

---

Model page: https://dev.pika.art/models/bytedance/seedance-2.5/text-to-video
API index: https://dev.pika.art/llms.txt