Entwickler

API-Dokumentation

Alles, was du zum Entwickeln mit der MeloLab API brauchst: Authentifizierung, Credits, Generierung, Jobs, Webhooks und Bibliothekssuche.

Erste Schritte

Authentifiziere jede Anfrage mit deinem API-Schlüssel über den Header Authorization: Bearer. Die Basis-URL ist https://melolab.ai. Lese-Endpunkte verbrauchen keine Credits; das Erstellen einer Generierung nutzt deine vorhandenen MeloLab-Credits mit denselben Kosten- und Erstattungsregeln wie die Web-App. Sende beim Erstellen einer Generierung einen Idempotency-Key-Header, damit Wiederholungen sicher sind. Erfolgreiche Antworten sind in ein data-Objekt verpackt; Fehler geben code, message und request_id zurück.

Konto

Lies dein API-Profil, dein Credit-Guthaben und die jüngste Nutzung.

GET/api/v1/meprofile:read

Gibt das authentifizierte API-Profil zurück, inklusive Konto-Stufe und API-Verfügbarkeit.

curl -X GET https://melolab.ai/api/v1/me \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/creditscredits:read

Gibt dein vorhandenes MeloLab-Credit-Guthaben zurück. Verbraucht keine Credits.

curl -X GET https://melolab.ai/api/v1/credits \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/usageprofile:read

Gibt eine Nutzungsübersicht und aktuelle, anonymisierte Anfrage-Ereignisse zurück.

curl -X GET https://melolab.ai/api/v1/usage \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Modelle

Liste verfügbare MeloLab-Modelle und ihre Credit-Kosten auf.

GET/api/v1/modelsmodels:read

Listet verfügbare MeloLab-Modelle mit ihren Credit-Kosten auf.

curl -X GET https://melolab.ai/api/v1/models \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/models/{model_id}models:read

Gibt ein Modell anhand der id zurück.

curl -X GET https://melolab.ai/api/v1/models/suno/v5-5 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Generierungen

Erstelle eine Musikgenerierung, liste aktuelle Generierungen auf und frage einen Job ab, bis er fertig ist.

POST/api/v1/generationsgenerations:create

Erstellt eine asynchrone Musikgenerierung. Nutzt deine vorhandenen MeloLab-Credits; erfordert einen Idempotency-Key-Header.

curl -X POST https://melolab.ai/api/v1/generations \
  -H "Authorization: Bearer $MELOLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_id":"suno/v5-5","prompt":"warm lofi beat for a focus playlist"}'

GET/api/v1/generationsgenerations:read

Listet deine aktuellen Generierungs-Jobs auf.

curl -X GET https://melolab.ai/api/v1/generations \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/generations/{id}generations:read

Fragt eine Generierung ab und gibt nach Abschluss ihre Titel zurück.

curl -X GET https://melolab.ai/api/v1/generations/gen_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/jobs/{job_id}

Fragt einen asynchronen Job (Musik, Stem-Trennung oder Vocal-Entfernung) ab und gibt die Ausgaben zurück, sobald der Anbieter fertig ist.

curl -X GET https://melolab.ai/api/v1/jobs/job_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Bibliothek

Durchsuche abspielbare Titel und Playlists und lies Details einzelner Titel oder Playlists.

GET/api/v1/library/searchlibrary:read

Durchsucht abspielbare Titel und Playlists, einschließlich deiner eigenen privaten Inhalte.

curl -X GET https://melolab.ai/api/v1/library/search?q=lofi \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/tracks/{id}library:read

Gibt abspielbare Metadaten eines Titels zurück.

curl -X GET https://melolab.ai/api/v1/tracks/track_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/playlistslibrary:read

Listet die dir verfügbaren Playlists auf.

curl -X GET https://melolab.ai/api/v1/playlists \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

GET/api/v1/playlists/{id}library:read

Gibt eine Playlist und ihre Titel zurück.

curl -X GET https://melolab.ai/api/v1/playlists/playlist_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Webhooks

Registriere HTTPS-Endpunkte, um benachrichtigt zu werden, wenn asynchrone Jobs abgeschlossen sind – so musst du nicht abfragen. Das vollständige Signing-Secret wird nur einmal beim Erstellen eines Endpunkts angezeigt.

GET/api/v1/webhook-endpoints

Listet deine aktiven Webhook-Endpunkte auf.

curl -X GET https://melolab.ai/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

