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.

POSThttps://api.roteo.ai/v1/videos
GEThttps://api.roteo.ai/v1/videos/{id}
GEThttps://api.roteo.ai/v1/videos/{id}/content
POSThttps://api.roteo.ai/v1/videos/quote

Lifecycle

  1. Quote (optional, free): send the same body to /v1/videos/quote for the exact price. Nothing is held or started.
  2. Submit to /v1/videos. It returns immediately with an id and status: "in_progress".
  3. Poll GET /v1/videos/{id} every few seconds. status moves in_progress → completed (or failed). Rendering takes about 1 to 5 minutes.
  4. Download from GET /v1/videos/{id}/content once status is completed.

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:

{
  "object": "video.quote",
  "model": "seedance-2.5",
  "size": "960x960",
  "seconds": 5,
  "list_price": "1.683245",
  "price": "1.683245",
  "discount_bps": 0,
  "currency": "USD"
}
json · 10 lines

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

modelstringrequired

Any video model, e.g. wan-3.0. See Models: sizes, durations and reference limits all vary per model.

promptstringrequired

Required in every mode. When you supply a starting frame, describe the motion rather than the scene. Up to 8,000 characters.

sizestring

A 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_ratiostring

Instead 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.

resolutionstring

480p, 720p or 1080p, with aspect_ratio (above).

secondsinteger

Seedance 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 | string

A 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".

taskstring

What 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.

consentboolean

Required 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.

audioboolean

false 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.

draftboolean

seedance-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

curl https://api.roteo.ai/v1/videos \
-H "x-api-key: $ROTEO_API_KEY" \
-H "content-type: application/json" \
-d '{
  "model": "wan-3.0",
  "prompt": "a calm ocean wave rolling onto a beach at sunset, cinematic",
  "size": "1280x720",
  "seconds": 8
}'
bash · 9 lines

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.

curl https://api.roteo.ai/v1/videos \
-H "x-api-key: $ROTEO_API_KEY" \
-F model=wan-3.0 \
-F "prompt=animate this scene, gentle camera push-in" \
-F size=1280x720 \
-F seconds=8 \
-F input_reference=@photo.jpg \
-F consent=true
bash · 8 lines

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.

curl https://api.roteo.ai/v1/videos \
-H "x-api-key: $ROTEO_API_KEY" \
-F model=seedance-2.5 \
-F "prompt=@image1 walks through the alley in @image2's lighting, slow dolly" \
-F size=1280x720 \
-F seconds=12 \
-F input_reference=@character.jpg \
-F input_reference=@style.jpg \
-F consent=true
bash · 9 lines

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.

curl https://api.roteo.ai/v1/videos \
-H "x-api-key: $ROTEO_API_KEY" \
-H "content-type: application/json" \
-d '{
  "model": "seedance-2.0",
  "prompt": "Continue the clip: she turns back to the camera and waves.",
  "size": "720x1280",
  "seconds": 5,
  "reference_videos": ["<id of a video you made, or an https link>"],
  "task": "extend",
  "consent": true
}'
bash · 12 lines

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.

curl https://api.roteo.ai/v1/videos \
-H "x-api-key: $ROTEO_API_KEY" \
-H "content-type: application/json" \
-d '{
  "model": "seedance-2.5",
  "prompt": "a lighthouse in a storm, waves crashing, slow push-in",
  "aspect_ratio": "9:16",
  "seconds": 5,
  "draft": true
}'
# {"id":"<draft_id>","status":"in_progress","size":"480x854","draft":true,"finalize_until":1761300000,...}
bash · 11 lines

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.

error.codeStatusMeaning
draft_not_found404Not one of your videos.
not_a_draft400The video was not made with "draft": true.
draft_not_ready409The draft is still rendering. Finish it once it is completed.
draft_failed400The draft failed, so there is nothing to finish.
draft_expired410Past finalize_until. Make a new draft.

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. consent confirms 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.

# price it (free)
curl https://api.roteo.ai/v1/videos/quote \
-H "x-api-key: $ROTEO_API_KEY" \
-H "content-type: application/json" \
-d '{"upscale": "<video id>"}'

# run it: a new job, polled and downloaded like any other
curl https://api.roteo.ai/v1/videos \
-H "x-api-key: $ROTEO_API_KEY" \
-H "content-type: application/json" \
-d '{"upscale": "<video id>"}'
bash · 11 lines
error.codeStatusMeaning
video_not_found404Not one of your videos.
video_not_ready409The video is still rendering. Upscale it once it is completed.
video_expired410The video's file is gone (videos are kept about 2 days). Upload a copy instead.
upload_not_found400Not one of your uploads, or older than 30 minutes. Upload it again.
consent_required400An upload sent without "consent": true.
video_too_long400Over 20 seconds. Trim it first.
already_1080p400Already 1080p, or close enough that upscaling adds nothing.
too_small400Under 360p.
video_unreadable400The upload is not an MP4 or MOV we can read.

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.

16:99:164:33:41:121:9
480p854x480480x854752x560560x752640x640992x432
720p1280x720720x12801112x834834x1112960x9601470x630
1080p1920x10801080x19201440x10801080x14401440x14402520x1080
  • seedance-2.5 and seedance-2.0 sell every size. Price follows the pixel count, so at 1080p 4:3 and 3:4 cost about a quarter less than 16:9 and 21:9 about a third more. At 480p and 720p every ratio is within a few cents of 16:9.
  • wan-3.0 sells every size but 21:9, and every ratio of a resolution costs the same.
  • gemini-omni-1.1-flash sells 1280x720 and 720x1280 only.

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:

codeWhat happenedWhat to do
consent_requiredThe request has reference mediaAdd consent: true
content_policyThe prompt was declined by our content policyChange the prompt
audio_copyrightThe soundtrack matched copyrighted music (an edit keeps the source clip's sound)Send audio: false, or use a reference and prompt without copyrighted music
person_inputA reference shows a recognisable real personUse a different reference
nsfw_inputA reference was refused by the safety filterUse a different reference
nsfw_outputThe finished video was refused by the safety filterChange the prompt
content_blockedRefused by the safety filterChange the prompt or references
invalid_mediaA reference could not be usedCheck its format, length and size
payment_failedThe video finished, but its charge could not be collected, so the clip is heldAdd funds to your wallet, then contact support to release it
timeout, delivery_failed, failedSomething went wrong on our sideSend the same request again

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.

Videos | Roteo