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 ElementSchlüsselfelderHinweise
Vollständiger Song oder Instrumentalmodel, mv, prompt, optional title, tags, action: "MUSIC"Verwenden, wenn der Benutzer ein fertiges Audio erwartet
Nur Liedtextemodel, prompt, action: "LYRICS"Nur mit Modellen verwenden, die die Generierung von Liedtexten unterstützen
Bestehenden Clip fortsetzenmodel, mv, prompt, continue_clip_id, optional continue_atBehalten Sie die ID des vorherigen Clips bei
Eigenes Audio covern oder erweiternmodel, mv, prompt, audio_url, optional audio_operationaudio_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 trennenaudio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation oder advanced-splitJeder 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-10s ab und stoppen Sie bei completed oder failed.
  • Zeigen Sie keinen finalen Player an, bis die Aufgabe completed ist und eine audio_url existiert.
  • 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_id fort, 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

SymptomWahrscheinliche UrsacheLösung
Aufgabe erstellt, aber kein PlayerAufgabe ist noch ausstehend oder wurde ohne audio_url abgeschlossenWeiter abfragen bis zum Endstatus, dann fehlende Ausgabe als fehlgeschlagenen Benutzerauftrag behandeln
Doppelte Songs nach AktualisierungUI hat die Aufgabe neu erstellt statt fortzusetzentask_id beibehalten und wiederverwenden
Liedtext-Aufgabe liefert kein Audioaction: "LYRICS" ist nur TextUI-Pfade für Liedtexte und Musik trennen
Nicht unterstützter ParameterDas ausgewählte Modell akzeptiert das Feld nichtEntfernen Sie es oder wählen Sie ein Modell, das es dokumentiert

API-Referenz

ThemaReferenz
Musik erstellenMusik erstellen
Musikstatus abrufenMusikstatus abrufen
Aufgabenstatus abrufenAufgabenstatus abrufen
Modelle auflistenModelle auflisten
Abrechnung & PreiseAbrechnung & Preise

Auf dieser Seite