> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creatok.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Seedance 2.5

> Generate videos with seedance-2.5: parameters, media requirements, and complete request examples.

Use `model: "seedance-2.5"` with `POST https://api.creatok.ai/v1/videos/generation`. Choose a scenario below, then submit its request body and poll the returned job.

## Supported scenarios

| Scenario | Input fields | Mode |
| - | - | - |
| [Text to video](#text-to-video) | `prompt` | Omit `generationMode` |
| [Single reference image](#single-reference-image) | `prompt`, `referenceImageKeys` | `reference` |
| [Multiple reference images](#multiple-reference-images) | `prompt`, `referenceImageKeys` | `reference` |
| [Reference video](#reference-video) | `prompt`, `referenceVideoKeys` | `reference` |
| [Images and video together](#images-and-video-together) | `prompt`, both reference arrays | `reference` |
| [First frame](#first-frame) | `prompt`, `firstFrameKey` | `frame` |
| [First and last frames](#first-and-last-frames) | `prompt`, `firstFrameKey`, `endFrameKey` | `frame` |
| [Adaptive video editing](#adaptive-video-editing) | `prompt`, `referenceVideoKeys` | Explicitly set `edit` |

## Before you start

Create an [organization API key](/guides/authentication) and fund your API wallet. For images or videos, complete the [signed upload flow](/guides/files) first. Replace each example `file_...` value with the returned `file_id`. You can also use the returned `upload_fields.key`.

> [!NOTE]
>
> These examples use the CreatOK request format. Put generation parameters inside `input`. Media fields accept uploaded file identifiers, not public URLs, base64 strings, or `asset://` identifiers. A prompt is required in every mode.

## Parameters

At the request root, supply `model` and `input`. You can also set `metadata` to a JSON object and `max_cost_usd` to a nonnegative decimal string with up to six decimal places. The cost cap is a spending limit, not a quoted price.

Use these fields inside `input`:

| Field | Type | Rules |
| - | - | - |
| `prompt` | string | Required, nonempty after trimming; at most 8,000 characters. |
| `seconds` | integer | 4–30; defaults to `4`. Omit in edit mode. |
| `definition` | string | `480p`, `720p`, `1080p`; defaults to `480p`. |
| `orientation` | string | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `auto`. Defaults to `9:16` for text/reference modes. Omit in frame and edit modes; those modes use the source aspect ratio. |
| `referenceImageKeys` | string\[] | Up to 30 uploaded images. [Upload first](/guides/files), then use the returned `file_id`. |
| `referenceVideoKeys` | string\[] | Up to 10 uploaded videos. [Upload first](/guides/files), then use the returned `file_id`. |
| `firstFrameKey` | string | An uploaded image; required in frame mode. [Upload first](/guides/files), then use the returned `file_id`. |
| `endFrameKey` | string | An uploaded image; requires `firstFrameKey`. [Upload first](/guides/files), then use the returned `file_id`. |
| `generationMode` | string | `reference` or `frame` or `edit`. Reference/frame mode is inferred from the media fields when omitted. |
| `autoMatchVideoDuration` | boolean | Defaults to `true` in edit mode; `false` is rejected there. `true` is rejected outside edit mode. |
| `watermark` | boolean | Optional watermark setting. |
| `seed` | string | Optional seed, for example `"42"`; do not send a JSON number. Results are not guaranteed to be identical. |

Unknown fields are rejected with `400 invalid_parameter`. The API does not accept `duration`, `resolution`, `size`, `image_urls`, `video_urls`, `audio_urls`, `generate_audio`, or `return_last_frame`. Use the fields documented above.

## Media requirements

| Constraint | Limit |
| - | - |
| Image size | 10 MiB per upload |
| Image formats | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF |
| Image dimensions | 300–6000 pixels per side |
| Video size | 100 MiB per file |
| Video formats | MP4 or MOV |
| Video duration | 2–30 seconds per video, at most 30 seconds total in reference mode; each video must be at least 4 seconds in edit mode |
| Video dimensions | 300–6000 pixels per side; 409,600–8,295,044 total pixels |
| Video frame rate | 23–60 fps |
| Image and video aspect ratio | 0.4–2.5 |

You can combine up to 30 images and 10 videos, with at most 40 reference items in total.

The server checks uploaded media before charging. A successful upload does not guarantee that a file meets the model's requirements. Frame images follow the same image restrictions as reference images.

## Submit a request

Save one complete JSON example below as `request.json`. Set your key and generate an idempotency key once for that request:

```bash theme={null}
export CREATOK_API_KEY="cok_..."
export CREATOK_IDEMPOTENCY_KEY="$(uuidgen)"
```

Submit the file:

```bash theme={null}
curl --fail-with-body --include https://api.creatok.ai/v1/videos/generation \
  -H "Authorization: Bearer $CREATOK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $CREATOK_IDEMPOTENCY_KEY" \
  --data-binary @request.json
```

Keep the same key and body when retrying a network failure or server error. Generate a new key when you switch examples or change any request field. See [Idempotency](/guides/idempotency).

## Text to video

Describe the scene, subject movement, and camera movement. No upload is required.

```json theme={null}
{
  "model": "seedance-2.5",
  "input": {
    "prompt": "A paper lantern floats above a still lake at dusk, slow tracking shot",
    "seconds": 4,
    "definition": "480p",
    "orientation": "16:9"
  }
}
```

## Single reference image

> [!NOTE]
>
> [Upload each reference file first](/guides/files): request a grant with `POST /files`, complete the multipart upload, then replace the sample IDs below with the returned `file_id` values. `upload_fields.key` is also accepted.

Use one image as visual guidance. To specify the opening frame instead, use the first-frame example.

```json theme={null}
{
  "model": "seedance-2.5",
  "input": {
    "prompt": "Show the ceramic mug from the reference image on a sunlit kitchen counter",
    "referenceImageKeys": [
      "file_11111111-1111-4111-8111-111111111111"
    ],
    "seconds": 4,
    "definition": "480p",
    "orientation": "16:9"
  }
}
```

## Multiple reference images

> [!NOTE]
>
> [Upload each reference file first](/guides/files): request a grant with `POST /files`, complete the multipart upload, then replace the sample IDs below with the returned `file_id` values. `upload_fields.key` is also accepted.

Upload every image separately. Describe how the subjects or visual details should appear together. Reference array order does not turn images into first and last frames.

```json theme={null}
{
  "model": "seedance-2.5",
  "input": {
    "prompt": "Place the mug from the first image on the table shown in the second image",
    "referenceImageKeys": [
      "file_11111111-1111-4111-8111-111111111111",
      "file_33333333-3333-4333-8333-333333333333"
    ],
    "seconds": 4,
    "definition": "480p",
    "orientation": "16:9"
  }
}
```

## Reference video

> [!NOTE]
>
> [Upload each reference file first](/guides/files): request a grant with `POST /files`, complete the multipart upload, then replace the sample IDs below with the returned `file_id` values. `upload_fields.key` is also accepted.

Use a video as guidance for a new generation. Set the output duration explicitly; reference mode does not automatically match the source duration. Reference-video duration also contributes to the charge.

```json theme={null}
{
  "model": "seedance-2.5",
  "input": {
    "prompt": "Use the camera movement from the reference video for a scene in a quiet library",
    "referenceVideoKeys": [
      "file_22222222-2222-4222-8222-222222222222"
    ],
    "seconds": 4,
    "definition": "480p",
    "orientation": "16:9"
  }
}
```

## Images and video together

> [!NOTE]
>
> [Upload each reference file first](/guides/files): request a grant with `POST /files`, complete the multipart upload, then replace the sample IDs below with the returned `file_id` values. `upload_fields.key` is also accepted.

Combine visual references with video guidance. Do not add first/end-frame fields to this request.

```json theme={null}
{
  "model": "seedance-2.5",
  "input": {
    "prompt": "Show the mug from the image using a slow camera orbit like the reference video",
    "referenceImageKeys": [
      "file_11111111-1111-4111-8111-111111111111"
    ],
    "referenceVideoKeys": [
      "file_22222222-2222-4222-8222-222222222222"
    ],
    "seconds": 4,
    "definition": "480p",
    "orientation": "16:9"
  }
}
```

## First frame

> [!NOTE]
>
> [Upload each reference file first](/guides/files): request a grant with `POST /files`, complete the multipart upload, then replace the sample IDs below with the returned `file_id` values. `upload_fields.key` is also accepted.

Use an uploaded image as the opening frame. Omit both reference arrays. The mode can be inferred, but this example sets it explicitly.

```json theme={null}
{
  "model": "seedance-2.5",
  "input": {
    "prompt": "The camera moves slowly forward from this opening view",
    "generationMode": "frame",
    "firstFrameKey": "file_11111111-1111-4111-8111-111111111111",
    "seconds": 4,
    "definition": "480p"
  }
}
```

## First and last frames

> [!NOTE]
>
> [Upload each reference file first](/guides/files): request a grant with `POST /files`, complete the multipart upload, then replace the sample IDs below with the returned `file_id` values. `upload_fields.key` is also accepted.

Upload both images. The first image starts the video and the second supplies the ending frame. An end frame alone is not accepted. Do not include reference arrays.

```json theme={null}
{
  "model": "seedance-2.5",
  "input": {
    "prompt": "Move smoothly from the opening view to the final view",
    "generationMode": "frame",
    "firstFrameKey": "file_11111111-1111-4111-8111-111111111111",
    "endFrameKey": "file_33333333-3333-4333-8333-333333333333",
    "seconds": 4,
    "definition": "480p"
  }
}
```

## Adaptive video editing

> [!NOTE]
>
> [Upload each reference file first](/guides/files): request a grant with `POST /files`, complete the multipart upload, then replace the sample IDs below with the returned `file_id` values. `upload_fields.key` is also accepted.

Set `generationMode: "edit"` explicitly. Upload a source video of 4–30 seconds. Its duration and aspect ratio determine the output, so omit `seconds` and `orientation`. `autoMatchVideoDuration` defaults to `true`; setting it to `false` is rejected.

```json theme={null}
{
  "model": "seedance-2.5",
  "input": {
    "prompt": "Change the room lighting to warm evening light while preserving the camera movement",
    "generationMode": "edit",
    "referenceVideoKeys": [
      "file_22222222-2222-4222-8222-222222222222"
    ],
    "autoMatchVideoDuration": true,
    "definition": "480p"
  }
}
```

You can add `referenceImageKeys` for visual guidance. If you supply several reference videos, the first determines the output duration and aspect ratio. All reference videos contribute to the total duration limit and token pricing. Output duration is not guaranteed to be frame-exact.

## Read the result

HTTP `202` returns a job directly. Read its `id` and `status`; there is no `data` wrapper. A submission can already have `status: "failed"`, so do not treat `202` as generation success.

While the job is `queued` or `running`, wait the number of seconds in `Retry-After`, then retrieve it:

```bash theme={null}
curl --fail-with-body --include https://api.creatok.ai/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $CREATOK_API_KEY"
```

Replace `JOB_ID` with the returned `id`. Continue until the status is `succeeded`, `failed`, or `canceled`. On success, download the video URL in `output.files`. URLs last about one hour; retrieve the job again for a fresh URL. Copy the output to your storage before `expires_at`, 48 hours after completion.

For a complete polling and download script, see [Quickstart](/quickstart#complete-example). See [Jobs and polling](/guides/jobs) for response fields and refunds.

## Common errors

| Result | What to check |
| - | - |
| `400 invalid_parameter` | Check the model's field values, uploaded files, and media limits. Do not mix frame inputs with reference arrays. |
| `400 missing_parameter` | Supply a nonempty `Idempotency-Key` of at most 255 characters. |
| `400 max_cost_exceeded` | The quote exceeds your cost cap. Review the input or cap before resubmitting. |
| `402` | Check that your API wallet is enabled and has sufficient balance. |
| `409 idempotency_key_reused` | You changed the request while reusing a key. Use the original body for a retry or a new key for a new job. |
| `429 concurrency_limited` | Wait `Retry-After` seconds and retry with the same key and body. |
| Job `failed` | Read `error.code` and `cost.refunded_usd`. To request another generation, use a new key. |

See [Errors](/guides/errors) for all error codes. See the [pricing page](https://www.creatok.ai/app/api-platform/pricing) for current rates and [token pricing](/guides/video-models#pricing) for how media affects usage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.