doubao-seedance-2.5 is also available: clips up to 30 seconds, up to 1080p, and up to 30 reference images per request.
Available models
URLs & auth
- Base URL:
https://www.ruapi.ai/v1 - Auth: header
Authorization: Bearer sk-YOUR_KEY(create one in the console under “API Keys”)
Submit a task
POST /v1/videos → returns a task idPoll the status
GET /v1/videos/{id} → until status becomes completedDownload the video
GET /v1/videos/{id}/content → get the MP4Step 1. Submit a task (text-to-video)
id is the task number, used in the next two steps):
Step 2. Poll the status
Query theGET /v1/videos/{id} route about every 5 seconds. status goes through queued → in_progress → completed.
metadata.url is the download link):
Step 3. Download the video
Full example: the whole flow in one script
Copy-paste and run, replacingsk-YOUR_KEY with your own key:
The same with curl
One command for macOS, Linux and Windows (Git Bash / WSL): it submits the task, waits until it is ready (usually 2–5 minutes) and savesseedance.mp4. Put your key on the first line. If anything goes wrong, it prints the API response with the reason.
Parameters
Top-level fields:metadata:
480p / 5 seconds, then tune.The four input modes
input_type usually doesn’t need to be set — it’s inferred from the number of images/videos; you can also set it explicitly via metadata.input_type.
doubao-seedance-2.0 and doubao-seedance-2.5 also accept them as reference images or first and last frames. For reference images and first and last frames on -mini and -fast, add "auto_create_assets": true to metadata — see the FAQ below.Mode 1. Text-to-video
Just a textprompt — generated entirely from the description.
Mode 2. Image-to-video: first frame (1 image)
Put 1 image URL inmetadata.images: it becomes the first frame, and the model animates the scene from it. Describe the motion / camera in prompt. To use the image only as a reference (keep the character or style without starting from it), add "input_type": "reference" to metadata.
Mode 3. Image-to-video: first and last frames (2 images)
Put 2 images inmetadata.images: the 1st = start frame, the 2nd = end frame. It generates a smooth transition from the first to the second.
Mode 4. Omni reference-to-video (1 reference video)
Put 1 short video URL inmetadata.videos; the model reinterprets it while keeping the subject’s motion (e.g. restyle or change the scene).
doubao-seedance-2.5, set "ratio": "adaptive". If the prompt sounds like “continue this video”, the model may decide on its own to extend the video, and an extension accepts only adaptive: with any other ratio, the task fails with the code InvalidParameter.TaskTypeConstraint in error. To edit or extend a video explicitly, see “Video editing and extension in Seedance 2.5” below.Advanced: multiple images / videos
images and videos are arrays — you can pass several references at once (both verified):
- Multiple images: put 3 or more images in
images(officially up to 9; up to 30 ondoubao-seedance-2.5). The model combines subject / scene / style across them. With 3+ images,input_typeis auto-detected asreference. - Multiple videos: put 2 or more clips in
videos(officially up to 3, total duration ≤ 15 seconds; ondoubao-seedance-2.5up to 10, total ≤ 30 seconds).
images with videos and pass several short clips (each ideally ≤ 7 seconds with a clear subject, ≤ 15 seconds total; ≤ 30 seconds total on doubao-seedance-2.5).Reference audio
Pass an array of audio file URLs inmetadata.audios — for example, a voice or music for the model to follow. Like images and videos, audio must be reachable at a public URL.
doubao-seedance-2.0,-fastand-mini— up to 3 audio files, and only together with at least one image or video: a request with audio only returns400.doubao-seedance-2.5— up to 10 audio files; audio alone also works, without images or videos: for example, the scene is described in text and the sound follows the reference audio.
doubao-seedance-2.5. When a request contains audio or video, images act as references rather than as the first frame. Reference audio is not charged separately: the same video uses the same number of tokens with or without it.
Silent video
Seedance generates videos with sound by default. To get a clip without an audio track, pass"generate_audio": false: inside metadata for POST https://www.ruapi.ai/v1/videos, or at the top level of the request in the ModelArk format.
Task statuses
How many videos can run at once
Each account can have at most 3 unfinished video tasks at a time (queued or in progress) — one limit shared by all keys and models of the account. Any further task is rejected immediately with429, the code video_concurrency_limit and the header Retry-After: 30; it is not charged. Wait until one of your tasks finishes, then submit again.
If you need more parallel tasks, contact support at support@ruapi.ai or on Telegram @RuAPI_Support.
Completion callbacks
Instead of polling, you can ask RuAPI to notify your server when a task finishes. When creating the task, pass:callback_url— where the notification goes:https://only, a public address only (notlocalhostor an internal network), no username or password in the URL, up to 1024 characters;callback_secret(optional) — a secret used to sign the notification, up to 256 characters.
POST https://www.ruapi.ai/v1/videos both fields can go inside metadata or at the top level of the request; in the ModelArk format they go at the top level. If the URL isn’t acceptable, the task isn’t created: you get 400 with the code invalid_callback, and nothing is charged.
POST request to callback_url. The body is the same JSON a status request would return at that moment: GET https://www.ruapi.ai/v1/videos/{id} for tasks created via /v1/videos, or GET https://www.ruapi.ai/v1/contents/generations/tasks/{id} for tasks in the ModelArk format. Intermediate statuses are not sent.
2xx code within 10 seconds. Otherwise RuAPI retries after about 10 seconds, 1 minute and 5 minutes — 4 attempts in total, then it stops. Redirects (3xx) are not followed and count as a failure. Reply 200 right away and do slow work (such as downloading the video) in the background. If every attempt fails, check the status with a regular GET request.
Verifying the signature
Compute the signature over the raw request body — before parsing the JSON — and compare it with the header using a constant-time comparison (hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js). It’s a good idea to reject notifications older than a few minutes.
Listing and deleting tasks
List.GET https://www.ruapi.ai/v1/videos returns the tasks created with the same API key that makes the request; tasks from the account’s other keys are not listed. You can fetch or delete a specific task by id with any key of the account.
{"object": "list", "data": [...], "first_id": "...", "last_id": "...", "has_more": false}; data holds the same objects that GET https://www.ruapi.ai/v1/videos/{id} returns.
Delete. DELETE https://www.ruapi.ai/v1/videos/{id} deletes a finished task (completed or failed) and returns {"id": "...", "object": "video.deleted", "deleted": true}. After that the task is gone from the list, GET https://www.ruapi.ai/v1/videos/{id} returns an error with the code task_not_exist, and the download link stops working — save the video first.
BytePlus ModelArk format: /v1/contents/generations/tasks
If you already have code for the BytePlus ModelArk (Volcengine Ark) API, you don’t need to rewrite it for/v1/videos: RuAPI accepts requests in that format too. In your code, replace the API address (…/api/v3) with https://www.ruapi.ai/v1, the key with your RuAPI key, and the model name with one of ours from the table above (for example, doubao-seedance-2.5; the dated model IDs from the ModelArk docs won’t work). Requests and responses follow the official ModelArk format, plus two RuAPI extension fields that aren’t in the official docs: auto_create_assets and reference_video_task_id; the pre-charge, prices and the 3-task limit are the same as for /v1/videos.
GET https://www.ruapi.ai/v1/contents/generations/tasks/{id} once the task is done:
status:queued→running→succeededorfailed(reason inerror). RuAPI never returnscancelledorexpired.content.video_urlis a signed download link: it needs no API key and is valid for 24 hours from the status request, but the video itself is only kept for 23 hours after the task completes. If the link has expired (403with the codelink_expired), query the status again to get a fresh one.- Pass generation settings such as
resolution,ratio,durationandgenerate_audioas JSON fields. Commands inside the prompt text such as--dur 10or--rs 1080pare not supported — such a request gets400. - Text in
contentis optional when the request has an image, video or audio (modelsdoubao-seedance-2.0,doubao-seedance-2.0-fast,doubao-seedance-2.0-minianddoubao-seedance-2.5), for example just a first frame. Audio alone, without images or videos, is accepted only bydoubao-seedance-2.5. A request with neither text nor media gets400. - Errors come in the ModelArk format:
{"error": {"code": "...", "message": "..."}}. callback_urlandcallback_secretgo at the top level; the notification arrives in the ModelArk format (see “Completion callbacks” above).
Draft mode in Seedance 2.5: preview before 1080p
A 1080p clip costs noticeably more than a 480p one. In draft mode,doubao-seedance-2.5 first renders a cheap 480p sample that shows the composition, motion and sound. If you like it, the final 1080p video is made from that same draft: the prompt, references, duration, aspect ratio, sound and seed all come from the draft. If you don’t, change the prompt and make a new draft without paying for 1080p.
Drafts work only with doubao-seedance-2.5 and only through https://www.ruapi.ai/v1/contents/generations/tasks. In POST https://www.ruapi.ai/v1/videos the draft field has no effect — you get a regular video.
Make a draft (480p)
"draft": true. The resolution can only be 480p (you can omit it; any other value returns 400). It’s charged like a regular 480p video of the same length: for example, about $0.52 for 4 seconds.Make the final video (1080p)
succeeded, submit a new task whose content holds only the draft reference {"type": "draft_task", "draft_task": {"id": "<draft id>"}}, plus the required "resolution": "1080p". You may also pass callback_url and callback_secret; text, images, videos, audio, duration, ratio, generate_audio and seed are not accepted in this step (400).{"id": "task_..."} — that’s the draft id. Wait for succeeded, watch the clip at content.video_url, and if it works for you, send the second step:
- the draft was created by your account with
"draft": true, finished successfully and has not been deleted; - the model is the same —
doubao-seedance-2.5; - no more than 7 days have passed since the draft was created (otherwise
400with the codedraft_task_expired).
400 with the code draft_unavailable — make a new draft. The final video is charged at the 1080p rate without a reference video (see the table below): the pre-charge is based on the draft’s duration, the final amount on the actual tokens.
Video editing and extension in Seedance 2.5
doubao-seedance-2.5 can edit an existing video or continue it. Add omni_reference_task_type (the task type hint) to the request and pass the source video as a reference video:
"auto"), the model decides what to do from the input assets and the prompt.
Rules:
- only
doubao-seedance-2.5supports it; other models return400; - at least 1 reference video is required:
metadata.videos, or a video with"role": "reference_video"incontentin the ModelArk format; first and last frame images can’t be used with it; ratiocan only be"adaptive"or omitted (thenadaptiveis used and the aspect ratio follows the source video);- edit: the result is as long as the source video, so
durationcan only be-1or omitted (with/v1/videos, leave outsecondstoo); - extend:
durationis the length of the new segment (4–30 seconds, 5 if omitted). The result does not include the source video: its first frame is the last frame of the source video. For one long video, join the source video and the new segment yourself; - it can’t be combined with draft mode.
POST https://www.ruapi.ai/v1/videos they go inside metadata. An edit example (ModelArk format):
/v1/videos, 4 more seconds):
-1, so the estimate assumes the longest 30-second result plus 30 seconds of reference video (about $4.65 for 480p at the standard price), and your balance must cover it. On completion the charge is settled by the actual tokens and the excess goes back to your balance.
If the source video shows a real person (including videos generated on RuAPI): with doubao-seedance-2.0 or doubao-seedance-2.5 you can usually send it directly; doubao-seedance-2.0-mini and doubao-seedance-2.0-fast usually reject such videos — switch to 2.0 / 2.5, or see “Reusing a generated video: reference_video_task_id” below.
A reference video needs at least about 410,000 pixels (for example 854×480; a 480p video in 4:3 or 21:9 may fall short, so use 720p); smaller videos are rejected, and you aren’t charged.
MOV output in Seedance 2.5
doubao-seedance-2.5 outputs MP4 by default. For a MOV (QuickTime) file, add "output_format": "mov": at the top level of the request in the ModelArk format, or inside metadata for POST https://www.ruapi.ai/v1/videos. The price is the same as for MP4. On other models "mov" returns 400.
GET https://www.ruapi.ai/v1/videos/{id}/content returns a MOV file (Content-Type: video/quicktime), so save it with the .mov extension. output_format can go in the same request as an edit or an extension; the second step of a draft doesn’t support it.
Reusing a generated video: reference_video_task_id
A video with a real person in it, passed directly as a reference video, usually works withdoubao-seedance-2.0 and doubao-seedance-2.5, but doubao-seedance-2.0-mini and doubao-seedance-2.0-fast usually reject it (error code InputVideoSensitiveContentDetected.PrivacyInformation) — even if the video was generated on RuAPI. To edit or extend such a video with mini / fast, or to make a new one from it, add its task id to the request as reference_video_task_id. The task id tells the model that the video is its own output, so it may accept it — worth a try. This doesn’t work for every video — see the requirements below.
This is a RuAPI extension field (it isn’t in the official ModelArk docs) and works only in the ModelArk format — POST https://www.ruapi.ai/v1/contents/generations/tasks, at the top level of the request. In POST https://www.ruapi.ai/v1/videos the field has no effect: the video is passed as a regular reference video.
reference_video_task_idis the id of a video task from your account (task_...) that finished successfully no more than 23 hours ago and has not been deleted;- the same video must be in
contentexactly once, with"role": "reference_video"; for the URL, usecontent.video_urlfrom the status response orhttps://www.ruapi.ai/v1/videos/{task id}/content; - use the same model that generated the source video: when referencing by task id with a different model, even another Seedance 2.0 / 2.5 one, a video with a real person will most likely still be rejected (sending the video directly to
doubao-seedance-2.0/doubao-seedance-2.5without a task id usually works, see above); - it can’t be combined with
auto_create_assetsordraft_task; a draft (the 480p sample) can’t be the source video either — make the final video from it first and use that; omni_reference_task_type(edit, extend) andoutput_formatcan go in the same request if the backend that generated the source video supports them (otherwise you getunsupported_by_channel).
400 with the code unsupported_by_channel, and nothing is charged. At the moment this works for videos generated with auto_create_assets; for other videos it may not. Videos without real people don’t need this field: download the video and pass it as a regular reference video from your own public URL.
It’s billed like any request with a reference video: the source video’s length counts toward the tokens (see the billing note in “Video editing and extension in Seedance 2.5” above).
Errors for this feature (all 400, nothing is charged):
Billing
Video is billed per token: tokens ≈ width × height × seconds × 24 ÷ 1024 (480p is about 10K tokens per second). The per-token price depends on the resolution and on whether a reference video is used. Price per 1M tokens by tier (standard prices — what the pricing page shows with “Standard” selected, 6 Nov 2026; new accounts on their first top-up and accounts with $100+ in top-ups pay less):doubao-seedance-2.0-mini. With a reference video the per-token price is lower, but the reference video’s tokens are counted too. Only successful videos are charged.
On submit, a pre-charge is held — a deliberately generous estimate:
- resolution — as set in the request; if omitted, the video is generated and billed at
720p; - duration — as set in the request; if omitted, 5 seconds; for
-1, the maximum: 15 seconds, or 30 ondoubao-seedance-2.5; - tokens per second — for the “heaviest” aspect ratio at that resolution;
- reference videos — on the 2.0 models, 15 seconds are added per reference video (up to three are counted); on
doubao-seedance-2.5, all reference videos together count as 30 seconds.
FAQ
Model not available (503) or 404 error
Model not available (503) or 404 error
model name correct (e.g. doubao-seedance-2.0-fast) — otherwise you get a 503 with the code model_not_found; and is the address https://www.ruapi.ai/v1/videos (with /v1) — otherwise a 404.Stuck on queued / in_progress
Stuck on queued / in_progress
Downloaded file is empty / won't open
Downloaded file is empty / won't open
410 or 502), and the error text is saved to the file instead of the video. Download right after generation.Omni reference-to-video task failed
Omni reference-to-video task failed
input_contains_real_person / PrivacyInformation error: a real person in a photo or video
input_contains_real_person / PrivacyInformation error: a real person in a photo or video
input_contains_real_person (when the task is submitted) or InputImageSensitiveContentDetected.PrivacyInformation (in the error field of a finished task). The model checks photos of real people strictly (deepfake protection) and may reject them; on RuAPI, photos of ordinary people can usually be used, depending on the model and mode (see above). If you still get this error:- A photo of an ordinary person (not a public figure). Send the same request again with
"auto_create_assets": trueinmetadata(at the top level of the request in the ModelArk format). The photo then goes through a separate review for this one video. This may add 1–2 minutes, and passing is not guaranteed. It works only for images given as a public http(s) URL, not for videos. If the photo is rejected again with the flag set, it most likely shows a public figure — see the next question. - A real person in a reference video (
input_contains_real_personon submission,InputVideoSensitiveContentDetected.PrivacyInformationin a finished task). Switching todoubao-seedance-2.0ordoubao-seedance-2.5usually helps:-miniand-fastusually don’t accept such videos.auto_create_assetscovers photos only, not videos. If the video was generated on RuAPI within the last 23 hours, try reusing it by its task id with the same model — see “Reusing a generated video: reference_video_task_id” above. - No real people. Replace the image with an illustration, a character, an object or a landscape, or describe the scene in text only.
input_copyright_restricted / PolicyViolation error: public figures and characters
input_copyright_restricted / PolicyViolation error: public figures and characters
input_copyright_restricted (when the task is submitted) or InputImageSensitiveContentDetected.PolicyViolation (in the error field of a finished task). The model does not accept images of public figures (celebrities, influencers) or copyrighted characters (film, TV, games), or prompts that name such a character, and auto_create_assets does not help here. Use your own images or photos of ordinary people. A rejected task is not charged. If your project really needs a public figure and you have their authorization, contact support at support@ruapi.ai or on Telegram @RuAPI_Support. For all Seedance moderation codes, see Seedance: PolicyViolation and SensitiveContentDetected.400 error when calling Seedance via /v1/chat/completions
400 error when calling Seedance via /v1/chat/completions
/v1/chat/completions, /v1/responses, /v1/messages or /v1/images/generations. Such a request immediately gets 400 with a hint, and nothing is charged. Create a task with POST https://www.ruapi.ai/v1/videos (or POST https://www.ruapi.ai/v1/contents/generations/tasks in the ModelArk format). If a client like Cherry Studio shows this error while checking models, that’s expected: such clients test every model as a chat model.Which address do I poll?
Which address do I poll?
GET /v1/videos/{id}. It’s the OpenAI-compatible format, and metadata.url in the response is directly the download link.