curl --request POST \
--url https://api.mage.space/v1/cherry/generate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
"aspect_ratio": "16:9",
"duration": "4"
}
'import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const request = await mage.run('cherry', {
prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',
aspect_ratio: '16:9',
duration: '4',
});
console.log(request.result.url);from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
request = mage.run("cherry", {
"prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
"aspect_ratio": "16:9",
"duration": "4",
})
print(request["result"]["url"])const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',
aspect_ratio: '16:9',
duration: '4'
})
};
fetch('https://api.mage.space/v1/cherry/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": "cherry",
"model_id": "cherry-2-pro",
"created_at": "2026-09-17T14:52:48.000Z",
"updated_at": "2026-09-17T14:52:49.000Z",
"billing": {
"mode": "gems",
"gems_charged": 618
},
"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_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."
}
}Cherry
Generate video with Cherry through the Mage API: the fields of POST /v1/cherry/generate, its options by model, the rules it enforces, and its gem price.
curl --request POST \
--url https://api.mage.space/v1/cherry/generate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
"aspect_ratio": "16:9",
"duration": "4"
}
'import Mage from '@mage-space/sdk';
const mage = new Mage(); // reads MAGE_API_KEY
const request = await mage.run('cherry', {
prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',
aspect_ratio: '16:9',
duration: '4',
});
console.log(request.result.url);from mage_space import Mage
mage = Mage() # reads MAGE_API_KEY
request = mage.run("cherry", {
"prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
"aspect_ratio": "16:9",
"duration": "4",
})
print(request["result"]["url"])const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',
aspect_ratio: '16:9',
duration: '4'
})
};
fetch('https://api.mage.space/v1/cherry/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": "cherry",
"model_id": "cherry-2-pro",
"created_at": "2026-09-17T14:52:48.000Z",
"updated_at": "2026-09-17T14:52:49.000Z",
"billing": {
"mode": "gems",
"gems_charged": 618
},
"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_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."
}
}| Detail | |
|---|---|
| Type | Video |
| Models | cherry-mini (Cherry Mini), cherry (Cherry), cherry-pro (Cherry Pro), cherry-2 (Cherry 2), cherry-2-pro (Cherry 2 Pro, default) |
| Image inputs | image (reference image), additional_images (additional reference images) |
| Video inputs | videos (source videos) |
| Gems | 618 at the default settings |
| Model page | Cherry |
Options by model
The tokens each variant accepts. A field left out inherits the architecture default, clamped to the variant’s first listed token when the variant does not offer it.| Model | resolution | duration |
|---|---|---|
cherry-mini | 480p, 720p | 4, 5, 8, 10, 15 |
cherry | 480p, 720p | 4, 5, 8, 10, 15 |
cherry-pro | 480p, 720p, 1080p, 4k | 4, 5, 8, 10, 15 |
cherry-2 | 480p, 720p | 4, 5, 8, 10, 15, 20, 25, 30 |
cherry-2-pro | 480p, 720p, 1080p, 4k | 4, 5, 8, 10, 15, 20, 25, 30 |
Mentions
Write@handle in prompt to attach one of your saved entities, exactly as in the app. Each mention counts against the budget below; a mention that does not resolve, or that the chosen model does not support, is refused with 400 invalid_config before any gems are charged. See Characters and references.
| Mention | Models | Budget |
|---|---|---|
| Characters | All models | 8 images, characters, and references per request (cherry-2: 10, cherry-2-pro: 29) |
| References | All models | 8 images, characters, and references per request (cherry-2: 10, cherry-2-pro: 29) |
| Audio references | All models | 3 audio sources per request, counting the voices of mentioned characters |
{
"prompt": "@ana walking through a night market, wearing @red-coat"
}
use_character_voices: false to leave the voices out.
Rules
A request that breaks one of these is refused with400 invalid_config before any gems are charged.
- Video editing takes exactly one source video, of 4 to 30 seconds on
cherry-2andcherry-2-proand 2 to 15 seconds on the other models. - On
cherry-2andcherry-2-proan edit keeps its source video’s length and aspect ratio:durationandaspect_ratioare ignored, and the price follows the video’s length.
billing.gems_charged, and the balance at GET /v1/account.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 - 255Body
A partial config for Cherry.
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.

