# Seedance 2.5 Flash

Animate a first frame, or connect first and last frames, at 480p or 720p.

- Model ID: `bytedance/seedance-2.5-flash/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-flash/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-flash/image-to-video`

```bash
curl -X POST https://api.dev.pika.art/v1/media/bytedance/seedance-2.5-flash/image-to-video \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "A short multi-shot film with hard cuts between the numbered shots; Shot 1 starts exactly on the first frame. Cuts only change the camera angle on one continuous action - nobody and nothing jumps position between shots, and anyone new is seen arriving. Every shot stays in this same location with the same light. No text or logos appear.\nStory: he opens his perfume, the dragonfly flies off, and he dives in to chase it.\n[Shot 1, 0-5s] Close-up as in the first frame. With his other hand he clearly lifts the round glass cap straight up off the perfume bottle - the dragonfly is sitting on that cap. As the cap comes off, the startled dragonfly takes off from it and darts away over the pool to the right. He holds the open bottle in one hand and the cap in the other. He does NOT spray the perfume - no spray, no mist.\n[Shot 2, 5-9s] Same close-up angle: his head turns sharply to follow where the dragonfly flew, eyes locked on it, deadpan and determined. He sets the bottle down on the tiles beside him and pushes himself up from the pool edge.\n[Shot 3, 9-15s] Wide shot from the far end of the pool at water level: fully dressed in his oversized cream shirt, he dives from the pale tiled edge into the pale aqua water with a clean splash and swims fast freestyle straight across the pool after the small dragonfly, which skims low over the water just ahead of him. With every stroke the soaked cream shirt clings to his back, shoulders and arms, its long sleeves on his arms and the big round collar floating on the water around his neck. Far behind, the small lifeguard on his tall white chair sits up and watches.\nWARDROBE CONTINUITY: his oversized cream shirt is visible on him in every shot - on the pool edge, in mid-air during the dive and while swimming - wet cream fabric on his back and arms the whole time.\nKeep every person's face, hair, wardrobe, the props and the location exactly as in the first frame in every shot.\nSPEED IS CRITICAL: everything moves at normal real-time speed, like 24fps footage played back at 24fps - natural motion, NO slow motion.\nAudio: open-air pool ambience, water lapping at the tiles, the soft glassy clink of the cap lifting off, the dry buzz of dragonfly wings, a big splash and steady swimming strokes; an original, cool, minimal instrumental with a soft nylon guitar.\nColor: soft but vibrant — never oversaturated, never desaturated or washed out(muted is off-brand, soft is not dull). Full color range; saturated reds,oranges, blues, greens welcome and a bold color can lead. Build one complementary pairing — a lighter tone against a deeper saturated one, warm against cool (pale blue + vivid red, ivory + crimson, tan + cobalt) — for depth and to separate subject from background. Colors true; no cast, no teal-and-orange or stylized tint. Not over-saturated; contrast controlled, low-to-moderate.\nLighting: soft, diffused, even and dimensional — a large soft close source, or overcast / open shade. Never hard or flat: no bare flash, no harsh sun, no sharp-edged shadows. Fill shadows so texture holds in fabric, skin and surface; shadows soft but present — they give the subject DIMENSION without distracting, and detail stays alive inside them. Low-to-moderate contrast. Light neutral and true, not colored for mood — contrast comes from the colors.",
  "duration": 15,
  "resolution": "720p",
  "generate_audio": true,
  "watermark": false,
  "image_url": "https://msaocnoosm1a4.pika.art/v2/media/uploads/b20e8900-95df-4681-9f1b-a6b5c5abc236/060f7cfb8b154e6185e0bf10fdb570d9.png",
  "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 Flash). |
| `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'. |
| `seed` | integer (0 – 2147483647) | no | - | Seed for a similar result when repeating a request; an exact match is not guaranteed. |
| `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. |

#### Example body

```json
{
  "prompt": "A short multi-shot film with hard cuts between the numbered shots; Shot 1 starts exactly on the first frame. Cuts only change the camera angle on one continuous action - nobody and nothing jumps position between shots, and anyone new is seen arriving. Every shot stays in this same location with the same light. No text or logos appear.\nStory: he opens his perfume, the dragonfly flies off, and he dives in to chase it.\n[Shot 1, 0-5s] Close-up as in the first frame. With his other hand he clearly lifts the round glass cap straight up off the perfume bottle - the dragonfly is sitting on that cap. As the cap comes off, the startled dragonfly takes off from it and darts away over the pool to the right. He holds the open bottle in one hand and the cap in the other. He does NOT spray the perfume - no spray, no mist.\n[Shot 2, 5-9s] Same close-up angle: his head turns sharply to follow where the dragonfly flew, eyes locked on it, deadpan and determined. He sets the bottle down on the tiles beside him and pushes himself up from the pool edge.\n[Shot 3, 9-15s] Wide shot from the far end of the pool at water level: fully dressed in his oversized cream shirt, he dives from the pale tiled edge into the pale aqua water with a clean splash and swims fast freestyle straight across the pool after the small dragonfly, which skims low over the water just ahead of him. With every stroke the soaked cream shirt clings to his back, shoulders and arms, its long sleeves on his arms and the big round collar floating on the water around his neck. Far behind, the small lifeguard on his tall white chair sits up and watches.\nWARDROBE CONTINUITY: his oversized cream shirt is visible on him in every shot - on the pool edge, in mid-air during the dive and while swimming - wet cream fabric on his back and arms the whole time.\nKeep every person's face, hair, wardrobe, the props and the location exactly as in the first frame in every shot.\nSPEED IS CRITICAL: everything moves at normal real-time speed, like 24fps footage played back at 24fps - natural motion, NO slow motion.\nAudio: open-air pool ambience, water lapping at the tiles, the soft glassy clink of the cap lifting off, the dry buzz of dragonfly wings, a big splash and steady swimming strokes; an original, cool, minimal instrumental with a soft nylon guitar.\nColor: soft but vibrant — never oversaturated, never desaturated or washed out(muted is off-brand, soft is not dull). Full color range; saturated reds,oranges, blues, greens welcome and a bold color can lead. Build one complementary pairing — a lighter tone against a deeper saturated one, warm against cool (pale blue + vivid red, ivory + crimson, tan + cobalt) — for depth and to separate subject from background. Colors true; no cast, no teal-and-orange or stylized tint. Not over-saturated; contrast controlled, low-to-moderate.\nLighting: soft, diffused, even and dimensional — a large soft close source, or overcast / open shade. Never hard or flat: no bare flash, no harsh sun, no sharp-edged shadows. Fill shadows so texture holds in fabric, skin and surface; shadows soft but present — they give the subject DIMENSION without distracting, and detail stays alive inside them. Low-to-moderate contrast. Light neutral and true, not colored for mood — contrast comes from the colors.",
  "duration": 15,
  "resolution": "720p",
  "generate_audio": true,
  "watermark": false,
  "image_url": "https://msaocnoosm1a4.pika.art/v2/media/uploads/b20e8900-95df-4681-9f1b-a6b5c5abc236/060f7cfb8b154e6185e0bf10fdb570d9.png",
  "ratio": "adaptive"
}
```

### 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`. 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`, `failed`, or `cancelled`.

### The job object

- `id` (string): Unique identifier for the job.
- `status` (enum): One of `queued`, `running`, `completed`, `failed`, `cancelled`.
- `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":"unexpected_field: Extra inputs are not permitted"}`
- 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 · fast | 7.35 | 10,000 | 0.0735 | 0.37 |
| 720p · fast | 7.35 | 21,600 | 0.1588 | 0.79 |

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