Sign in
latestOpenAPI 3.1.12026-08-22330162.7 KB

35448566f143

Uploads

Upload a media file

Gets a media file into your AITuber library and returns an assetId you can pass to other endpoints. Every upload has a purpose that says what the file is for; the purpose decides the validation rules and where the asset can be used.

Two ways to upload:

1. From a URL (easiest, works from AI agents): pass sourceUrl and we download the file for you. Only available for small image purposes (not video).

2. Direct upload (for local files): pass contentType and fileSizeBytes and you get back an uploadUrl. PUT your file bytes to that URL within 1 hour (set the same Content-Type header), then use the assetId.

Supported purposes:

  • clip-reference-image, clip-reference-video, clip-reference-audio: input files for standalone clip generation. Images allow JPEG, PNG, or WebP up to 25MB. Videos allow MP4, MOV, or WebM up to 200MB. Audio allows MP3, WAV, M4A, AAC, OGG, or WebM up to 50MB. Direct upload only.
  • element-image: a reference photo for an element (a person, product, or place). JPEG, PNG, or WebP, max 25MB. URL upload allowed. Use the assetId in POST /elements.
  • ugc-demo: a product demo video for a UGC hook video. MP4, MOV, or WebM, max 200MB, up to 3 minutes. Direct upload only. Use the assetId as demoVideoAssetId in POST /ugc/videos.
  • music: an audio track to score a music video. MP3, WAV, M4A, or AAC, max 50MB. Direct upload only, and durationSeconds is REQUIRED. Use the assetId as musicAssetId in POST /music-videos.
  • voice-sample: an audio sample for voice cloning. MP3, WAV, M4A, AAC, OGG, or WebM, max 11MB. Direct upload only. Pass the assetId to the voice clone endpoint.

Uploads that are never attached to anything are deleted after 7 days.

post/uploads

Request body

purpose'clip-reference-image' | 'clip-reference-video' | 'clip-reference-audio' | 'element-image' | 'ugc-demo' | 'music' | 'voice-sample' | 'agent-attachment' required

What this file is for. Only listed purposes are accepted; each unlocks specific endpoints (see the endpoint description).

sourceUrlstring

A public URL to download the file from (image purposes only). Use this OR contentType+fileSizeBytes, not both.

contentType'image/jpeg' | 'image/png' | 'image/webp' | 'video/mp4' | 'video/quicktime' | 'video/webm' | 'audio/mpeg' | 'audio/wav' | 'audio/mp4' | 'audio/x-m4a' | 'audio/aac' | 'audio/mp3' | 'audio/wave' | 'audio/x-wav' | 'audio/ogg' | 'audio/webm'

The file type for a direct upload. Returns an uploadUrl to PUT the bytes to. Must match the purpose (image, video, or audio).

fileSizeBytesinteger

The file size in bytes for a direct upload. Max depends on the purpose (25MB images, 200MB video, 50MB audio).

durationSecondsnumber

For video (ugc-demo, 1-180) and audio (music, 1-600) uploads: REQUIRED. The clip or track length in seconds. Used to time the segment.

videoWidthinteger

For video uploads (ugc-demo): the pixel width. Recommended so the demo is framed correctly.

videoHeightinteger

For video uploads (ugc-demo): the pixel height. Recommended so the demo is framed correctly.

Response

OK

assetIdstring uuid required

Pass this to the endpoint that consumes this purpose.

urlstring required

The public URL the file will be served from.

uploadUrlstring nullable required

Only for direct uploads: PUT your file bytes here within 1 hour, with the same Content-Type you declared. null for URL uploads (already stored).

status'ready' | 'awaiting_file' required

ready: the file is stored and the assetId is usable now. awaiting_file: PUT your file to uploadUrl first.