The AI video generation API, from text or images

At a glance

The Mage video generation API is a REST API at https://api.mage.space/v1 that runs 12 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.

• 12

  video models

• $0.02

  Cheapest default, per clip

• 20

  Concurrent generations

• $0

  Monthly 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.

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.

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"

import os, time, requests

headers = {"Authorization": f"Bearer {os.environ['MAGE_API_KEY']}"}
request = requests.post(
    "https://api.mage.space/v1/berry/generate",
    headers=headers,
    json={
      "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
      "aspect_ratio": "16:9",
      "duration": "3",
      "model_id": "berry-2"
    },
).json()

while request["status"] in ("queued", "in_progress"):
    time.sleep(3)
    request = requests.get(request["status_url"], headers=headers).json()

print(request["status"], request["result"] and request["result"]["url"])

const headers = {
  Authorization: `Bearer ${process.env.MAGE_API_KEY}`,
  'Content-Type': 'application/json',
};
let request = await fetch('https://api.mage.space/v1/berry/generate', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    "prompt": "A slow push-in on a lighthouse at dusk, waves breaking below",
    "aspect_ratio": "16:9",
    "duration": "3",
    "model_id": "berry-2"
  }),
}).then((response) => response.json());

while (['queued', 'in_progress'].includes(request.status)) {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  request = await fetch(request.status_url, { headers }).then((r) => r.json());
}

console.log(request.status, 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. 01

   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. 02

   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. 03

   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

Use cases

What developers build with the video API

FAQ

Frequently asked questions

Start building with Mage

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

Related

• AI image generation API
• AI audio generation API
• Mage MCP server
• All API models
• API playground
• API documentation