Skip to main content
POST
Upload a media source
Uploads a media source from a public URL, data URI, or raw base64 payload and returns its permanent Magica URL and detected media metadata.

Authorization

string
required
Bearer API key. Format: Bearer gx_your_api_key.

Request

Provide exactly one source:
  • url: a public HTTPS media URL or a base64 data URI. Remote URLs must be reachable without interactive authentication.
  • data_uri: a base64 data URI.
  • base64: raw base64 bytes; content_type is required with this form.
Optional fields include media_type, filename, and folder. folder defaults to mcp-uploads; setting it to media-library only changes the storage folder and does not create a media-library catalog record.

Examples

Response

string
Permanent URL for the uploaded media.
string
Detected media type: image, video, audio, or file.
string | null
Detected source filename when available.
object
Additional media metadata discovered during import.

Errors

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Provide exactly one of url, data_uri, or base64. URL sources may be public HTTPS media URLs or base64 data URIs; explicitly enabled non-production localhost fixtures may use HTTP. Raw base64 also requires content_type.

url
required

Public HTTPS media source or a base64 data URI. HTTP is accepted only for explicitly enabled localhost development fixtures.

Minimum string length: 1
data_uri
string

Base64 data URI source.

base64
string

Raw base64 source bytes.

media_type
enum<string>
Available options:
image,
video,
audio,
file
filename
string
content_type
string
folder
enum<string>
Available options:
mcp-uploads,
media-library

Response

The source was uploaded to permanent storage.

url
string<uri>
required
media_type
enum<string>
required
Available options:
image,
video,
audio,
file
filename
string | null
required
metadata
object
required