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

Erstellungsantworten können Folgendes enthalten:

/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 AblaufCopy Anchor Link

1. Validieren Sie die Benutzeranfrage und senden Sie den Erstellungsaufruf mit einem expliziten model.
2. 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.
3. Fragen Sie alle 5-10s für lang laufende Medienaufgaben ab.
4. Stoppen Sie nur, wenn die Aufgabe completed oder failed ist.
5. Bei completed lesen Sie die medien-spezifischen Ergebnisfelder und speichern Sie endgültige URLs oder Metadaten.
6. 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"
}

AbfragebeispielCopy Anchor Link

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

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

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

Abrechnung und AbwicklungCopy Anchor Link

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.

StornierungCopy Anchor Link

DELETE /v1/tasks/{id} ist absichtlich eng gefasst. Wenn der ausgewählte Task Abbruch unterstützt, gilt es für wartende Seedance-Video-Tasks 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.

FehlersucheCopy Anchor Link

Support-PaketCopy Anchor Link

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