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.
POST
https://serastudio.app/api/v1/uploadsUsage notes
- The key needs the create permission.
- Two steps: this call returns
upload_url; thenPUTthe file bytes to it with exactlyupload_headersand noAuthorizationheader. The address is valid untilupload_url_expires_atand 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 andimg_for photos. Pass them to a generation assource.upload_idandimages[].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.mp4Input schema
content_typestringrequiredThe 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"
}idstringThe upload id (vid_... or img_...).
kindstringvideo or image, from content_type.
upload_urlstringWhere to PUT the bytes. One file, valid until upload_url_expires_at.
upload_methodstringAlways PUT.
upload_headersobjectSend exactly these headers with the PUT.
max_bytesintegerThe largest file the address accepts.
Errors
| Status | Code | When it happens | Retry |
|---|---|---|---|
400 | invalid_json | The body is not a JSON object. | No |
401 | api_key_missing | No Bearer key was sent in the Authorization header. | No |
401 | api_key_invalid | The key is malformed or unknown. | No |
401 | api_key_revoked | The key was deleted in the console. | No |
401 | api_key_disabled | The key is disabled in the console. | No |
401 | api_key_expired | The key is past its expiration date. | No |
403 | insufficient_scope | The key lacks the create permission. Keys created in the console have it. | No |
403 | workspace_forbidden | The account that owns the workspace is suspended or scheduled for deletion. | No |
422 | invalid_parameter | content_type is missing or not one of the accepted types. | No |
503 | temporarily_unavailable | The request could not be completed just now. | Yes |
500 | internal_error | Something failed on our side. The request_id identifies the request. | Yes |
503 | api_unavailable | The API is turned off. | No |