> ## 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

> Use Seedance 2, Fast, and Mini with shared parameters and scenario examples.

Use the Seedance 2 family with `POST https://api.creatok.ai/v1/videos/generation`. Choose a model variant, select a scenario below, then submit its request body and poll the returned job.

## Choose a model

| Variant | `model` | Resolutions | Output duration |
| - | - | - | - |
| Seedance 2 | `seedance-2` | `480p`, `720p`, `1080p`, `4k` | 4–15 seconds |
| Seedance 2 Fast | `seedance-2-fast` | `480p`, `720p` | 4–15 seconds |
| Seedance 2 Mini | `seedance-2-mini` | `480p`, `720p` | 4–15 seconds |

All three variants share the input fields, media modes, and media limits on this page. The examples use `seedance-2` at `480p`. To use Fast or Mini, replace only the root `model` value with the corresponding ID. Keep `definition` at `480p` or `720p` for those variants.

[Seedance 2.5](/models/video/seedance-2.5/generation) has its own limits and supports adaptive editing.

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

For adaptive editing, use [Seedance 2.5](/models/video/seedance-2.5/generation#adaptive-video-editing). These three variants do not accept `generationMode: "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–15; defaults to `4`. |
| `definition` | string | Defaults to `480p`. Use a resolution supported by your variant in the table above. |
| `orientation` | string | `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, or `auto`. Defaults to `9:16` for text/reference modes. You can also set this in frame mode. |
| `referenceImageKeys` | string\[] | Up to 9 uploaded images. [Upload first](/guides/files), then use the returned `file_id`. |
| `referenceVideoKeys` | string\[] | Up to 3 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`. Reference/frame mode is inferred from the media fields when omitted. |
| `autoMatchVideoDuration` | boolean | Omit this field. `true` is not accepted by these variants. |
| `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 |
| Image dimensions | 300–6000 pixels per side |
| Video size | 50 MiB per file |
| Video formats | MP4 or MOV |
| Video duration | 2–15 seconds per video, at most 15 seconds total |
| Video dimensions | 300–6000 pixels per side; 409,600–927,408 total pixels |
| Video frame rate | 23–60 fps |
| Image and video aspect ratio | 0.4–2.5 |

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",
  "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",
  "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",
  "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",
  "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",
  "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",
  "input": {
    "prompt": "The camera moves slowly forward from this opening view",
    "generationMode": "frame",
    "firstFrameKey": "file_11111111-1111-4111-8111-111111111111",
    "seconds": 4,
    "definition": "480p",
    "orientation": "16:9"
  }
}
```

## 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",
  "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",
    "orientation": "16:9"
  }
}
```

## 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.