Media Upload

Upload images, videos, and audio files to use in generation and editing workflows.

POST/api/v1/media/upload

Content-Type

Requests must use multipart/form-data. For a single file, use the field name file. For multiple files, use any field name per file.

Supported Formats

Category	MIME Types
Images	jpeg, png, gif, webp, svg+xml
Videos	mp4, webm, quicktime, x-msvideo
Audio	mpeg, mp3, wav, ogg, webm, aac, m4a

Single-File Response

{
  "mediaId": "uuid",
  "url": "https://...",
  "mimeType": "video/mp4",
  "uploads": {
    "file": { "mediaId": "uuid", "url": "...", "mimeType": "..." }
  }
}

Multi-File Response

When uploading multiple files, the response includes an uploads map keyed by field name, plus an errors map for any files that failed. Partial success is possible -- some files may upload successfully while others fail.

{
  "uploads": {
    "background": { "mediaId": "...", "url": "...", "mimeType": "..." },
    "overlay": { "mediaId": "...", "url": "...", "mimeType": "..." }
  },
  "errors": {
    "badfile": "Unsupported MIME type"
  }
}

Example

cURL -- single file upload

curl https://api.wondercat.ai/api/v1/media/upload \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -F "file=@/path/to/video.mp4"

cURL -- multi-file upload

curl https://api.wondercat.ai/api/v1/media/upload \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -F "background=@/path/to/bg.png" \
  -F "overlay=@/path/to/overlay.png"

Request Fields

Parameter	Type	Required	Description
file	binary	Yes	The file to upload. Use field name "file" for single uploads, or any name for multi-file uploads.