UploadsCreate upload

Uploads

Create upload API

Get a one-time address to upload a source video or a reference photo, and the id to use in a generation.

POSThttps://serastudio.app/api/v1/uploads

Usage notes

  • The key needs the create permission.
  • Two steps: this call returns upload_url; then PUT the file bytes to it with exactly upload_headers and no Authorization header. The address is valid until upload_url_expires_at and accepts one file.
  • Videos: video/mp4 or video/quicktime. A QuickTime file is uploaded with content-type: video/mp4 (the returned header says so). Photos: image/jpeg or image/png. Up to 50 MB per file.
  • Upload ids start with vid_ for videos and img_ for photos. Pass them to a generation as source.upload_id and images[].upload_id.
  • An upload stays until you delete it, so you can reuse it in several generations.

Quick start

curl https://serastudio.app/api/v1/uploads \
  -H "Authorization: Bearer $SERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content_type": "video/mp4"}'

# then put the bytes to upload_url with the returned headers (no Authorization header)
curl -X PUT "<upload_url>" -H "content-type: video/mp4" -H "x-upsert: false" --data-binary @source.mp4

Input schema

content_typestringrequired

The file's media type: video/mp4, video/quicktime, image/jpeg, image/png.

Response

A new upload returns 201:

{
  "id": "vid_3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21",
  "object": "upload",
  "kind": "video",
  "content_type": "video/mp4",
  "upload_url": "https://rvzzbovxmjgldcnlbwyx.supabase.co/storage/v1/object/upload/sign/episodes/7d9e2f10-4b3a-4c5d-8e6f-0a1b2c3d4e5f/episodes/refs/3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21.mp4?token=<signed>",
  "upload_method": "PUT",
  "upload_headers": {
    "content-type": "video/mp4",
    "x-upsert": "false"
  },
  "upload_url_expires_at": "2026-11-09T07:08:00.000Z",
  "max_bytes": 52428800,
  "created_at": "2026-11-09T05:08:00.000Z"
}
idstring

The upload id (vid_... or img_...).

kindstring

video or image, from content_type.

upload_urlstring

Where to PUT the bytes. One file, valid until upload_url_expires_at.

upload_methodstring

Always PUT.

upload_headersobject

Send exactly these headers with the PUT.

max_bytesinteger

The largest file the address accepts.

Errors

StatusCodeWhen it happensRetry
400invalid_jsonThe body is not a JSON object.No
401api_key_missingNo Bearer key was sent in the Authorization header.No
401api_key_invalidThe key is malformed or unknown.No
401api_key_revokedThe key was deleted in the console.No
401api_key_disabledThe key is disabled in the console.No
401api_key_expiredThe key is past its expiration date.No
403insufficient_scopeThe key lacks the create permission. Keys created in the console have it.No
403workspace_forbiddenThe account that owns the workspace is suspended or scheduled for deletion.No
422invalid_parametercontent_type is missing or not one of the accepted types.No
503temporarily_unavailableThe request could not be completed just now.Yes
500internal_errorSomething failed on our side. The request_id identifies the request.Yes
503api_unavailableThe API is turned off.No