Endpoints
Videos
Async, OpenAI-Sora-compatible text-to-video and image-to-video generation.
Generate video from a prompt, or animate a reference image. Video is asynchronous: submit a job, poll until it finishes, then download the MP4.
https://api.roteo.ai/v1/videoshttps://api.roteo.ai/v1/videos/{id}https://api.roteo.ai/v1/videos/{id}/contenthttps://api.roteo.ai/v1/videos/quoteLifecycle
- Quote (optional, free): send the same body to
/v1/videos/quotefor the exact price. Nothing is held or started. - Submit to
/v1/videos. It returns immediately with anidandstatus: "in_progress". - Poll
GET /v1/videos/{id}every few seconds.statusmovesin_progress→completed(orfailed). Rendering takes about 1 to 5 minutes. - Download from
GET /v1/videos/{id}/contentoncestatusiscompleted.
You are charged per delivered clip, by duration and size, plus the length of any reference video; a failed job is free.
Price before you run
POST /v1/videos/quote takes exactly the body of POST /v1/videos and answers with the price, for free:
list_price is what the submit holds from your balance; price is what you pay after your lock discount. With a reference video on Seedance the quote measures its length first, adds input_video_seconds, and gives seconds as billed (an edit runs as long as its input); on wan-3.0 reference videos are free, so the quote is the clip's own price. On Seedance a reference video's length is billed as input on top of the clip, at a lower rate per second: a 3-second reference barely changes the price, a 10-second one nearly doubles it. The full table is in the Seedance guide, under What a reference video adds. GET /v1/models?type=video lists every model's sizes, reference limits and the list price of every size and duration.
Submit
modelstringrequiredAny video model, e.g. wan-3.0. See Models: sizes, durations and reference limits all vary per model.
promptstringrequiredRequired in every mode. When you supply a starting frame, describe the motion rather than the scene. Up to 8,000 characters.
sizestringA resolution and an aspect ratio, as width x height: see Sizes. Seedance takes every size, Wan every size but 21:9; with a single starting frame Wan's clip takes its shape from the frame, and the size only picks the resolution. Gemini Omni: 1280x720 (landscape) or 720x1280 (portrait).
aspect_ratiostringInstead of size: 16:9, 9:16, 4:3, 3:4, 1:1 or 21:9, with resolution. "aspect_ratio": "1:1", "resolution": "720p" is 960x960. Either one alone keeps the other from the model's first size.
resolutionstring480p, 720p or 1080p, with aspect_ratio (above).
secondsintegerSeedance 2.5 and Wan: 5, 8, 12, 16, 20, 24 or 30. Seedance 2.0: 5, 8, 10, 12 or 15. Gemini Omni: 4, 6, 8 or 10. A value one model accepts another rejects with 400. Omit size or seconds to take the model's first listed value.
input_referencefile | string | string[]Reference image: a file (multipart), an https:// link, an upload id, or a data:image/... URI. PNG, JPEG, or WebP. Files sent in the request: up to 3.5MB each and 4MB in total; links and uploads: up to 20MB each. In JSON, one or an array (reference_images is the same field under the name agents expect); in multipart, a file or a text part.
Optional on every video model.
Repeat the part to send several (-F input_reference=@a.jpg -F input_reference=@b.jpg). One reference is a starting frame; two or more are subject and style references, up to 30 on seedance-2.5, 9 on seedance-2.0, 10 on wan-3.0 and 10 on gemini-omni-1.1-flash. Sending more than a model takes returns 400 rather than quietly dropping the extras.
A single frame is cover-cropped to the video size for you on Seedance and Gemini Omni. Wan takes its aspect ratio from the frame itself, so nothing is cropped, and multi-image references are never cropped.
last_referencefile | stringA file, link, upload id or data:image URI, like input_reference. Optional LAST frame for first+last-frame animation (seedance-2.5, seedance-2.0, wan-3.0 and gemini-omni-1.1-flash). Send it alongside exactly one input_reference (the first frame) and the model animates the transition between them: a controlled morph, or continuation from a previous clip. Sending it with no input_reference, with several, or on another model returns 400.
reference_videosstring[]seedance-2.5, seedance-2.0 and wan-3.0. Videos the model works from: each an https:// link to an MP4 or MOV, the id of a video you made with us in the last 46 hours, or an upload id for a local file (up to 200MB, 100MB on wan-3.0). Up to 10 videos and 30 seconds in total on seedance-2.5, 3 and 15 seconds on seedance-2.0, 5 and 15 seconds on wan-3.0 (1 to 15 seconds each). On wan-3.0 they are references only and free: the price is the same with or without them. JSON body: an array. Multipart: repeat reference_video. Any video puts the request in reference mode, and input_reference images then act as extra subject references. Cite each video in the prompt as @video1, @video2 and say what to take from it (its dance, its camera move): a video the prompt never names may be ignored.
reference_audiosstring[]Seedance only. A voice or music for the clip to follow: each an https:// link to a WAV or MP3, or an upload id. seedance-2.5: up to 10 clips of 2 to 30 seconds, 30 seconds in total, and audio alone is enough. seedance-2.0: up to 3 clips of 2 to 15 seconds, 15 seconds in total, and it needs an image or a video too. Free: the price is the same with or without. Needs audio on, and can't be combined with last_reference. JSON body: an array. Multipart: repeat reference_audio. Cite each in the prompt as @audio1, @audio2 and say what it is for, e.g. "@image1 sings along to @audio1".
taskstringWhat to do with a reference video. reference: a new clip that borrows its subject, style or motion. edit: the same clip changed as the prompt says; it keeps the input's length and shape, and seconds is ignored. extend: the clip continued from where it ends, for seconds. edit and extend take exactly one video and are Seedance only: wan-3.0 takes reference and returns 400 for the others.
consentbooleanRequired whenever the request carries reference media (input_reference, last_reference, reference_videos or reference_audios). true confirms you have the right to use the media, that everyone shown consented, and that everyone shown is an adult. Without it the request returns 400 with error.code consent_required. Multipart: consent=true.
audiobooleanfalse renders the clip with no soundtrack, on seedance-2.5, seedance-2.0 and wan-3.0 (the price is the same either way). Gemini Omni always has sound and returns 400 for false. With audio on, an edit keeps the source clip's soundtrack (the prompt cannot change it); with false the clip has no audio track. Turn it off when a job fails with audio_copyright.
draftbooleanseedance-2.5 only. true renders a quick 480p preview in the shape you ask for, at the 480p price, that you can finish in 1080p within about 2 days. Our video provider holds a draft's prompt and inputs so it can be finished, and is instructed to delete them after 48 hours: see Drafts. Not with task edit or extend.
Text-to-video
Image-to-video
Send multipart/form-data with an input_reference image plus the same scalar fields. Or send JSON with input_reference set to an https:// link or an upload id, which has no request size limit.
Reference-to-video
seedance-2.5, seedance-2.0, wan-3.0 and gemini-omni-1.1-flash. Send two or more input_reference images (up to 30, 9, 10 and 10 respectively) and cite them in the prompt as @image1, @image2, and so on. They are treated as subject and style references rather than a starting frame, so none of them is cropped.
Video-to-video: reference, edit, extend
seedance-2.5, seedance-2.0 and wan-3.0 also take VIDEOS (Wan as references only). Pass a link, or the id of a video you made here (no re-upload), and say what to do with task. This is a JSON request, so the video never has to fit in the request body.
The id is the one POST /v1/videos returned when you made the video. It works for 46 hours, from any of your API keys. A clip made in the Station usually leaves our servers as soon as it is saved on your device, so its id is not a reference any more: upload the file instead (Uploads). While we still hold one, Copy ID in its viewer copies the id.
On Seedance a job with a reference video is priced on the clip you get AND the video's own length, which the request measures when you submit; an edit runs as long as its input. On wan-3.0 reference videos are free: the job costs what the clip alone costs.
Drafts
seedance-2.5 only. Add "draft": true to try a shot cheaply first: it renders at 480p in the shape you asked for, at the 480p price. If you like it, finish the same shot in 1080p: the same prompt, inputs, length, shape and sound, rendered again at full quality, not upscaled.
The finish is a new job with its own id, in 1080p and the draft's shape. It is priced by the quote and charged only if it is delivered. Send only the draft's id in finalize (and model, if you like): every other field returns 400, because the draft already fixed it. A job's JSON says "draft": true and gives finalize_until (Unix seconds, about 2 days after the draft was made). Until then a draft can be finished more than once; each finish is a new job and a new charge. A draft made in the Station can be finished here too: Copy ID in its viewer.
Privacy. A draft is the one request whose prompt and inputs our video provider holds after the job ends, so that it can be finished; the provider is instructed to delete them after 48 hours. Roteo itself stores none of it. Leave draft off for anything you do not want kept. See Privacy.
Upscale to 1080p
Sharpen a clip to 1080p in the same shape: the same frames, motion and sound (flux-video-upscale). It is a new job, polled and downloaded like any other, and charged only if it is delivered. Price it first with POST /v1/videos/quote and the same body, for free.
The clip can be:
- One of your videos:
{"upscale": "<video id>"}, any video you made with us in the last 46 hours. Nothing else goes in the body. - A video you uploaded (Uploads):
{"upscale": "upl_...", "consent": true}. It is measured from the file itself (its length, rounded up to the second, and its picture as it plays) and deleted when the job ends.consentconfirms you have the right to use it, that everyone shown consented, and that everyone shown is an adult.
Either way the clip is at most 20 seconds, with a short side from 360 to 720 pixels (480p and 720p); an upload is an MP4 or MOV. It is priced per second of the clip by the 1080p size it becomes, and every shape's rate is on GET /v1/models?type=video under flux-video-upscale.
Sizes
size picks a resolution and an aspect ratio. 1:1 suits a square feed post, 9:16 a story or a short, 21:9 a cinematic banner.
seedance-2.5andseedance-2.0sell every size. Price follows the pixel count, so at 1080p4:3and3:4cost about a quarter less than16:9and21:9about a third more. At 480p and 720p every ratio is within a few cents of16:9.wan-3.0sells every size but21:9, and every ratio of a resolution costs the same.gemini-omni-1.1-flashsells1280x720and720x1280only.
A size the model does not sell is refused with 400. The exact price of every size is in /v1/llms.txt, and Station shows it before every run.
When a job fails
A failed job is never charged. GET /v1/videos/{id} returns status: "failed" with error: { code, message }, and a request refused at submit returns the same code on its error. The code tells you what to change:
A finished video is delivered once its charge settles. Until then GET /v1/videos/{id} keeps answering in_progress (progress 99) with no url, and /content answers 409.
Choosing a reference image
Use a detailed photo or rich scene: the model animates from the reference, so it needs real structure to work with. A flat or near-blank image (a logo, icon or solid color) gives it nothing to animate and can stall or produce poor motion. Transparency is flattened to a solid background.
Wan takes the clip's aspect ratio from the frame, so send it already framed the way you want the video. Seedance and Gemini Omni cover-crop a single frame for you, and multi-image references are never cropped.