KI-Musik-API für Entwickler: Songs mit Gesang über REST, MCP und CLI

Die Musik-API von eroq macht ganze Songs mit Gesang und Instrumenten oder Instrumentals, aus einem Satz oder aus deinen eigenen Lyrics. Dahinter steckt dieselbe Engine wie im Tool „Musik“, Music One, mit denselben Credits und demselben Schlüssel wie der Rest der eroq-API. Dieser Leitfaden behandelt den Request, den asynchronen Job, Webhooks, die Abrechnung und das MCP-Tool für Agents. Die Referenz findest du unter /docs/music.

Zwei Wege, einen Song zu beschreiben

• Simple: Schick prompt, also den Song in einem Satz. Der Songwriter schreibt Stil, Lyrics und Titel, im Preis inbegriffen.
• Custom: Schick deinen eigenen style (Sprache, Gesang, Genre, Tempo, Instrumente) und lyrics, mit Abschnitts-Tags in eigenen Zeilen: [Intro], [Verse], [Pre-Chorus], [Chorus], [Bridge], [Outro]. Für einen style ohne lyrics werden die Lyrics passend dazu geschrieben.

Mit instrumental: true fällt der Gesang weg (Lyrics werden dann ignoriert). Mindestens eines der Felder prompt, style oder lyrics muss gesetzt sein.

Einen Song starten

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
  }'

Die Parameter, auf die es ankommt:

• seconds: die Länge, 30 bis 240 in 30er-Schritten. Der Wert rastet auf dieses Raster ein und wird nach der angefragten Länge abgerechnet.
• n: Takes, 1 oder 2 (Standard 2). Jeder Take ist ein eigener Job mit eigenem Seed und eigener Abbuchung.
• seed: reproduzierbare Takes; Take N rendert mit seed + N - 1.
• title: bis zu 80 Zeichen; fehlt er, gibt der Songwriter dem Song einen Namen.
• folder_id: der Ordner der Bibliothek, in dem die Takes landen.

Ein Song braucht Minuten an GPU-Zeit. Deshalb bucht der Aufruf ab, startet einen Job pro Take und antwortet mit 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 }
}

Die Antwort gibt title, style und lyrics zurück, aus denen der Song gerendert wird; im Simple-Modus siehst du also, was der Songwriter geschrieben hat.

Jeden Take pollen

Das Polling von GET /v1/music/generations/{id} ist kostenlos. Poll alle paar Sekunden, bis status auf succeeded oder failed steht:

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')
}

Ein fertiger Take enthält eine MP3-URL (audio/mpeg), seine echte Länge in seconds (ein Song kann sein Ende etwas vor der angefragten Länge finden) und seine library_id: Jeder Take wird außerdem mit seinem Rezept in deiner Bibliothek gespeichert. Job-IDs verfallen 24 Stunden nach ihrer Erstellung; wenn du die MP3 selbst auslieferst, lade sie also vorher herunter oder speichere sie.

Oder nimm einen signierten Webhook

Registriere einen Endpunkt im Entwickler-Dashboard und abonniere damit music.generation.succeeded und music.generation.failed. Jede Zustellung ist ein JSON-POST, signiert im Header eroq-signature (t=<timestamp>,v1=<HMAC-SHA256 of "t.body">), nach demselben Verfahren wie bei den Video-Events, erklärt in asynchrone Jobs und signierte Webhooks. Der Payload enthält die Job-ID und eine result_url, nie das Audio selbst.

Antworte schnell mit 2xx und erledige die Arbeit danach; behalte Polling als Rückfallebene für alles, wovon du nichts gehört hast.

Abrechnung

• 3 Credits pro angefangene 30 Sekunden Song und Take, nach der angefragten Länge: 6 Credits für eine Minute, 18 für drei, 24 für vier.
• n: 2 verdoppelt das. Nimm n: 1, wenn du keine Auswahl brauchst.
• Ein Take, der fehlschlägt oder nicht im Zeitfenster der Engine fertig wird, wird einzeln erstattet; der andere Take wird trotzdem geliefert.
• Mit denselben Credits bezahlst du Bilder, Video, Sprache und Chat. Ein Paket für $10 enthält 1.000 Credits; ein Plan ist nicht nötig.

Inhaltsrichtlinie

Die Richtlinie gilt für alles, was du schickst, und für das, was der Songwriter schreibt. In ihrem Rahmen sind Lyrics unzensiert: Kraftausdrücke und düstere Themen sind in Ordnung. Abgelehnt werden: alles mit Minderjährigen, reale, identifizierbare Personen ohne Einwilligung, illegale Inhalte und sexuelle Gewalt; der Songwriter nennt nie einen echten Künstler. Ein abgelehnter Request antwortet mit 400 content_blocked und kostet nichts, oder er wird erstattet, wenn die geschriebenen Lyrics das Problem sind.

Ist die Engine auf einem Deployment nicht live, antwortet der Aufruf mit 503 model_unavailable, bevor etwas abgebucht wird; GET /v1/engines meldet das.

Für KI-Agents: MCP

Der MCP-Server von eroq stellt ChatGPT, Claude, Claude Code, Cursor und Codex das Tool generate_music bereit. Es nimmt prompt (ein Satz) oder style + lyrics, dazu title, instrumental und seconds, wartet kurz und gibt den Song zurück oder eine Job-ID, die du mit get_music_status prüfst. Verbinde ihn über die MCP-Seite. Bitte deinen Assistenten: „Mach mir ein 30-sekündiges Lo-Fi-Intro für meinen Podcast“, und er ruft das Tool auf.

Aus dem Terminal: die 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

Die CLI pollt, bis die MP3 fertig ist, und speichert sie als Datei. Ihr Befehl eroq mcp startet einen lokalen MCP-Server, der Songs als Dateien in deinem Arbeitsverzeichnis speichert – genau das, was Coding-Agents brauchen.

Häufige Fragen

Gibt es eine API für KI-Musikgenerierung mit Gesang?

Ja. POST /v1/music/generations macht Songs mit Gesang oder Instrumentals, aus einem Satz oder aus deinem eigenen Stil und deinen eigenen Lyrics. Die API arbeitet asynchron: ein Job pro Take, kostenlos gepollt oder per Webhook zugestellt.

Was kostet die Musik-API?

3 Credits pro angefangene 30 Sekunden und Take, genau wie im Studio. Ein zweiminütiger Song kostet 12 Credits pro Take.

Wie lang kann ein generierter Song sein?

Von 30 bis 240 Sekunden, in 30er-Schritten.

Welche Webhook-Events sendet ein Song?

music.generation.succeeded und music.generation.failed, signiert mit dem Header eroq-signature.

Kann ich über die API eigene Lyrics schreiben?

Ja. Schick style und lyrics mit Abschnitts-Tags wie [Verse] und [Chorus] in eigenen Zeilen, bis zu 3.000 Zeichen Lyrics.

Kann ein KI-Assistent mit eroq Songs machen?

Ja, über das MCP-Tool generate_music, verfügbar in ChatGPT, Claude, Claude Code, Cursor und Codex, sobald du eroq verbunden hast.