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 WorkflowCopy Anchor Link

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 MusikaufgabeCopy Anchor Link

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 AbschlussCopy Anchor Link

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"

AntwortstrukturCopy Anchor Link

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 StatusverwaltungCopy Anchor Link

• 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 AbgleichCopy Anchor Link

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 FehlerCopy Anchor Link

API-ReferenzCopy Anchor Link