Upload source media

Capabilities that take source media (image to image, image to video, voice clone, reference audio to music, etc.) accept three reference forms — artifact is the most reliable:

Form	Syntax	When to use
Uploaded artifact	`{ "type": "artifact", "artifact_id": "artifact_..." }`	Recommended; reusable and immune to external links going stale
Public URL	`{ "type": "url", "url": "https://..." }`	Media already has a public address; the platform downloads and re-stores it
Data URI	`{ "type": "data_uri", "data": "data:image/png;base64,..." }`	Small files (≤256KB after encoding)

Upload

POST /v1/uploads

multipart/form-data, single file ≤100MB:

curl "$BEATRA_BASE_URL/uploads" \
  -H "Authorization: Bearer $BEATRA_API_KEY" \
  -F "[email protected]" \
  -F "purpose=voice_clone_source"

purpose options: media_input (default) · reference_audio · voice_clone_source.

Accepted MIME types: image/png, image/jpeg, image/webp, image/gif, image/bmp, image/tiff, audio/mpeg, audio/mp3, audio/wav, audio/x-wav, audio/mp4, audio/x-m4a, audio/aac, audio/flac, audio/ogg, audio/webm, video/mp4, video/webm, and video/quicktime. If the multipart client sends application/octet-stream (as the curl example may), Beatra detects the concrete type from the file signature. A declared type that does not match the bytes, or an unsupported type, returns 422 invalid_media before storage.

Returns 201:

{
  "object": "upload",
  "artifact_id": "artifact_01JX...",
  "cdn_url": "https://cdn.beatra.ai/.../sample.mp3",
  "mime_type": "audio/mpeg",
  "media_type": "audio",
  "size_bytes": 2097152,
  "duration_ms": 131000,
  "checksum_sha256": "9f86d08..."
}

Rules

Instant dedupe: re-uploading identical content (by checksum_sha256) returns 201 with the existing artifact_id; storage is not counted twice;
Over the limit: >100MB returns 413 media_too_large; chunked upload for larger files is not yet available;
Type validation: uploads accept image, audio, and video only; when media_type is omitted it is inferred from the verified MIME type; a mismatch or invalid signature returns 422 before storage;
Artifacts produced by generation tasks (the artifact_id in output) can likewise be used as input to subsequent tasks.

Full parameters and constraints → API definition

Upload source media

Upload

Rules

On this page