AIaituber
Uploads

Upload a media file

Changed on

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:

  • background-video-upload: H.264 MP4, up to 500MB and 10 minutes. Direct upload only. Call POST /uploads/confirm-background-video after PUT.
  • 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.
  • rebuild-still: a Before or After picture for an AI Construction Timelapse (templateId: "rebuild"). Pass the returned URL as beforeImageUrl or afterImageUrl. A photo, a drawing, or a render all work. JPEG, PNG, or WebP, max 25MB. URL upload allowed.
  • 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.
  • visual-style-reference: a picture of a look you want to reuse. JPEG, PNG, or WebP, max 10MB. URL upload allowed. AITuber reads the picture and writes a reusable visual style from it.
  • 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.
  • document-source: a PDF to turn into a video. PDF only, max 25MB, up to 100 pages. Direct upload only.

Optional fileName: the name of the file you are uploading. We keep it for display, so a PDF shows its own name instead of an id.

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

post/uploads

Request

  • Base URL
    https://app.aituber.app/api/v1
  • Auth
    HTTP bearer

Request body

purpose'background-video-library-upload' | 'background-video-upload' | 'clip-reference-image' | 'clip-reference-video' | 'clip-reference-audio' | 'rebuild-still' | 'document-source' | 'element-image' | 'visual-style-reference' | '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' | 'application/pdf' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.openxmlformats-officedocument.presentationml.presentation' | 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' | 'text/plain' | 'text/markdown' | 'text/csv'

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

fileSizeBytesinteger

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

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.

fileNamestring

The name of the file, for display (document-source shows it instead of an id). Directory parts are dropped.

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.

Changes

  • b3e73971c023Revision changes
    • info

      added the new application/vnd.openxmlformats-officedocument.presentationml.presentation enum value to the request property

    • info

      added the new application/vnd.openxmlformats-officedocument.spreadsheetml.sheet enum value to the request property

    • info

      added the new application/vnd.openxmlformats-officedocument.wordprocessingml.document enum value to the request property

    • info

      added the new text/csv enum value to the request property

    • info

      added the new text/markdown enum value to the request property

    • info

      added the new text/plain enum value to the request property

  • 4b4b893e360fRevision changes
    • info

      api operation id uploads.create removed and replaced with createUpload