Create upload
curl --request POST \
--url https://api.mage.space/v1/uploads \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"content_type": "video/mp4"
}
'import requests
url = "https://api.mage.space/v1/uploads"
payload = { "content_type": "video/mp4" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({content_type: 'video/mp4'})
};
fetch('https://api.mage.space/v1/uploads', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"upload_url": "https://storage.googleapis.com/mage/temp/30d/uploads/user/video/6f1c.mp4?X-Goog-Signature=…",
"method": "PUT",
"headers": {
"Content-Type": "video/mp4",
"x-goog-content-length-range": "0,104857600"
},
"url": "https://cdn3.mage.space/temp/30d/uploads/user/video/6f1c.mp4",
"content_type": "video/mp4",
"max_bytes": 104857600,
"upload_url_expires_at": "2026-09-17T15:07:48.000Z",
"url_expires_at": "2026-10-17T14:52:48.000Z"
}{
"error": {
"code": "invalid_request",
"message": "`content_type` must be one of: image/jpeg, image/png, video/mp4, video/quicktime, video/webm."
}
}{
"error": {
"code": "unauthorized",
"message": "The API key is invalid or has been revoked."
}
}{
"error": {
"code": "internal_error",
"message": "Something went wrong on our side. Retry, and contact support if it persists."
}
}Endpoints
Create upload
POST /v1/uploads returns a signed URL to upload one image or video input of up to 100 MB to Mage storage.
POST
/
v1
/
uploads
Create upload
curl --request POST \
--url https://api.mage.space/v1/uploads \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"content_type": "video/mp4"
}
'import requests
url = "https://api.mage.space/v1/uploads"
payload = { "content_type": "video/mp4" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({content_type: 'video/mp4'})
};
fetch('https://api.mage.space/v1/uploads', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"upload_url": "https://storage.googleapis.com/mage/temp/30d/uploads/user/video/6f1c.mp4?X-Goog-Signature=…",
"method": "PUT",
"headers": {
"Content-Type": "video/mp4",
"x-goog-content-length-range": "0,104857600"
},
"url": "https://cdn3.mage.space/temp/30d/uploads/user/video/6f1c.mp4",
"content_type": "video/mp4",
"max_bytes": 104857600,
"upload_url_expires_at": "2026-09-17T15:07:48.000Z",
"url_expires_at": "2026-10-17T14:52:48.000Z"
}{
"error": {
"code": "invalid_request",
"message": "`content_type` must be one of: image/jpeg, image/png, video/mp4, video/quicktime, video/webm."
}
}{
"error": {
"code": "unauthorized",
"message": "The API key is invalid or has been revoked."
}
}{
"error": {
"code": "internal_error",
"message": "Something went wrong on our side. Retry, and contact support if it persists."
}
}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
An API key from Settings → API, sent as Authorization: Bearer mage_sk_…. Keys are for server-side code only.
Body
application/json
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.
PUT the file here.
Allowed value:
"PUT"Headers the PUT must carry exactly; storage checks them against the signature.
Show child attributes
Show child attributes
The URL the file has once the PUT succeeds. Send it in any media field.
The media type the PUT must declare.
The largest body the upload accepts: 100 MB.
When upload_url stops accepting the PUT.
When the uploaded file is deleted: 30 days after the ticket.
Last modified on September 17, 2026

