Seedance 2.0 Mini API docs & examples

Authentication

Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create an API Key in the console to start.

Request body

Parameter	Type	Required	Description
model	string	Yes	Model ID, here seedance-2.0-mini.
prompt	string	Yes	Text prompt describing the video, camera and motion. Max 5000 bytes (UTF-8; a Chinese character counts as 3). With multiple reference images you can address them as @Image1 / @Image2 in the prompt, e.g. "the character from @Image1 in the scene from @Image2"; without tokens the model decides on its own.
duration	integer	No	Length in seconds, any integer 5-15 (default 5); alias seconds. Billed per second.
resolution	string	No	Resolution: 480P / 720P (default 720P; each tier has its own rate, see the model page).
size	string	No	Aspect ratio: 16:9 / 9:16 / 1:1 / 4:3 / 3:4 (16:9 default); alias aspect_ratio.
audio	boolean	No	Every clip comes with sound (dialogue, effects and music generated from the prompt); it cannot be switched off, and `false` has no effect.
image	string	No	One reference image (public URL, data: URI or base64), handed to the model as a reference for the characters, objects, scene or style; use images for several. This line has no first-frame control, so the image is not guaranteed to open the clip. With no references at all it is text-to-video.
images	array	No	Multiple reference images, up to 9 for this model. Each item may be a public URL, a data: URI, or base64. Exceeding the cap is rejected, never truncated. Alias: reference_images. Each image up to 16 MB, jpg / png / webp / gif; address them in order as @Image1, @Image2, ... in the prompt.
image_role	string	No	Optional. Reference images are always used as references (characters, scene, style), addressed as @Image1... in the prompt; the model has no first/last-frame control.
audio_reference	string / array	No	Public http(s) URL(s) for reference audio, up to 3. Must accompany a reference image or video; alias audio_references (do not send both). Base64 works too (data:audio/mpeg;base64,...), mp3 / wav / m4a; address it as @Audio1 in the prompt.
video_references	array	No	Reference videos, up to 3. Each may be a public http(s) URL or a local file sent inline as base64 (data:video/mp4;base64,..., mp4 / mov, up to 50 MB each); we host it and hand the link to the upstream. May be combined with reference images in the same request (e.g. photos for the characters' looks, a video for motion and camera) - address them in the prompt as @Image1 / @Video1. Each video at most 30 s, 15 s in total; references we host are kept for 7 days.

Request example

cURL

# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://kovapi.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "seedance-2.0-mini", "prompt": "a cat surfing a wave at sunset", "duration": 5, "resolution": "720P", "size": "16:9"}'
# with references: add "images": ["https://example.com/a.png"], "video_references": ["https://example.com/move.mp4"], "audio_reference": ["https://example.com/bgm.mp3"] and name them @Image1 / @Video1 / @Audio1 in the prompt
# 2) poll every ~5s until status=succeeded, then read data[0].url
curl https://kovapi.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'

Response

200 · JSON

{
  "id": "img_3f9a...c2",
  "object": "video.generation.job",
  "status": "queued",
  "model": "seedance-2.0-mini"
}

Async video job (submit → poll)

Submitting returns HTTP 202 and a job id right away; poll until status=succeeded and read data[0].url (an mp4 link). The allowed duration, resolution and size values are in the parameter table above; add an image param for image-to-video.

curl · submit (text-to-video)

curl https://kovapi.com/v1/videos/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "seedance-2.0-mini", "prompt": "a cat surfing at sunset", "size": "16:9"}'

With references: images (reference images), video_references (reference videos) and audio_reference (reference audio) can go together in one request, as public URLs, data: URIs or base64; name them @Image1 / @Video1 / @Audio1 in the prompt. Reference images set the subject, scene and style; they are not used as the first frame.

Real human faces work as reference images, no masking needed. Please make sure you have the right to use the likeness of anyone pictured.

Response Example

{ "id": "img_3f9a...c2", "object": "video.generation.job", "status": "queued", "model": "seedance-2.0-mini" }

curl · poll

curl https://kovapi.com/v1/videos/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'

Response Example

{
  "id": "img_3f9a...c2",
  "object": "video.generation.job",
  "status": "succeeded",
  "model": "seedance-2.0-mini",
  "data": [{ "url": "https://img.kovapi.com/i/9f86d081a8....mp4" }]
}

🕑 data[0].url is a link on our image host that is kept for 15 days and then deleted automatically; to keep using it, download it and store it on your own storage or CDN.

Billed per second ($0.046/s x duration); the hold equals the settle exactly, and a failed or timed-out render is refunded in full automatically.

Rather not poll? Add callback_url when you submit and we push the result to your server when the job ends, or set a default endpoint in the console. Webhook docs →

Content requirements

Every Seedance job goes through content review: the prompt, the reference files and the finished clip, picture and sound alike. A job that fails review ends with content_policy and is not charged.

When review happens

The prompt and references are reviewed at submit; the finished clip is reviewed again, picture and sound, once it is generated. A rejection can therefore arrive seconds after submitting or only when rendering ends, which can take over half an hour. A job that ends with status failed and error.code content_policy failed review; with a webhook you receive a video.failed event.

Not charged

A rejected job costs nothing: the amount held at submit is refunded in full when the job ends, and the call log shows it as not billed.

Sound

The soundtrack (dialogue, narration, singing and effects) is generated by the model from your prompt and reviewed with the picture: spoken lines, narration and lyrics in the prompt are voiced or sung. For a clip without voices, leave lines and lyrics out of the prompt. This model always adds a soundtrack; it cannot be turned off, and audio: false has no effect. Uploaded reference audio is reviewed too, and copyrighted music used as reference audio may be rejected. When the sound fails review, error.param is audio and the message says whether it was the generated sound or your reference audio.

Commonly rejected content

Sexual content, nudity or sexual suggestion, including AI-generated or composited images
Gore, cruelty, self-harm, and violent injury such as gunshot wounds and bleeding
Firearms, explosives and drugs
Any sexualised content involving minors; minors shown with alcohol, tobacco, drugs or in dangerous situations are rejected too
Politicians, celebrities, athletes, business figures and other public figures, in looks or voice, including look-alikes
Copyrighted characters and IP, such as Disney or Marvel characters
Hateful or discriminatory content, and fake news

Long storyboard scripts

One shot that breaks the rules fails the whole clip, and long storyboard scripts are where it happens most: a gunfight or a close-up of bleeding in an action scene, or minors in a drinking or smoking scene, sink the whole clip. Read the script through before submitting and remove or rewrite such shots.

Real people

To use a photo of a real person as a reference you need the right to use their likeness; whether a model accepts real-person references is stated above on this page.

After a rejection

Resubmitting the same input is rejected again. Find the part that is likely at fault, reword the prompt or replace the reference, then submit again.

Error code: content_policy · status: failed

Error codes

Every error carries error.message / error.type / error.code / error.param; branch on code. The most common ones are below; the full list is under Error codes.

HTTP	code	Description
401	invalid_api_key	No key, or the key is invalid or disabled (`missing_api_key`, `invalid_api_key`).
402	insufficient_quota	Not enough balance, or the key has reached its budget (`insufficient_quota`).
400	invalid_request	A bad parameter or an unknown model (such as `model_not_found`); `error.param` names the field.
—	content_policy	Content review failed: the prompt, a reference, or the generated picture or sound was flagged. Not billed; the same input is rejected again, so reword the prompt or replace the reference. Video jobs return it in `error` when `status` is `failed`.
429	rate_limit_exceeded	Over the per-minute limit set on this key or a free model's daily quota, or the model is at capacity (`rate_limit_exceeded`). Wait the seconds in `Retry-After` when it is there, otherwise a few seconds, then retry.
502	upstream_*	The upstream failed or timed out and the automatic retries did not help; `code` says why, e.g. `upstream_timeout` or `upstream_unavailable`. Not billed; safe to retry.

Full list of error codes →

Seedance 2.0 Mini · API