Seedance 2.5 - CreatOK API

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	`prompt`	Omit `generationMode`
Single reference image	`prompt`, `referenceImageKeys`	`reference`
Multiple reference images	`prompt`, `referenceImageKeys`	`reference`
Reference video	`prompt`, `referenceVideoKeys`	`reference`
Images and video together	`prompt`, both reference arrays	`reference`
First frame	`prompt`, `firstFrameKey`	`frame`
First and last frames	`prompt`, `firstFrameKey`, `endFrameKey`	`frame`
Adaptive video editing	`prompt`, `referenceVideoKeys`	Explicitly set `edit`

Before you start

Create an organization API key and fund your API wallet. For images or videos, complete the signed upload flow first. Replace each example file_... value with the returned file_id. You can also use the returned upload_fields.key.

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, then use the returned `file_id`.
`referenceVideoKeys`	string[]	Up to 10 uploaded videos. Upload first, then use the returned `file_id`.
`firstFrameKey`	string	An uploaded image; required in frame mode. Upload first, then use the returned `file_id`.
`endFrameKey`	string	An uploaded image; requires `firstFrameKey`. Upload first, 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:

export CREATOK_API_KEY="cok_..."
export CREATOK_IDEMPOTENCY_KEY="$(uuidgen)"

Submit the file:

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.

Text to video

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

{
  "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

Upload each reference file first: 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.

{
  "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

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.

{
  "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

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.

{
  "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

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

{
  "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

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

{
  "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

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.

{
  "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

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.

{
  "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:

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. See Jobs and polling 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 for all error codes. See the pricing page for current rates and token pricing for how media affects usage.

​Supported scenarios

​Before you start

​Parameters

​Media requirements

​Submit a request

​Text to video

​Single reference image

​Multiple reference images

​Reference video

​Images and video together

​First frame

​First and last frames

​Adaptive video editing

​Read the result

​Common errors

Supported scenarios

Before you start

Parameters

Media requirements

Submit a request

Text to video

Single reference image

Multiple reference images

Reference video

Images and video together

First frame

First and last frames

Adaptive video editing

Read the result

Common errors