curl --request POST \
--url https://api.mage.space/v1/{architecture}/generate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Editorial portrait in soft daylight, 35mm film look"
}
'import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const request = await mage.generate('mango', {
prompt: 'Editorial portrait in soft daylight, 35mm film look',
aspect_ratio: '4:5',
});
console.log(request.request_id, request.status);from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
request = mage.generate("mango", {
"prompt": "Editorial portrait in soft daylight, 35mm film look",
"aspect_ratio": "4:5",
})
print(request["request_id"], request["status"])const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({prompt: 'Editorial portrait in soft daylight, 35mm film look'})
};
fetch('https://api.mage.space/v1/{architecture}/generate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
"status": "in_progress",
"architecture": "flux2",
"model_id": "flux2-dev",
"created_at": "2026-09-17T14:52:48.000Z",
"updated_at": "2026-09-17T14:52:49.000Z",
"billing": {
"mode": "gems",
"gems_charged": 40
},
"result": null,
"error": null,
"status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
"cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
}{
"error": {
"code": "invalid_config",
"message": "`resolution` must be one of: 768P, 2K."
}
}{
"error": {
"code": "unauthorized",
"message": "The API key is invalid or has been revoked."
}
}{
"error": {
"code": "insufficient_gems",
"message": "This generation costs 40 gems and the account balance is too low.",
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
"gems_required": 40
}
}{
"error": {
"code": "content_blocked",
"message": "The request was blocked by Mage's content policy.",
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff"
}
}{
"error": {
"code": "architecture_not_found",
"message": "Unknown architecture `fluxx`. List architectures at GET /v1/architectures."
}
}{
"error": {
"code": "architecture_retired",
"message": "This architecture has been retired.",
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff"
}
}{
"error": {
"code": "too_many_requests",
"message": "At most 20 generations may be in flight at once for this account; 20 are running now."
}
}{
"error": {
"code": "content_blocked",
"message": "The request was blocked by an external content restriction.",
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff"
}
}{
"error": {
"code": "internal_error",
"message": "Something went wrong on our side. Retry, and contact support if it persists."
}
}Generate
Submit an image, video, or audio generation with any Mage model: the partial config body, the Idempotency-Key header, the 202 response, and every error the generate endpoint can return.
curl --request POST \
--url https://api.mage.space/v1/{architecture}/generate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "Editorial portrait in soft daylight, 35mm film look"
}
'import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const request = await mage.generate('mango', {
prompt: 'Editorial portrait in soft daylight, 35mm film look',
aspect_ratio: '4:5',
});
console.log(request.request_id, request.status);from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
request = mage.generate("mango", {
"prompt": "Editorial portrait in soft daylight, 35mm film look",
"aspect_ratio": "4:5",
})
print(request["request_id"], request["status"])const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({prompt: 'Editorial portrait in soft daylight, 35mm film look'})
};
fetch('https://api.mage.space/v1/{architecture}/generate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
"status": "in_progress",
"architecture": "flux2",
"model_id": "flux2-dev",
"created_at": "2026-09-17T14:52:48.000Z",
"updated_at": "2026-09-17T14:52:49.000Z",
"billing": {
"mode": "gems",
"gems_charged": 40
},
"result": null,
"error": null,
"status_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
"cancel_url": "https://api.mage.space/v1/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel"
}{
"error": {
"code": "invalid_config",
"message": "`resolution` must be one of: 768P, 2K."
}
}{
"error": {
"code": "unauthorized",
"message": "The API key is invalid or has been revoked."
}
}{
"error": {
"code": "insufficient_gems",
"message": "This generation costs 40 gems and the account balance is too low.",
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
"gems_required": 40
}
}{
"error": {
"code": "content_blocked",
"message": "The request was blocked by Mage's content policy.",
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff"
}
}{
"error": {
"code": "architecture_not_found",
"message": "Unknown architecture `fluxx`. List architectures at GET /v1/architectures."
}
}{
"error": {
"code": "architecture_retired",
"message": "This architecture has been retired.",
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff"
}
}{
"error": {
"code": "too_many_requests",
"message": "At most 20 generations may be in flight at once for this account; 20 are running now."
}
}{
"error": {
"code": "content_blocked",
"message": "The request was blocked by an external content restriction.",
"request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff"
}
}{
"error": {
"code": "internal_error",
"message": "Something went wrong on our side. Retry, and contact support if it persists."
}
}GET /v1/architectures as input_schema.
The response is the request’s current state, with status_url to poll and cancel_url to stop it. Gems are charged when the request is accepted; a request that fails is refunded. See Requests and lifecycle for what happens next.
This page documents the endpoint in general. For a specific model, open its page under Models: the playground there is filled in with that model’s fields.
Common fields
The same field names mean the same thing on every model.aspect_ratio is a W:H ratio such as 16:9; first_image and last_image are the frames a video starts and ends on; image and additional_images are reference images; video or videos is the source video; resolution and duration are tokens from the model’s lists. A model’s page lists which of these it takes and the values it accepts. A setting a model does not have is not an error: it passes through like any unknown field, and the model ignores it.
A config copied from the app is accepted as it is.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.
Headers
A key of your choosing, 1 to 255 characters, scoped to your API key. A retried submit with the same key returns the original request with 200 instead of charging again. The key identifies the first submission made with it; later bodies are not compared. A refusal recorded under the key (its envelope carries request_id) replays the same way, so a new attempt needs a new key.
1 - 255Path Parameters
The architecture id, from the catalog.
mango, krea_2, moss_image, minimax_h3_image, minimax_h3, magejutsu, z_image, stable_diffusion_xl, kiwi, blueberry, wan_22, flux2, chroma, hidream, ltx_video, stable_diffusion_v15, stable_diffusion_v35_large, guava, nano_banana_v2, sdxl_plus, cherry, seedance, seedream, raspberry, grok_image, grok_video, berry, gpt_image_2, anima, melon, seed_audio, eleven_speech, eleven_music, minimax_music, plum, lemon, wan_3 Body
A partial config for the architecture.
Response
The request was accepted; poll status_url for the result. A retried submit whose Idempotency-Key was used before answers 200 with the same shape, the original request, and charges nothing.