POST/api/v1/webhook-endpoints

Registriert einen öffentlichen HTTPS-Webhook-Endpunkt. Das Signing-Secret wird nur einmal zurückgegeben.

curl -X POST https://melolab.ai/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $MELOLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/melolab/webhook"}'

PATCH/api/v1/webhook-endpoints/{id}

Aktualisiert die URL oder den Status eines Webhook-Endpunkts.

curl -X PATCH https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"disabled"}'

DELETE/api/v1/webhook-endpoints/{id}

Löscht einen Webhook-Endpunkt.

curl -X DELETE https://melolab.ai/api/v1/webhook-endpoints/wh_123 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Protokolle

Sieh dir die API-Anfrageprotokolle der letzten 30 Tage an.

GET/api/v1/logs

Listet die API-Anfrageprotokolle der letzten 30 Tage auf.

curl -X GET https://melolab.ai/api/v1/logs?limit=20 \
  -H "Authorization: Bearer $MELOLAB_API_KEY"

Ratenlimits

Lese-Endpunkte erlauben 600 Anfragen pro Minute (50.000 pro Tag). Musikgenerierung erlaubt 12 Anfragen pro Minute (500 pro Tag). Authentifizierung ist auf 120 Anfragen pro Minute je IP begrenzt. Bei Überschreitung wird 429 rate_limited zurückgegeben.

Fehler

Fehler geben einen HTTP-Status plus einen JSON-Body { error: { code, message, request_id } } zurück. Gib request_id an, wenn du den Support kontaktierst.

Status	Code	Bedeutung
401	authentication_required	Im Authorization-Header wurde kein API-Schlüssel übergeben.
401	invalid_api_key	Der API-Schlüssel ist ungültig oder widerrufen.
401	revoked_api_key	Der API-Schlüssel wurde widerrufen und kann nicht mehr verwendet werden.
403	api_terms_not_accepted	Das API-Konto ist noch nicht bereit, weil die API-Bedingungen nicht akzeptiert wurden.
403	insufficient_scope	Dem API-Schlüssel fehlt ein erforderlicher Geltungsbereich.
400	invalid_request	Der Anfrage-Body oder die Parameter sind ungültig.
400	invalid_model	Die angeforderte Modell-id existiert nicht.
402	insufficient_credits	Nicht genug MeloLab-Credits, um diese Generierung zu erstellen.
400	idempotency_key_required	Diese Anfrage benötigt einen Idempotency-Key-Header.
409	idempotency_key_conflict	Der Idempotency-Key wurde mit einer anderen Anfrageform wiederverwendet.
409	idempotency_conflict	Der Idempotency-Key wurde mit einem anderen Anfrage-Body wiederverwendet.
409	generation_concurrency_exceeded	Für dieses Konto laufen bereits zu viele Generierungsjobs.
404	job_not_found	Der angefragte Job existiert nicht oder gehört nicht zu diesem Konto.
404	track_not_found	Der angefragte Track existiert nicht oder ist für dieses Konto nicht zugänglich.
404	playlist_not_found	Die angefragte Playlist existiert nicht oder ist für dieses Konto nicht zugänglich.
404	webhook_endpoint_not_found	Der angefragte Webhook-Endpunkt existiert nicht oder gehört nicht dir.
400	webhook_url_invalid	Die Webhook-URL ist ungültig.
400	webhook_https_required	Webhook-Endpunkte müssen HTTPS verwenden.
400	webhook_credentials_forbidden	Webhook-URLs dürfen keine eingebetteten Zugangsdaten enthalten.
400	webhook_host_blocked	Webhook-URLs dürfen nicht auf localhost, private oder blockierte Hosts zeigen.
429	rate_limited	Zu viele Anfragen; bitte langsamer und später erneut versuchen.
502	provider_unavailable	Der vorgelagerte Anbieter ist vorübergehend nicht verfügbar.
502	provider_timeout	Der vorgelagerte Anbieter hat nicht rechtzeitig geantwortet.
500	generation_failed	Die Generierung ist nach der Annahme fehlgeschlagen.
500	internal_error	Unerwarteter API-Plattformfehler.

API-Dokumentation

Erste Schritte

Konto

Modelle

Generierungen

Bibliothek

Webhooks

Protokolle

Ratenlimits

Fehler

Kostenlos starten

Erstellen

Transform

Analyze

Unternehmen