Upload Media

POST/v1/upload

Upload an image, audio, or video file and receive a stored URL for a supported model input.

Multipart form

binaryfilerequired

Image up to 20 MB, audio up to 50 MB, or video up to 500 MB. Supported formats are listed below.

Optional<image | audio | video>type

Optional category hint. MIME detection from the file still controls validation.

Supported MIME types

Optional<string>Image

image/jpeg, image/png, image/webp, image/gif — maximum 20 MB.

Optional<string>Audio

audio/mpeg, audio/mp4, audio/wav, audio/x-wav, audio/ogg, audio/aac, audio/flac — maximum 50 MB.

Optional<string>Video

video/mp4, video/quicktime, video/webm — maximum 500 MB.

Response

stringurlrequired

Stored media URL to pass to a supported model input.

string · integerfilename · sizerequired

Original multipart filename and file size in bytes.

stringtype · content_typerequired

Detected MIME type used when storing the file.

Optional<number>duration_seconds

Audio and video only: media duration in seconds, when it can be read from the file.

MIME detection

The server detects the file type from its bytes and filename. The optional type field does not force a MIME type.

curl -X POST https://api.sandbase.ai/v1/upload \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -F "file=@reference.mp4" \
  -F "type=video"

Response200 OK

{
  "url": "https://media.sandbase.ai/uploads/2026/08/550e8400-e29b-41d4-a716-446655440000.mp4",
  "filename": "reference.mp4",
  "size": 1048576,
  "type": "video/mp4",
  "content_type": "video/mp4",
  "duration_seconds": 5.04
}