Musikgenerierung

Die Musikgenerierung ist asynchron. POST /v1/music/generations erstellt eine öffentliche TokenLab-Aufgabe und gibt id / task_id, status und normalerweise poll_url zurück. Ihre Anwendung sollte diese Aufgabenidentität speichern, den Fortschritt anzeigen und bis zu einem terminalen Status abfragen.

Wählen Sie den Workflow

Workflow	Schlüsselattribute	Hinweise
Vollständiges Lied oder Instrumental	`model`, `mv`, `prompt`, optional `title`, `tags`, `action: "MUSIC"`	Verwenden, wenn der Benutzer mit finalem Audio rechnet
Nur Texte	`model`, `prompt`, `action: "LYRICS"`	Nur verwenden mit Modellen, die die Liedgenerierung unterstützen
Fortsetzung eines bestehenden Clips	`continue_clip_id`, optional `continue_at`	Speichern Sie die vorherige öffentliche Clip-/Aufgabenidentität, bevor Sie die Fortsetzung anbieten

Fragen Sie den aktuellen Modellkatalog ab, bevor Sie eine fest codierte Modellliste versenden:

curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"

Die aktuellen öffentlichen Beispiele verwenden suno_music für die Musikgenerierung und enthalten mv mit einer offiziellen Suno-Modellversion wie chirp-v4. Für reine Textflüsse senden Sie action: "LYRICS" mit einem Modell, dessen unterstützte Operationen die Liedgenerierung dokumentiert, und lassen mv weg. Behandeln Sie Modell-IDs als öffentliche TokenLab-IDs, nicht als Garantie, dass anbieter-spezifische Felder öffentliche Vertragsfelder sind.

Erstellen Sie eine Musikaufgabe

curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "mv": "chirp-v4",
    "prompt": "Ein fröhlicher Synth-Pop-Track mit warmen Vocals und einem klaren Refrain",
    "title": "Morgenstatik",
    "tags": "synth-pop, fröhlich",
    "action": "MUSIC"
  }'

Halten Sie Prompts, Titel und Tags benutzersichtbar und sicher speicherbar. Platzieren Sie keine API-Schlüssel, privaten URLs oder privaten Diagnoseinformationen in einem Prompt-Feld.

Abfragen auf Abschluss

Verwenden Sie zuerst poll_url. Wenn Ihr Client eine feste Route benötigt, rufen Sie GET /v1/tasks/{id} mit der zurückgegebenen id oder task_id auf.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Antwortstruktur

Die Create-Antwort ist ein abfragbarer Aufgabendatensatz, nicht die finale Audiodatei:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "suno_music"
}

Eine abgeschlossene Polling-Antwort kann die finalen Medienfelder enthalten:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "completed",
  "audio_url": "https://cdn.example.com/music/abc123.mp3",
  "video_url": "https://cdn.example.com/music/abc123.mp4",
  "stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
  "image_url": "https://cdn.example.com/music/cover.jpg",
  "title": "Morning Static",
  "lyrics": "[Verse 1]\n..."
}

Finale Medienfelder fehlen, bis status completed ist. Fehlgeschlagene Aufgaben geben status: "failed" mit error zurück. Erwartete öffentliche Status sind pending, processing, completed und failed. Eine abgeschlossene Musikaufgabe kann audio_url, video_url, title, lyrics und normalisierte Metadaten enthalten. Speichern Sie endgültige URLs in Ihrer eigenen Datenbank, damit der Benutzer das Ergebnis erneut öffnen kann, ohne die Generierung neu zu starten.

UI- und Statusverwaltung

Zeigen Sie sofort nach der Aufgabenerstellung einen ausstehenden Status an.
Abfragen Sie alle 5-10s für lange Aufgaben, und stoppen Sie dann bei completed oder failed.
Zeigen Sie keinen endgültigen Player an, bis die Aufgabe completed ist und eine audio_url existiert.
Bei nur Textaufgaben rendern Sie die Textausgabe separat von Audioaufgaben, damit die Benutzer verstehen, was sie kaufen.
Bei einer Aktualisierung setzen Sie die Speicherung von task_id fort, anstatt eine neue Aufgabe zu erstellen.

Abrechnung und Abgleich

Musikaufgaben können zum Zeitpunkt der Erstellung einen geschätzten Betrag reservieren und nach Bekanntwerden des terminalen Status abrechnen. Speichern Sie request_id, task_id, Modell, Endpunkt und billing_transaction_id, wenn sie erscheinen. Verwenden Sie die Nutzungsaufzeichnungen der Management-API für den Abgleich anstelle von anbieter-spezifischen Aufgaben-IDs.

Häufige Fehler

Symptom	Wahrscheinliche Ursache	Lösung
Aufgabe erstellt, aber kein Player	Aufgabe ist noch ausstehend oder abgeschlossen ohne `audio_url`	Weiter abfragen, bis terminal, dann fehlende Ausgabe als fehlgeschlagene Benutzeraufgabe behandeln
Doppelte Lieder nach Aktualisierung	UI hat die Aufgabe neu erstellt, anstatt fortzufahren	`task_id` speichern und wiederverwenden
Liedaufgabe gibt kein Audio zurück	`action: "LYRICS"` ist nur textbasiert	Trennen Sie die UI-Pfade für Texte und Musik
Nicht unterstützter Parameter	Feld ist nicht im Modelldetails des Modells	Entfernen Sie anbieter-spezifische Felder oder wählen Sie ein Modell, das diese dokumentiert

API-Referenz

Thema	Referenz
Musik erstellen	Musik erstellen
Musikstatus abrufen	Musikstatus abrufen
Aufgabenstatus abrufen	Aufgabenstatus abrufen
Modelle auflisten	Modelle auflisten
Abrechnung & Preisgestaltung	Abrechnung & Preisgestaltung

Erste Schritte

Kernleitfäden

Medienleitfäden

Wählen Sie den Workflow

Erstellen Sie eine Musikaufgabe

Abfragen auf Abschluss

Antwortstruktur

UI- und Statusverwaltung

Abrechnung und Abgleich

Häufige Fehler

API-Referenz

​Wählen Sie den Workflow

​Erstellen Sie eine Musikaufgabe

​Abfragen auf Abschluss

​Antwortstruktur

​UI- und Statusverwaltung

​Abrechnung und Abgleich

​Häufige Fehler

​API-Referenz

Wählen Sie den Workflow

Erstellen Sie eine Musikaufgabe

Abfragen auf Abschluss

Antwortstruktur

UI- und Statusverwaltung

Abrechnung und Abgleich

Häufige Fehler

API-Referenz