Skip to content
PlaygroundDocsGet API key

Mage API · Video generation

The AI video generation API, from text or images

Text-to-video, image-to-video, first-and-last-frame, and reference-to-video from 15 models, led by Mage's flagship Cherry 2 Pro, with audio on many clips.

Get an API keyRead the API docs
POST https://api.mage.space/v1/{model}/generate

At a glance

The Mage video generation API is a REST API at https://api.mage.space/v1 that runs 15 text-to-video and image-to-video models, including Cherry 2 Pro, Lemon, Plum, Melon, MiniMax-H3, Grok Video, and Wan. Submit a prompt and optional frames or references, poll the request, and download an MP4. Each clip is paid in Gems by model, resolution, and duration.

  • 15video models
  • $0.02Cheapest default, per clip
  • 20Concurrent generations
  • $0Monthly fee

Models

Every video model in the Mage API

Prices are per generation, in Gems. 1,000 Gems cost $1 on the standard pack, and larger packs add bonus Gems. The price depends on the model, resolution, and duration; the default-settings price is shown, and every response reports the exact charge in billing.gems_charged. A generation that fails is refunded; one Mage's content policy blocks is not.

ModelBest formodel_id valuesDefault price
BerryVideo that stays true to your referencesberry, berry-2189 Gems ($0.189)
BlueberryPin the first and last frameblueberry, blueberry-v2360 Gems ($0.36)
CherryOur flagship video familycherry-mini, cherry, cherry-pro, cherry-2-pro618 Gems ($0.618)
Grok VideoGrok Imagine, in motiongrok-imagine-video375 Gems ($0.375)
KiwiEveryday video, zero setupkiwi270 Gems ($0.27)
LemonEvery video feature, at a friendlier pricelemon245 Gems ($0.245)
LTX VideoFast open-weights video for iterationltx-video-096-distilled, ltx-video-096-dev20 Gems ($0.02)
MagejutsuRecast any video, keeping its motionmagejutsu, magejutsu-lite, magejutsu-feather1,856 Gems ($1.856)
MelonAnime in motion, with optional audiomelon, melon-pro147 Gems ($0.147)
MiniMax-H3Fast open video with stereo soundminimax-h3-turbo, pika-h3-flex, minimax-h345 Gems ($0.045)
PlumSound on every clip, up to 2Kplum, plum-max, plum-fast173 Gems ($0.173)
RaspberryCharacters brought to life from a first frameraspberry360 Gems ($0.36)
SeedanceSeedance, with a strict filterseedance-2.0-mini, seedance-2.0-fast, seedance-2.0, seedance-2.5618 Gems ($0.618)
Wan 3.0Wan 3.0, with a strict filterwan-3.0245 Gems ($0.245)
Wan Video v2.2Open-weights video with a Lightning variantwan22-video, wan22-video-lightning40 Gems ($0.04)

Quick start

Generate a video with Berry 2

Set MAGE_API_KEY, submit the request, and poll until it completes. Swap berry in the URL for any model above.

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/berry/generate' \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
  "aspect_ratio": "16:9",
  "duration": "3",
  "model_id": "berry-2"
}' | jq -r '.status_url')

# Repeat until status is "completed"; result.url is the file
curl "$STATUS_URL" --header "Authorization: Bearer $MAGE_API_KEY"
TypeScript
// npm install @mage-space/sdk
import Mage from '@mage-space/sdk';

const mage = new Mage(); // reads MAGE_API_KEY

const request = await mage.run('berry', {
  prompt: 'A slow push-in on a lighthouse at dusk, waves breaking below',
  aspect_ratio: '16:9',
  duration: '3',
  model_id: 'berry-2',
});

console.log(request.result.url);
Python
# pip install mage-space
from mage_space import Mage

mage = Mage()  # reads MAGE_API_KEY

request = mage.run("berry", {
    "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
    "aspect_ratio": "16:9",
    "duration": "3",
    "model_id": "berry-2",
})

print(request["result"]["url"])

How it works

From API key to finished media in three calls

Every model shares one authentication scheme, one asynchronous request lifecycle, and the same field names.

  1. Create an API key

    Sign in to Mage, open API → API Keys, and create a key. It starts with mage_sk_ and is shown once. An account can hold 10 active keys.

  2. Submit a generation

    POST a JSON body to https://api.mage.space/v1/{model}/generate with an Authorization: Bearer header. The response returns at once with a request_id, a status, and a status_url. Send an Idempotency-Key header so a retry never pays twice.

  3. Poll and download

    Poll status_url until the status is completed, failed, or cancelled. A completed request carries result.url with the image, video, or audio file, kept for 30 days.

