Skip to main content
POST
Create upload
A signed URL to PUT one file onto Mage storage, for inputs too large for a data URL. Request bodies are capped at 4.5 MB on the platform, so a data URL carries about 3 MB; an upload takes up to 100 MB. Create a ticket with the file’s content_type, PUT the bytes to upload_url with exactly the headers returned, then send url in any media field of a generate request. The upload URL is valid for 15 minutes (upload_url_expires_at); the file lives 30 days (url_expires_at), like every input and result. See Inputs and uploads for the full flow.

Authorizations

Authorization
string
header
required

An API key from Settings → API, sent as Authorization: Bearer mage_sk_…. Keys are for server-side code only.

Body

application/json
content_type
enum<string>
required

The media type of the file you will upload.

Available options:
image/jpeg,
image/png,
video/mp4,
video/quicktime,
video/webm

Response

The upload ticket.

upload_url
string<uri>
required

PUT the file here.

method
string
required
Allowed value: "PUT"
headers
object
required

Headers the PUT must carry exactly; storage checks them against the signature.

url
string<uri>
required

The URL the file has once the PUT succeeds. Send it in any media field.

content_type
string
required

The media type the PUT must declare.

max_bytes
integer
required

The largest body the upload accepts: 100 MB.

upload_url_expires_at
string<date-time>
required

When upload_url stops accepting the PUT.

url_expires_at
string<date-time>
required

When the uploaded file is deleted: 30 days after the ticket.

Last modified on September 17, 2026