# Seedance 2.5

Start on your frame and let it run — a full 30-second scene in a single generation.

- Model ID: `bytedance/seedance-2.5/image-to-video`
- Provider: ByteDance
- Modality: image → video
- Type: Image to Video
- Status: stable
- Delivery: async
- Max resolution: 720p
- Output format: mp4

## 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/image-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/image-to-video`

```bash
curl -X POST https://api.dev.pika.art/v1/media/bytedance/seedance-2.5/image-to-video \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Cinematic fashion editorial, a narrow vintage elevator lined in deep oxblood mahogany panelling with a brass button plate, a woman in a liquid gold silk slip dress standing perfectly centred, an ocean of cream silk pooled across the floor and spilling out toward camera. Rich low-contrast grade, warm practical light inside the car, soft falloff into the dark wood, fine 35mm grain. Shot 1 — Locked symmetrical wide, matching the frame exactly. She holds still, then slowly raises her right arm and reaches toward the brass button plate on the wall beside her, the silk shifting faintly around her feet as she moves. Camera creeps forward a few inches as her finger nears the panel. Shot 2 — Hard cut to an extreme macro close-up of her hand at the brass plate, shallow focus. Her fingertip presses a worn button; it depresses and lights up warm amber, the glow reflecting in the polished brass and on her skin. A soft mechanical click. Camera drifts a fraction, rack focusing from the lit button to her knuckles. Shot 3 — Hard cut to a high overhead angle looking straight down at her from the elevator ceiling, the gold dress a single stroke of colour in a sea of cream silk. Camera orbits slowly above her as the car rises, the overhead light pulsing as floors pass, warm then dark then warm. She tilts her face up toward the lens. Shot 4 — Hard cut to a low wide from outside as the brass doors slide open and she steps forward out of the car, wading through the cream silk, the whole mass of it dragging with her across the threshold in a slow heavy wave. Camera retreats ahead of her, holding her centred, until she fills the frame and walks past the lens. Audio: deep elevator motor hum, cable creak, a soft button click and amber-lit chime, the dry whisper of silk sliding on wood, doors clunking open, bare feet on polished floor.",
  "duration": 10,
  "resolution": "720p",
  "generate_audio": true,
  "watermark": false,
  "image_url": "https://cdn.pika.art/v2/files/agent/b9ea9264-867b-4db3-ad83-9ee371093a8a/seedance-2.5-i2v-elevator-silk-input.jpg",
  "ratio": "adaptive"
}'
```

### Request body

| Param | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `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 for 2.5). |
| `generate_audio` | boolean | no | - | 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'. |
| `image_url` | string | yes | - | URL of the starting-frame image to animate. |
| `end_image_url` | string | no | - | Optional URL of the image to use as the last frame. |
| `ratio` | string | no | adaptive | Output aspect ratio. |

### Accepted values

| Param | Values | Default |
| --- | --- | --- |
| `resolution` | `480p`, `720p` | `720p` |
| `output_format` | `mp4`, `mov` | — |
| `bitrate_mode` | `standard`, `high` | — |

Returns a job object, not the final output — normally with status `queued`. 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.

### 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"
    }
  }
}
```

**200 OK · failed**

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

## Get result

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

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

Once the job completes, fetch a download URL for the generated media.

### Response

**200 OK · content URL**

```json
{
  "url": "https://api.dev.pika.art/v1/files/video_8f3a2c91.mp4"
}
```

## 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 — Org limit reached: requests per minute or day, or concurrent jobs. Returned as the failed job envelope; check the Retry-After header and 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 |
| 720p · standard | 11.235 | 21,600 | 0.2427 | 1.21 |

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. 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/image-to-video
API index: https://dev.pika.art/llms.txt