Medienleitfäden
Musikgenerierung
Erstellen Sie Songs oder Liedtexte und warten Sie auf das fertige Audio
Die Musikgenerierung erfolgt asynchron. POST /v1/music/generations gibt eine Task-ID, einen Status und normalerweise eine poll_url zurück. Fragen Sie mit GET /v1/tasks/{id} und dieser ID den Status ab, bis die Aufgabe completed (abgeschlossen) oder failed (fehlgeschlagen) ist.
Wählen Sie, was erstellt werden soll
| Zu erstellendes Element | Schlüsselfelder | Hinweise |
|---|---|---|
| Vollständiger Song oder Instrumental | model, mv, prompt, optional title, tags, action: "MUSIC" | Verwenden, wenn der Benutzer ein fertiges Audio erwartet |
| Nur Liedtexte | model, prompt, action: "LYRICS" | Nur mit Modellen verwenden, die die Generierung von Liedtexten unterstützen |
| Bestehenden Clip fortsetzen | model, mv, prompt, continue_clip_id, optional continue_at | Behalten Sie die ID des vorherigen Clips bei |
| Eigenes Audio covern oder erweitern | model, mv, prompt, audio_url, optional audio_operation | audio_url muss eine öffentliche URL sein. audio_operation ist standardmäßig upload-cover; upload-extend erfordert zusätzlich continue_at |
| Instrumental hinzufügen, Abschnitt ersetzen oder Stems trennen | audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation oder advanced-split | Jeder Vorgang hat eigene erforderliche Felder; siehe Musik erstellen |
Rufen Sie die aktuelle Liste der Musikmodelle ab unter:
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
-H "Authorization: Bearer sk-your-api-key"Das folgende Beispiel verwendet suno-music mit mv: "chirp-v6". Andere Musikmodelle, wie z. B. stable-audio-3, verwenden andere Felder wie duration und output_format; lesen Sie zuerst die Details des jeweiligen Modells. Wählen Sie für reine Liedtexte ein Modell, das die Generierung von Liedtexten dokumentiert, senden Sie action: "LYRICS" und lassen Sie mv weg.
Eine Musikaufgabe erstellen
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-v6",
"prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
"title": "Morning Static",
"tags": "synth-pop, upbeat",
"action": "MUSIC"
}'Prompts, Titel und Tags können in Ihrem Produktverlauf erscheinen. Platzieren Sie niemals API-Schlüssel, private URLs oder Diagnosedaten darin.
Das fertige Audio abrufen
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"Antwortformat
Die Antwort auf die Erstellung ist ein Aufgaben-Datensatz, nicht das fertige Audio:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"created": 1706000000,
"model": "suno-music"
}Eine abgeschlossene Abfrageantwort kann die finalen Medienfelder enthalten:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "completed",
"audio_url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"title": "Morning Static",
"lyrics": "[Verse 1]\n...",
"media_retention": {
"days": 30,
"items": [
{
"url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"kind": "audio",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"kind": "video",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"kind": "image",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
}
]
}
}Finale Medienfelder fehlen, bis der status auf completed steht. Fehlgeschlagene Aufgaben geben status: "failed" mit einem error zurück.
Die Status sind pending, processing, completed und failed. Eine abgeschlossene Aufgabe kann audio_url, video_url, title, lyrics und andere Metadaten enthalten. Die Medien-URLs sind TokenLab-URLs, die 30 Tage lang gültig bleiben; laden Sie Ergebnisse, die Sie länger benötigen, herunter oder speichern Sie diese.
Den richtigen Status anzeigen
- Zeigen Sie unmittelbar nach der Aufgabenerstellung einen ausstehenden Status (pending) an.
- Fragen Sie bei langen Aufgaben alle
5-10sab und stoppen Sie beicompletedoderfailed. - Zeigen Sie keinen finalen Player an, bis die Aufgabe
completedist und eineaudio_urlexistiert. - Rendern Sie bei Aufgaben, die nur Liedtexte betreffen, die Textausgabe getrennt von Audioaufgaben, damit Benutzer verstehen, was sie erhalten.
- Setzen Sie beim Aktualisieren der Seite die Arbeit mit der gespeicherten
task_idfort, anstatt eine neue Aufgabe zu erstellen.
Abrechnungsdatensätze
Musikaufgaben können bei der Erstellung einen geschätzten Betrag reservieren. Der endgültige Betrag wird nach Abschluss oder Fehler erfasst. Speichern Sie request_id, task_id, Modell, Endpunkt und billing_transaction_id, sobald diese erscheinen; verwenden Sie die Nutzungsdatensätze der Management API für die endgültige Abrechnung.
Häufige Fehler
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Aufgabe erstellt, aber kein Player | Aufgabe ist noch ausstehend oder wurde ohne audio_url abgeschlossen | Weiter abfragen bis zum Endstatus, dann fehlende Ausgabe als fehlgeschlagenen Benutzerauftrag behandeln |
| Doppelte Songs nach Aktualisierung | UI hat die Aufgabe neu erstellt statt fortzusetzen | task_id beibehalten und wiederverwenden |
| Liedtext-Aufgabe liefert kein Audio | action: "LYRICS" ist nur Text | UI-Pfade für Liedtexte und Musik trennen |
| Nicht unterstützter Parameter | Das ausgewählte Modell akzeptiert das Feld nicht | Entfernen Sie es oder wählen Sie ein Modell, das es dokumentiert |
API-Referenz
| Thema | Referenz |
|---|---|
| Musik erstellen | Musik erstellen |
| Musikstatus abrufen | Musikstatus abrufen |
| Aufgabenstatus abrufen | Aufgabenstatus abrufen |
| Modelle auflisten | Modelle auflisten |
| Abrechnung & Preise | Abrechnung & Preise |