cURL
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 { readFile } from 'node:fs/promises';
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
// Creates the ticket and uploads the file to it.
const ticket = await mage.uploads.upload(await readFile('clip.mp4'), {
contentType: 'video/mp4',
});
console.log(ticket.url); // send this in any media fieldfrom mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
# Creates the ticket and uploads the file to it.
ticket = mage.uploads.upload("clip.mp4") # a path, bytes, or a binary file
print(ticket["url"]) # send this in any media fieldconst 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",
"x-goog-if-generation-match": "0"
},
"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, audio/mpeg, audio/mp3, audio/wav, audio/wave, audio/x-wav."
}
}{
"error": {
"code": "unauthorized",
"message": "The API key is invalid or has been revoked."
}
}{
"error": {
"code": "payment_required",
"message": "The Mage API and MCP server need a successful payment on this account first: buy any Gem pack or start a plan at https://www.mage.space/gems, then retry. Signup bonus Gems work in the Mage app only."
}
}{
"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, video, or audio file of up to 100 MB to Mage storage.
POST
/
v1
/
uploads
cURL
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 { readFile } from 'node:fs/promises';
import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
// Creates the ticket and uploads the file to it.
const ticket = await mage.uploads.upload(await readFile('clip.mp4'), {
contentType: 'video/mp4',
});
console.log(ticket.url); // send this in any media fieldfrom mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
# Creates the ticket and uploads the file to it.
ticket = mage.uploads.upload("clip.mp4") # a path, bytes, or a binary file
print(ticket["url"]) # send this in any media fieldconst 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",
"x-goog-if-generation-match": "0"
},
"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, audio/mpeg, audio/mp3, audio/wav, audio/wave, audio/x-wav."
}
}{
"error": {
"code": "unauthorized",
"message": "The API key is invalid or has been revoked."
}
}{
"error": {
"code": "payment_required",
"message": "The Mage API and MCP server need a successful payment on this account first: buy any Gem pack or start a plan at https://www.mage.space/gems, then retry. Signup bonus Gems work in the Mage app only."
}
}{
"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, or as the voice or audio of a character or audio reference you create. 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
Create a key in API → API Keys: select Create API key, name it in the popup, then select Create key. Copy the one-time key and send it as Authorization: Bearer mage_sk_…. Keys are for server-side code only.
Body
application/json
The media type of the file you will upload: an image or video for a generate request, or an audio clip for a character voice or an audio reference.
Available options:
image/jpeg, image/png, video/mp4, video/quicktime, video/webm, audio/mpeg, audio/mp3, audio/wav, audio/wave, audio/x-wav Response
The upload ticket.
Last modified on September 23, 2026

