Endpoints

Uploads

Send a local image, video or audio file to a video job, past the request size limit.

Upload a local file once, then use its id in any media field of POST /v1/videos. The file goes straight into private storage, so it can be far larger than a request body (up to 200MB for a video).

POSThttps://api.roteo.ai/v1/uploads
DELETEhttps://api.roteo.ai/v1/uploads/{id}

Three calls

  1. Ask for an upload link: POST /v1/uploads with the file's content_type.
  2. Upload the file with a plain PUT to the returned upload_url, sending the same content-type.
  3. Use the id in reference_videos, reference_audios, input_reference / reference_images or last_reference, or in upscale to sharpen it to 1080p (Upscale), with "consent": true.
# 1. an upload link for a video
curl https://api.roteo.ai/v1/uploads \
-H "x-api-key: $ROTEO_API_KEY" \
-H "content-type: application/json" \
-d '{"content_type": "video/mp4"}'
# -> {"id": "upl_...", "upload_url": "https://...", "method": "PUT", ...}

# 2. the file itself
curl -X PUT -T dance.mp4 -H "content-type: video/mp4" "<upload_url>"

# 3. use it
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": "Same dance, on a rooftop at night.",
  "reference_videos": ["upl_..."],
  "task": "edit",
  "consent": true
}'
content_typestringrequired

video/mp4 or video/quicktime (MOV) for a video; image/png, image/jpeg or image/webp for an image; audio/mpeg (MP3) or audio/wav for audio.

The response (201):

{
  "id": "upl_7f3a9c2e41d84b6f0a1b2c3d4e5f6a7bv",
  "object": "upload",
  "kind": "video",
  "content_type": "video/mp4",
  "upload_url": "https://...",
  "method": "PUT",
  "headers": { "content-type": "video/mp4" },
  "max_bytes": 209715200,
  "expires_at": 1760000900
}
json · 11 lines

PUT the file to upload_url with the headers shown. The link works once, until expires_at.

Rules

SizeVideos up to 200MB, images up to 20MB, audio up to 15MB
Upload linkValid for 15 minutes, one file
Use it within30 minutes of creating it
DeletedWhen the job that used it ends, or after about an hour if no job did
One jobThe job that uses an upload deletes it. To reuse a result, pass the finished video's id instead
Who can use itOnly your account. Another account's id is not found
CheckedThe file's own bytes must be the kind it was uploaded as

Delete an upload

DELETE /v1/uploads/{id} removes one of your uploads right away, without waiting for a job or the hourly cleanup. It returns { "id": "...", "object": "upload", "deleted": true }, or 404 when there is nothing of yours under that id.

Errors

error.codeMeaningFix
upload_not_foundNo upload of yours under that id: never uploaded, already used by a finished job, or older than 30 minutesUpload the file again
invalid_mediaThe upload is the wrong kind for the field (an image in reference_videos), or its bytes are not what it was uploaded asUpload the right file to the right field
invalid_requestcontent_type is not one of the seven aboveUse a listed type
Uploads | Roteo