Get started
Debug a failed Seedance request
- 1
Read the code, not the message
Branch on code (request errors) or job.errorCode (job errors); messages can change, codes do not.
- 2
Check limits first
Most 400s are a duration, resolution or aspect ratio the model does not offer. GET /v1/models lists each model's limits.
- 3
Respect 429s
Wait the seconds in Retry-After before sending again.
- 4
Resend safely
After a timeout, resend with the same Idempotency-Key. After a declined prompt, change it and use a new key.
Request errors (the HTTP call fails)
| Code | Status | Meaning | Fix |
|---|---|---|---|
| invalid_api_key | 401 | The key is missing, wrong or revoked. | Send Authorization: Bearer <key>. Create a new key if it was revoked. |
| insufficient_balance | 402 | Not enough tokens for the quoted cost. | Top up under Billing. data.top_up_url links there. |
| account_not_active | 403 | The developer account is suspended. | Contact support. |
| scope_missing | 403 | The key lacks the scope this endpoint needs. | Use a key with that scope. |
| job_not_found | 404 | No job with that id for this key's account. | Check the id; jobs are private to the account. |
| character_not_found | 404 | The character id or slug doesn't exist. | List characters with GET /v1/characters. |
| upload_not_found | 404 | The upload_id doesn't exist in this workspace. | Create the upload again. |
| reference_upload_not_developer | 400 | The upload_id is a file uploaded on the website, not through the API. | Upload this file with /v1/uploads first. |
| reference_upload_not_found | 404 | A reference upload_id doesn't exist in this workspace. | Re-upload the file and use the new upload_id. |
| video_edit_source_not_found | 404 | The source_video_upload_id doesn't exist. | Upload the clip with upload_type VIDEO. |
| upload_in_use | 409 | A queued or processing job still uses this upload. | Delete it after the job finishes. |
| character_pending | 409 | The character is still being reviewed. Nothing was reserved. | Wait retry_after seconds, then retry. |
| upload_too_large | 413 | The file is over the size limit for its type. | Images 50 MB, video 200 MB, audio 15 MB. |
| character_registration_failed | 422 | The character image did not pass review. | Register the character again with another image. |
| rate_limited | 429 | Too many requests in the window. | Wait the seconds in the Retry-After header. |
| prompt_required | 400 | No prompt (or text for speech) was sent. | Add a prompt. |
| prompt_too_long | 400 | The prompt is over the model's limit. | Shorten it; GET /v1/models lists maxPromptChars. |
| model_not_found | 400 | Unknown model alias. | Use an id from GET /v1/models. |
| duration_not_supported | 400 | The model doesn't offer that length. | Send one of the model's durations. |
| aspect_ratio_not_supported | 400 | The model doesn't offer that aspect ratio. | Send one of the model's aspect ratios. |
| resolution_not_supported | 400 | The model doesn't offer that resolution. | Send one of the model's resolutions. |
| reference_combination_not_supported | 400 | These references can't be combined, e.g. start/end frames with reference images. | Send one kind per request. |
| upload_invalid | 400 | The upload request is missing a field or has a bad type. | Send file_name, mime_type, file_size and upload_type. |
| video_edit_model_not_supported | 400 | Video edits need a Seedance 2.0 family model (2.0, Fast or Mini). | Use kreator-video-pro, kreator-video-fast or kreator-video-mini. |
| video_edit_source_required | 400 | A video edit needs a source clip. | Send source_video_upload_id or video. |
| voice_required | 400 | Speech needs a voice. | Use an id from GET /v1/voices. |
| paid_account_required | 403 | Lip Sync needs a paid account. Nothing was charged. | Top up with a card under Billing. |
| paid_check_unavailable | 503 | The account's payment status could not be read just now. Nothing was charged. | Send the same request again in a moment. |
| audio_reference_too_long | 400 | The audio references add up to more than the model accepts in total (15 s on Seedance 2.0, 30 s on 2.5). Nothing was charged. | Trim or remove audio so all audio references combined fit. |
| image_upload_not_found | 404 | The image_upload_id isn't in this workspace. | Upload the photo with upload_type IMAGE and use the new upload_id. |
| audio_upload_not_found | 404 | The audio_upload_id isn't in this workspace (or audio_job_id isn't a completed /v1/audio job). | Upload the track with upload_type AUDIO, or use a completed audio job id. |
| audio_too_short | 400 | The voice track is under 4 seconds. Nothing was charged. | Send 4 seconds to 5 minutes of audio. |
| audio_too_long | 400 | The voice track is over 5 minutes. Nothing was charged. | Trim it to 5 minutes or less. |
| audio_unreadable | 400 | The audio couldn't be read. Nothing was charged. | Use an MP3 or WAV under 15 MB. |
| image_rejected | 422 | The photo didn't pass the safety check. Nothing was charged. | Use a different photo. |
| internal_error | 500 | Something failed on our side. | Retry with the same Idempotency-Key. |
| dispatch_disabled | 503 | Generation is paused for this environment. | Retry later. |
Job errors (the job ends as failed, tokens released)
| Code | Meaning | Fix |
|---|---|---|
| reference_rejected | A reference did not pass screening. | For a real person you have consent to use, register the face as a character (reviewed once, then reused), or use another image. |
| reference_asset_pending | A new reference is still being reviewed. | Wait errorData.retry_after seconds, resubmit with the same upload_id and a new Idempotency-Key. |
| reference_asset_failed | The reference did not pass review. | Use a different file. |
| generation_rejected | The request was declined (prompt, reference or options). | Change the prompt, reference or options, then retry. |
| generation_timeout | The job did not finish in time. Reserved tokens are released. | Retry with a new Idempotency-Key. |
| generation_unavailable | The model is temporarily unavailable. | Retry later or pick another model. |
| generation_failed | The generation failed. | Retry; change the prompt or references if it repeats. |
Seedance API price per second on KreatorFlow
Seedance 2.0 and 2.5 at 720p and above on the KreatorFlow API: price per second, tokens per 5-second clip, and clips per prepaid top-up.
| Model · resolution | Tokens | 5 s clip | List rate per second | $20 top-up · 400 tokens | $50 top-up · 1,000 tokens | $100 top-up · 2,000 tokens | $250 top-up · 5,000 tokens |
|---|---|---|---|---|---|---|---|
| Seedance 2.0 · 720p | 11/5s | $0.55 | $0.110/s | 36 | 90 | 181 | 454 |
| Seedance 2.0 · 1080p | 24/5s | $1.20 | $0.240/s | 16 | 41 | 83 | 208 |
| Seedance 2.0 · 4K | 58/5s | $2.90 | $0.580/s | 6 | 17 | 34 | 86 |
| Seedance 2.5 · 720p | 21/5s | $1.05 | $0.207/s | 19 | 47 | 95 | 238 |
| Seedance 2.5 · 1080p | 45/5s | $2.25 | $0.444/s | 8 | 22 | 44 | 111 |
| Seedance 2.5 · 4K | 100/5s | $5.00 | $0.999/s | 4 | 10 | 20 | 50 |
Seedance 2.0 and 2.5, 720p and above. List rate per second is the rate card price; a clip is billed at that rate and its total rounded up to whole tokens ($0.05), which is why a 5-second clip can cost a cent or two more than rate x 5. Top-up columns: 5-second clips each top-up covers, without a video input. A 10-second clip uses about twice the tokens.
Why was my reference rejected?
References and prompts that ask to match a real person, a celebrity or a public figure are declined. That covers photos of real people used as references and prompts that name a person to imitate. Describe appearance, wardrobe and style instead, or register a character you own with POST /v1/characters and pass its id.
Why does the output have a different aspect ratio?
With an input image or first frame, adaptive follows the image. Send an explicit aspect_ratio when the output must match a format, and check the model offers it.
Why did camera_fixed fail with an image input?
Leave camera_fixed out when you send an image or frame input, and describe the camera in the prompt instead (for example locked-off camera).
Frequently asked questions
Am I charged when a Seedance job fails?
No. A failed job's reserved tokens are released.
What does insufficient_balance mean?
Your token balance is lower than the job's quote. Top up in the console; nothing was reserved.
What should I do on a 429?
Wait the number of seconds in the Retry-After header, then send again.
Why was my prompt declined?
It asked to match a real person or broke the acceptable use policy. Change the prompt and create a new job.
