Skip to main content
POST
Seed Audio
Voices, dialogue, music, and sound effects from a prompt, as an MP3 of exactly the requested duration.

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.

Rules

A request that breaks one of these is refused with 400 invalid_config before any gems are charged.
  • An image reference cannot be combined with audio references: send one kind or the other.
  • The prompt is at most 2986 characters.
  • sample_rate is one of 8000, 16000, 24000, 32000, 44100, 48000.
  • speech_rate is a whole number from -50 to 100.
  • loudness_rate is a whole number from -50 to 100.
  • pitch_rate is a whole number from -12 to 12.
Every field below that you leave out keeps its default. Option values are the tokens listed per field; a numeric token may be sent as a number. Fields the schema does not list pass through to the model unchanged. The exact charge for other settings is in the response’s billing.gems_charged, and the balance at GET /v1/account.

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string

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.

Required string length: 1 - 255

Body

application/json

A partial config for Seed Audio.

prompt
string
required

The text prompt.

Minimum string length: 1
seed
integer | null

Integer seed for reproducible output; omit or send null for a random seed.

model_id
enum<string>
default:seed-audio-1.0

The model variant to generate with.

Available options:
seed-audio-1.0
duration
enum<string>
default:5

Clip length in seconds, as a token.

Available options:
5,
10,
30,
60,
120
image

The reference image. An https URL or a data URL.

sample_rate
number
default:48000
speech_rate
number
default:0
loudness_rate
number
default:0
pitch_rate
number
default:0

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.

request_id
string<uuid>
required

The request id, also the id in status_url and cancel_url.

status
enum<string>
required

queued and in_progress are live; completed, failed, and cancelled are final.

Available options:
queued,
in_progress,
completed,
failed,
cancelled
architecture
string
required

The architecture the request generates with.

model_id
string | null
required

The model variant, when the architecture has variants.

created_at
string<date-time>
required

When the request was accepted.

updated_at
string<date-time>
required

When the request last changed.

billing
object
required
result
object | null
required

The output once status is completed, else null.

error
object | null
required

Why the request failed once status is failed, else null.

status_url
string<uri>
required

Poll this URL for the request.

cancel_url
string<uri>
required

POST to this URL to stop the request.

Last modified on September 23, 2026