Seedance 2 - CreatOK API

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 has its own limits and supports adaptive editing.

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`

For adaptive editing, use Seedance 2.5. These three variants do not accept generationMode: "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–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, then use the returned `file_id`.
`referenceVideoKeys`	string[]	Up to 3 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`. 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:

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

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

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.

​Choose a model

​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

​Read the result

​Common errors

Choose a model

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

Read the result

Common errors