Skip to content
PlaygroundDocsGet API key

Mage API · Audio generation

The AI audio generation API for voices, music, and sound

Speech, narration, music, and sound effects from one prompt with Seed Audio, with voice references and speech, loudness, and pitch controls.

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

At a glance

The Mage audio generation API runs Seed Audio at https://api.mage.space/v1/seed_audio/generate. Send a text prompt, optionally with voice references or an image, and receive an audio file up to 120 seconds long with voices, music, or sound effects. Each clip is paid in Gems, with no subscription.

  • 3audio models
  • $0.019Cheapest default, per clip
  • 20Concurrent generations
  • $0Monthly fee

Models

Every audio 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
Eleven MusicElevenLabs songs, with vocals or withouteleven-music-v2.5113 Gems ($0.113)
Eleven SpeechElevenLabs v4: lifelike speech you can directeleven-v430 Gems ($0.03)
Seed AudioVoices, music, and sound effects from one promptseed-audio-1.019 Gems ($0.019)

Quick start

Generate audio with Eleven Music v2.5

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

cURL
STATUS_URL=$(curl --request POST 'https://api.mage.space/v1/eleven_music/generate' \
  --header "Authorization: Bearer $MAGE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "An upbeat indie pop song about a summer road trip, bright guitars, handclaps, female vocals, 110 BPM.",
  "duration": "30",
  "model_id": "eleven-music-v2.5"
}' | 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('eleven_music', {
  prompt: 'An upbeat indie pop song about a summer road trip, bright guitars, handclaps, female vocals, 110 BPM.',
  duration: '30',
  model_id: 'eleven-music-v2.5',
});

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

mage = Mage()  # reads MAGE_API_KEY

request = mage.run("eleven_music", {
    "prompt": "An upbeat indie pop song about a summer road trip, bright guitars, handclaps, female vocals, 110 BPM.",
    "duration": "30",
    "model_id": "eleven-music-v2.5",
})

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 audio API

  • Narration and voiceover

    Generate narration for videos, explainers, and audiobooks, with speech rate, loudness, and pitch controls.

  • Consistent voices

    Save a voice clip as a reference and mention it by @handle to keep the same voice across clips.

  • Sound effects

    Create ambience, foley, and UI sounds from a description for games and apps.

  • Music beds

    Produce background music for social clips and ads from a prompt.

  • Soundtracks for generated video

    Pair Seed Audio with the video API to add sound to clips from silent models.

  • Agents that speak

    Let Claude, ChatGPT, or your own agent produce audio through the MCP server or the REST API.

FAQ

Frequently asked questions

Can the audio API do text-to-speech?
Yes. Seed Audio reads a script in a described voice, or in a saved voice reference, and exposes speech rate, loudness, and pitch settings. It also generates music and sound effects from the same prompt field.
How long can generated audio be?
Seed Audio generates clips up to 120 seconds.
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