Built for production

What every Mage API request gets

  • One key, every model

    35 image, video, and audio models behind one REST API and one Gems balance. Switch models by changing the URL path.

  • Pay per generation

    No subscription and no minimum spend. You buy Gems, and each request is charged its listed price. A generation that fails is refunded, unless Mage's content policy blocked it.

  • Safe retries

    Idempotency keys make a retried submit return the original request without charging again.

  • Consistent characters

    Save a character or reference once, then write @handle in any prompt to use it with every model that supports it.

  • Large inputs

    Send image, video, and audio inputs as URLs or data URLs, or upload files up to 100 MB through a signed upload.

  • 20 generations in flight

    Each account can run 20 generations at once, and the limit can be raised for your use case. Refused requests are never charged.

Use cases

What developers build with the video API

  • Short-form and social video

    Produce vertical clips for TikTok, Reels, and Shorts from a prompt or a product image.

  • Animate still images

    Turn a first frame, or a first and last frame, into motion with image-to-video models such as Lemon and Kiwi.

  • Character-driven stories

    Keep the same character across shots with reference-to-video models that take @handle characters.

  • Video with sound

    Plum and other models generate speech, sound effects, and ambience with the picture, and take audio references for voices.

  • Ads and product demos

    Generate many variants of a spot and pick the winner, with idempotent submits that never double-charge.

  • Edit existing clips

    Berry, Plum, and Grok Video edit a source video you send; Lemon and MiniMax-H3 also take reference videos.

FAQ

Frequently asked questions

What is the best AI video generation API?
On Mage, Cherry 2 Pro is the default for video: it supports characters, many reference images, audio references, 480p to 1080p output, and clips up to 30 seconds. Lemon is the choice for first-and-last-frame control, Plum for clips with generated sound up to 2K, and Cherry Mini or Wan for cheaper drafts.
Does the video API support image-to-video?
Yes. Image-to-video models take a first frame, and some also take a last frame or reference images, as URLs, data URLs, or uploads. Each model page lists its inputs and whether an image is required.
How long can generated videos be?
It depends on the model and resolution. Many models generate 4 to 15 seconds, and Cherry 2 Pro reaches 20, 25, and 30 seconds. Each model page lists its durations.
How long does a video generation take?
It depends on the model, resolution, and duration. The API is asynchronous: submit, then poll status_url with backoff, or let your MCP client wait with get_request.
How much does the Mage API cost?
There is no subscription or monthly fee. Each generation is paid in Gems at its model's listed price, and 1,000 Gems cost $1 on the standard pack. Every model page lists its default-settings price, and each response reports the exact charge. A generation that fails is refunded; one Mage's content policy blocks is not. A request your balance cannot cover is refused before anything is charged.
Do I need a Mage membership to use the API?
No. The API runs on Gems alone. Membership plans and their unlimited in-app generation do not apply to API requests. The account needs one successful payment first, any Gem pack or plan; signup bonus Gems work in the Mage app only.
Can I use API outputs commercially?
Yes. Content you create with Mage, including through the API and MCP server, can be used commercially. Attribution is appreciated but not required.
What are the rate limits?
An account can have 20 generations queued or running at once. A submit past that is refused with 429 and costs nothing. Write to [email protected] to raise the cap for your use case.
Can my AI agent use the Mage API?
Yes. Agents can call the REST API with a key, or connect to the Mage MCP server, which gives Claude, ChatGPT, Claude Code, Grok, and Cursor sixteen ready-made tools for choosing a model, quoting the price, generating, and fetching the result. See the MCP server.
Is there an SDK for the Mage API?
Yes. The official @mage-space/sdk package on npm and mage-space on PyPI are open source and typed for every model. They submit, wait for the result, retry safely, and upload files for you. ComfyUI users can install the comfyui-mage node pack. See the Mage SDKs.
I already use another generation API. What do I have to change?
Point your client at https://api.mage.space/v1, send your Mage key as a Bearer token, and map your fields to the model page: prompt, aspect_ratio, resolution, duration, and model_id work the same way across every Mage model. Requests are asynchronous, so submit and then poll status_url.

Start building with Mage

One account, one Gems balance, every model. Pay only for what you generate.

Get an API keyRead the API docs