Create Music: POST /create-music

Turn a text prompt into a complete original song, with vocals, melody and full arrangement, delivered as a finished MP3 rather than a loop or preview. One call costs $0.50 in USDC on Base.

What it is for

Describe the genre, mood, instrumentation and tempo, supply your own lyrics, ask for an instrumental, or pin a style tag. The discovery document names soundtracks under video, release-ready artist tracks, podcast and game themes, and demo sketches as uses.

At a glance

Endpoint	`POST https://app.suedeai.ai/create-music`
Price	$0.50, `amount` `500000` USDC base units
Payment	x402 `exact` on `eip155:8453` to `0x10FF767043A1723E0BB5B9207bC37D3442cC9E4F`, or a Skyfire token
Paid response	`202 Accepted` with `songId` and `pollUrl`
Poll	`GET https://app.suedeai.ai/api/songs/{songId}`, free
Identifiers	OpenAPI `operationId`, A2A skill and MCP tool: `create_music`

Request body

Field	Type	Required	Description
`prompt`	string	Yes	The song you want: genre, mood, instruments and any specific vibe. Examples from the schema: "Upbeat 80s synthwave with driving bass and neon atmosphere", "A melancholic acoustic guitar ballad about rain".
`style`	string	No	A style or genre tag, such as `Hip Hop`, `Ambient` or `Rock`.
`custom_mode`	boolean	No	`true` to sing the lyrics you supply in `lyrics`.
`lyrics`	string	When `custom_mode` is `true`	Your lyrics.
`make_instrumental`	boolean	No	`true` for a track without vocals.
`vocal_gender`	string	No	`m` or `f`.
`tags`	string	No	Comma-separated keywords to tag the generated file.
`asyncMode`	boolean	No	Switches asynchronous mode on, never off. Paid calls are already asynchronous.

Example: your own lyrics

First send the request without PAYMENT-SIGNATURE to get the 402 challenge (amount 500000, priceUsd $0.50), sign it as shown in the quickstart, then send:

curl -i -X POST https://app.suedeai.ai/create-music \
  -H 'Content-Type: application/json' \
  -H "PAYMENT-SIGNATURE: $PAYMENT" \
  -H 'X-Idempotency-Key: rain-ballad-0001' \
  -d '{
    "prompt": "A melancholic acoustic guitar ballad about rain",
    "style": "Ambient",
    "custom_mode": true,
    "lyrics": "Your lyrics here",
    "vocal_gender": "f"
  }'

For a track without vocals, drop custom_mode and lyrics and send "make_instrumental": true.

Response to a paid call: 202 Accepted

Field	Description
`status`	`processing` or `queued`.
`shareUrl`	The browser share URL the track will have once the job completes.
`songId`	The id of the song row, and the `{songId}` in `pollUrl`. It can be `null` when the job is queued before that row exists.
`pollUrl`	The absolute URL of `GET /api/songs/{songId}`. No further payment.

With ?async=false the call blocks and answers 200 with shareUrl (a public page to listen to and download the track), title and imageUrl (cover art). Renders take minutes and payment clients time out in about 30 seconds, so the default asynchronous mode suits most callers.

Polling: GET /api/songs/{songId}

Music returns the song row, not the jobId and status shape the video and image polls use. Read model_version:

pending: the track is queued or rendering. Poll again.
failed: generation failed. This is final; stop polling.
Any version label, such as v4.5: the track is ready and audio_url is the finished MP3.

Until the track is ready, audio_url holds the placeholder cover-image URL the row was created with. It is a reachable image, not audio, so a present audio_url does not mean the track is finished.

Field	Description
`id`	The `songId` you polled.
`model_version`	The job state, as above.
`audio_url`	The finished MP3 once ready; a placeholder image URL before that.
`title`, `prompt`, `genre`	Track title, the prompt it was generated from, and the style label from the request.
`image_url`	Cover art URL.
`duration`	Length in seconds; `0` until the render finishes.
`share_id`	Public share identifier for the listener page.
`is_public`	`true` for x402 and Skyfire paid jobs, which are created public so the buyer can fetch them.
`created_at`	Creation time, ISO 8601.

An unknown songId answers 404 with {"error":"Song not found"}. Because paid jobs are created public, a 404 means the id is wrong, not that the track is still rendering.

Sources

app.suedeai.ai/.well-known/x402: description, price, payment requirement and input schema (resource entry last updated 2026-08-30).
app.suedeai.ai/openapi.json: operations create_music and create_music_result.
Live requests on 2026-10-11: the unpaid 402 challenge and the 404 for an unknown songId.