Asynchrone Jobs & Abfragen

Viele Medienendpunkte sind asynchron. Eine Erstellungsanfrage startet die Arbeit und gibt eine öffentliche TokenLab-Aufgabenidentität zurück; Ihre Anwendung fragt ab, bis diese Aufgabe einen terminalen Status erreicht. Bauen Sie keine Kunden-Workflows um upstream-Aufgaben-URLs, Routing-IDs oder das Callback-Verhalten des Anbieters.

Öffentlicher Aufgabenvertrag

Erstellungsantworten können Folgendes enthalten:

Feld	Bedeutung	Was zu tun ist
`id`	Öffentliche TokenLab-Aufgaben-ID	Speichern Sie es mit Ihrem eigenen Jobdatensatz
`task_id`	Kompatibilitätsalias für dieselbe öffentliche Aufgabenidentität	Behandeln Sie es als gleichwertig zu `id`
`status`	Aktueller öffentlicher Aufgabenstatus	Beginnen Sie mit der Abfrage, wenn er nicht terminal ist
`poll_url`	Bevorzugte Status-URL	Verwenden Sie dies zuerst, wenn vorhanden
`model`	Modell, das vom Endpunkt angefordert oder gelöst wurde	Speichern Sie es für Support- und Abrechnungsversöhnung

/v1/tasks/{id} ist der kanonische feste Statusendpunkt für öffentliche asynchrone Medienjobs. Medien-spezifische Statusrouten können zur Kompatibilität existieren, aber neue Integrationen sollten poll_url oder /v1/tasks/{id} bevorzugen.

Empfohlener Ablauf

Validieren Sie die Benutzeranfrage und senden Sie den Erstellungsaufruf mit einem expliziten model.
Speichern Sie id / task_id, poll_url, Endpunkt, Modell, Benutzer-ID und Ihre eigene Job-ID, bevor Sie die Kontrolle an die UI zurückgeben.
Fragen Sie alle 5-10s für lang laufende Medienaufgaben ab.
Stoppen Sie nur, wenn die Aufgabe completed oder failed ist.
Bei completed lesen Sie die medien-spezifischen Ergebnisfelder und speichern Sie endgültige URLs oder Metadaten.
Bei failed speichern Sie den öffentlichen Fehler und bieten Sie einen erneuten Versuch nur als neuen benutzer-sichtbaren Job an.

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "model": "veo3.1"
}

Abfragebeispiel

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

Erwartete öffentliche Status sind pending, processing, completed und failed. Abgebrochene Aufgaben werden als failed mit cancelled: true und cancellation_status: "cancelled" dargestellt, damit die ältere Statusverarbeitung weiterhin funktioniert.

Client-Wiederholungsregeln

Netzwerkzeitüberschreitungen sind die häufigste Quelle für doppelte Jobs. Verwenden Sie diese Regel:

Wo die Zeitüberschreitung auftritt	Sichereres Verhalten
Bevor Ihr Server eine Erstellungsantwort erhält	Überprüfen Sie die Serverprotokolle auf `request_id`; wiederholen Sie nur, wenn keine Aufgabe erstellt wurde
Nachdem eine Erstellungsantwort gespeichert wurde	Setzen Sie die Abfrage der gespeicherten `task_id` fort
Während der Abfrage	Wiederholen Sie die Statusanfrage mit Backoff
Nach terminalem Status	Fragen Sie nicht erneut ab, es sei denn, der Benutzer aktualisiert ausdrücklich den Datensatz

Senden Sie keine zweite Erstellungsanfrage nur, weil der Browser aktualisiert wurde oder eine Statusabfrage fehlgeschlagen ist.

Abrechnung und Abwicklung

Asynchrone Jobs können einen geschätzten Betrag reservieren, wenn die Erstellungsanfrage akzeptiert wird. Die endgültige Abwicklung erfolgt nach terminalem Status. Wenn verfügbar, können die Antworten zum Aufgabenstatus billing_transaction_id und den Header X-Billing-Transaction-ID offenbaren. Für die Versöhnung verbinden Sie diese Identifikatoren in Ihren Protokollen:

request_id aus der Erstellungsanfrage.
task_id / id aus der Aufgabe.
billing_transaction_id, wenn vorhanden.
Ihre eigene Benutzer-ID, Projekt-ID oder Job-ID.

Stornierung

DELETE /v1/tasks/{id} ist absichtlich eng gefasst. Es unterstützt derzeit wartende Volcengine Seedance-Videoaufgaben wie seedance-1.5-pro, seedance-2.0 und seedance-2.0-fast. Nicht unterstützte Aufgaben geben 400 unsupported_task_cancel zurück. Aufgaben, die bereits laufen oder terminal sind, geben 409 task_not_cancellable zurück. Erstellen Sie die Stornierungs-UI als “Stornierung anfordern” anstatt als garantierten Stopp-Button.

Fehlersuche

Symptom	Wahrscheinliche Ursache	Was zu überprüfen ist
`async_task_not_found`	Aufgabe ist unbekannt, abgelaufen, für diesen API-Schlüssel nicht zugänglich oder keine öffentliche asynchrone Aufgabe	Bestätigen Sie den Besitz des API-Schlüssels und die gespeicherte öffentliche `task_id`
Aufgabe scheint nie zu enden	Client fragt die falsche URL ab oder hat vor dem terminalen Status gestoppt	Verwenden Sie `poll_url` oder `/v1/tasks/{id}` und überprüfen Sie den neuesten Status
Endgültige Medien-URL fehlt	Aufgabe ist nicht abgeschlossen oder der upstream-Job wurde ohne verwendbare Ausgabe abgeschlossen	Fragen Sie weiter ab, bis terminal, und behandeln Sie fehlende Ausgaben als fehlgeschlagen
Benutzer sieht Duplikate	Der Wiederholungsweg hat nach Zeitüberschreitung oder Aktualisierung eine neue Aufgabe erstellt	Dedupizieren Sie nach Ihrer eigenen Job-ID und gespeicherter `task_id`
Abrechnungsabweichung	Abwicklung ist asynchron oder der Client vergleicht Anbieter-IDs	Vergleichen Sie `request_id`, `task_id` und `billing_transaction_id`

Support-Paket

Wenn Sie den Support kontaktieren, fügen Sie request_id, task_id, billing_transaction_id (wenn vorhanden), Endpunkt, Modell, Zeitstempel und eine bereinigte Anfrageform hinzu. Fügen Sie keine API-Schlüssel, privaten Medien, signierten URLs oder vollständigen Eingabeaufforderungen hinzu, es sei denn, der Support fordert ein redigiertes Beispiel an.

API-Referenz

Thema	Referenz
Aufgabenstatus abrufen	Get Task Status
Aufgabe stornieren	Cancel Task
Bildgenerierung	Image Generation
Videoerzeugung	Video Generation
Musikgenerierung	Music Generation
3D-Generierung	3D Generation
Abrechnung & Preisgestaltung	Billing & Pricing

​Öffentlicher Aufgabenvertrag

​Empfohlener Ablauf

​Abfragebeispiel

​Client-Wiederholungsregeln

​Abrechnung und Abwicklung

​Stornierung

​Fehlersuche

​Support-Paket

​API-Referenz