An AI music API for developers: songs with vocals over REST, MCP and CLI

eroq's music API makes full songs with vocals and instruments, or instrumentals, from one sentence or from your own lyrics. It is the same engine as the music studio, Music One, behind the same credits and key as the rest of the eroq API. This guide covers the request, the async job, webhooks, billing, and the MCP tool for agents. The reference lives at /docs/music.

Two ways to describe a song

• Simple: send prompt, the song in one sentence. The songwriter writes the style, the lyrics and a title, included in the price.
• Custom: send your own style (language, vocals, genre, tempo, instruments) and lyrics, with section tags on their own lines: [Intro], [Verse], [Pre-Chorus], [Chorus], [Bridge], [Outro]. A style without lyrics gets lyrics written for it.

Add instrumental: true to drop the vocals (lyrics are then ignored). One of prompt, style or lyrics is required.

Start a song

curl https://eroq.ai/v1/music/generations \
  -H "Authorization: Bearer $EROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "eroq-music-one",
    "prompt": "a melancholy synth-pop song about leaving a small town at night, warm female vocal",
    "seconds": 120,
    "n": 2
  }'

The parameters that matter:

• seconds: the length, 30 to 240 in steps of 30. It is snapped to that grid and billed on the requested length.
• n: takes, 1 or 2 (default 2). Each take is its own job, its own seed and its own charge.
• seed: reproducible takes; take N renders with seed + N - 1.
• title: up to 80 characters; omitted, the songwriter names it.
• folder_id: the Library folder the takes land in.

A song takes minutes of GPU, so the call charges, starts one job per take and answers 202:

{
  "id": "4d2a91c0-…",
  "object": "music.generation",
  "status": "processing",
  "model": "eroq-music-one",
  "seconds": 120,
  "title": "Leaving Light",
  "style": "english, female vocals, synth-pop, 104 bpm, warm analog synths",
  "lyrics": "[Verse]\nStreetlights fade behind the bus\n…",
  "instrumental": false,
  "jobs": [
    { "id": "4d2a91c0-…", "poll": "/v1/music/generations/4d2a91c0-…", "take": 1, "seed": 182736 },
    { "id": "9b07e3f1-…", "poll": "/v1/music/generations/9b07e3f1-…", "take": 2, "seed": 182737 }
  ],
  "usage": { "credits_spent": 24, "credits_remaining": 852 }
}

The answer echoes the title, style and lyrics the song renders from, so in Simple mode you see what the songwriter wrote.

Poll each take

Polling GET /v1/music/generations/{id} is free. Poll every few seconds until status is succeeded or failed:

const BASE = 'https://eroq.ai/v1'
const headers = { Authorization: `Bearer ${process.env.EROQ_API_KEY}` }

async function waitForTake(id, { every = 5000, deadline = 15 * 60_000 } = {}) {
  const started = Date.now()
  while (Date.now() - started < deadline) {
    const take = await fetch(`${BASE}/music/generations/${id}`, { headers }).then(r => r.json())
    if (take.status === 'succeeded') return take.data[0]   // { url, content_type, seconds, library_id }
    if (take.status === 'failed') throw new Error(take.error?.message ?? 'take failed')
    await new Promise(resolve => setTimeout(resolve, every))
  }
  throw new Error('still rendering — poll again later')
}

A finished take carries an MP3 URL (audio/mpeg), its real length in seconds (a song can find its ending a little before the requested length) and its library_id: every take is also saved to your Library with its recipe. Job ids expire 24 hours after creation, so download or store the MP3 before then if you serve it yourself.

Or take a signed webhook

Register an endpoint in the developers dashboard and subscribe it to music.generation.succeeded and music.generation.failed. Each delivery is a JSON POST signed in the eroq-signature header (t=<timestamp>,v1=<HMAC-SHA256 of "t.body">), the same scheme as the video events, explained in async jobs and signed webhooks. The payload carries the job id and a result_url, never the audio itself.

Answer 2xx fast and do the work afterwards; keep polling as the fallback for anything you did not hear about.

Billing

• 3 credits per started 30 seconds of song, per take, on the requested length: 6 credits for a minute, 18 for three, 24 for four.
• n: 2 doubles it. Use n: 1 when you do not need a choice.
• A take that fails, or never finishes within the engine's window, is refunded on its own; the other take still delivers.
• The same credits pay for images, video, speech and chat. A $10 pack is 1,000 credits; no plan is required.

Content policy

The policy applies to everything you send and to what the songwriter writes. Lyrics are uncensored within it: profanity and dark themes are fine. Refused: anything involving minors, real identifiable people without consent, illegal content and sexual violence; the songwriter never names a real artist. A refused request answers 400 content_blocked and bills nothing, or is refunded when the written lyrics are the problem.

If the engine is not live on a deployment, the call answers 503 model_unavailable before any debit; GET /v1/engines reports it.

For AI agents: MCP

The eroq MCP server exposes generate_music to ChatGPT, Claude, Claude Code, Cursor and Codex. The tool takes prompt (one sentence) or style + lyrics, plus title, instrumental and seconds, waits briefly, and returns the song or a job id to check with get_music_status. Connect it from the MCP page. Ask your assistant "make me a 30-second lo-fi intro for my podcast" and it calls the tool.

From a terminal: the CLI

eroq music "a melancholy synth-pop song about leaving a small town" -s 120
eroq music --style "English, warm male vocal, folk" --lyrics "[Verse]…" -n 1 -o song.mp3
eroq music "a calm lo-fi beat for studying" --instrumental -s 60

The CLI polls until the MP3 is ready and saves it as a file. Its eroq mcp command runs a local MCP server that saves songs as files in your working directory, which suits coding agents.

FAQ

Is there an API for AI music generation with vocals?

Yes. POST /v1/music/generations makes songs with vocals, or instrumentals, from one sentence or from your own style and lyrics. It is asynchronous: one job per take, polled for free or delivered by webhook.

How much does the music API cost?

3 credits per started 30 seconds, per take, the same as in the studio. A two-minute song is 12 credits per take.

How long can a generated song be?

From 30 to 240 seconds, in steps of 30.

Which webhook events does a song send?

music.generation.succeeded and music.generation.failed, signed with the eroq-signature header.

Can I write my own lyrics through the API?

Yes. Send style and lyrics with section tags such as [Verse] and [Chorus] on their own lines, up to 3,000 characters of lyrics.

Can an AI assistant make songs with eroq?

Yes, through the MCP tool generate_music, available in ChatGPT, Claude, Claude Code, Cursor and Codex once you connect eroq.