Kernleitfäden

Asynchrone Jobs und Polling

Erstellen Sie Medien-Tasks und warten Sie auf das fertige Ergebnis

Viele Medien-Endpunkte geben einen Task anstelle einer fertigen Datei zurück. Speichern Sie die zurückgegebene Task-ID und pollen Sie GET /v1/tasks/{id}, bis der Status completed (abgeschlossen) oder failed (fehlgeschlagen) lautet. Dieser eine Endpunkt dient für Bild-, Video-, Musik-, 3D-, Worlds- und asynchrone Audio-Transkriptions-Tasks.

Asynchrone Terminal-Task-Snapshots haben einen Lebenszyklus, der vom 30-tägigen Request/Response-Erfassungsfenster getrennt ist. Generierte Bild-, Video-, Audio-, 3D- und Worlds-Datei-URLs sind TokenLab-Medien-Ergebnis-URLs, die 30 Tage lang gültig bleiben. Task-Status-Abfragen von abgeschlossenen Tasks funktionieren für etwa 7 Tage; speichern Sie das Ergebnis daher, sobald der Task abgeschlossen ist. Die media_retention-Felder der Antwort geben den Speicherstatus und das expires_at (Ablaufdatum) jedes Elements an; diese können fehlen, wenn der Speicherstatus nicht rechtzeitig bekannt ist, wobei die URL weiterhin funktioniert. Fehlgeschlagene und laufende Tasks geben leere Medien-URL-Felder zurück. Siehe Datenaufbewahrung.

Zu speichernde Felder

Erstellungsantworten können Folgendes enthalten:

FeldBedeutungWas zu tun ist
idTokenLab Task-IDSpeichern Sie diese mit Ihrem eigenen Job-Datensatz
task_idEin anderer Name für dieselbe Task-IDBehandeln Sie diese als äquivalent zu id
statusAktueller Task-StatusPrüfen Sie weiter, bis der Task abgeschlossen oder fehlgeschlagen ist
poll_urlStatus-URL für den TaskSpeichern Sie diese; pollen Sie /v1/tasks/{id} mit der Task-ID
modelFür den Task verwendetes ModellSpeichern Sie dieses mit dem Task-Datensatz

Ein einziger Status-Endpunkt

Pollen Sie GET /v1/tasks/{id} mit der id oder task_id aus der Erstellungsantwort. Dies funktioniert für jeden Task-Typ. Für die meisten Tasks ist poll_url dieser gleiche Pfad. Eine Worlds-Erstellungsantwort gibt eine poll_url unter /v1/worlds/generations/{id} zurück; pollen Sie auch für Worlds /v1/tasks/{id} mit der Task-id.

Modalitätsspezifische Statuspfade, wie /v1/videos/generations/{id}, werden für bestehende Integrationen weiterhin unterstützt. Neue Integrationen sollten /v1/tasks/{id} verwenden.

Task speichern und Status prüfen

Speichern Sie id oder task_id, sobald die Erstellungsanfrage erfolgreich war. Speichern Sie poll_url, Modell, Endpunkt sowie Ihre eigene Benutzer- oder Job-ID dazu. Bei langen Medien-Jobs reicht es normalerweise aus, alle 5–10 Sekunden zu prüfen.

Stoppen Sie, wenn der Status completed oder failed erreicht. Ein abgeschlossener Task enthält das Medienergebnis; ein fehlgeschlagener Task enthält den Fehler, den Sie anzeigen oder protokollieren können. Ein erneuter Versuch einer fehlgeschlagenen Generierung erstellt einen neuen Task und kann eine neue Gebühr verursachen.

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

Polling-Beispiel

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

Die Status sind pending, processing, completed und failed. Ein abgebrochener Task verwendet failed zusammen mit cancelled: true und cancellation_status: "cancelled".

Eine erfolgreiche Statusabfrage gibt HTTP 200 zurück, auch wenn der Task fehlgeschlagen ist. Verwenden Sie den status des Tasks, um zu entscheiden, ob die Generierung erfolgreich war. Das error-Feld behält seine String- oder Objektform bei. Fehlgeschlagene Tasks können auch error_details mit status (der geschäftliche Fehlerstatus), type, code, message, param und retryable enthalten. Zum Beispiel bedeutet error_details.status: 400 mit param: "size", dass die Anfrage korrigiert werden muss; es bedeutet nicht, dass die Statusanfrage selbst fehlgeschlagen ist. param wird weggelassen, wenn kein spezifisches Feld bekannt ist. Wenn error_details.projection_version den Wert 2 hat, ist message der endgültige Grund für das Scheitern, normalerweise die eigene Erklärung des Upstream-Dienstes, wie z. B. ein Parameterlimit oder eine Entscheidung der Content-Richtlinie. Für einen Task, der auf einer Official-Route ausgeführt wurde, enthält error_details.upstream auch den gemeldeten Upstream-Fehler: message sowie code, param und source (der Name des Upstream-Dienstes), sofern bekannt. Verzweigen Sie weiterhin basierend auf code und type; upstream.code-Werte werden vom Upstream-Dienst definiert und können sich ändern.

Fehler, die die Erstellungsanfrage ablehnen, bevor ein Task akzeptiert wird, verwenden den normalen HTTP-Fehlerstatus und das strukturierte error-Objekt. Das Wiederholen derselben idempotenten Erstellungsanfrage bewahrt diese Ablehnung. Eine fehlgeschlagene Statusabfrage ändert den Terminal-Status des Tasks nicht.

Doppelte Tasks vermeiden

Die meisten doppelten Generierungen entstehen durch das Wiederholen einer Erstellungsanfrage nach einem Timeout.

Wo das Timeout auftrittSichereres Verhalten
Bevor Ihr Server eine Erstellungsantwort erhältSenden Sie dieselbe Anfrage erneut mit demselben Idempotency-Key, um den ursprünglichen Task zu erhalten. Ohne Key prüfen Sie die request_id und wiederholen Sie den Vorgang nur, wenn kein Task erstellt wurde
Nachdem eine Erstellungsantwort gespeichert wurdeSetzen Sie das Polling der gespeicherten task_id fort
Während des PollingsWiederholen Sie die Statusanfrage mit Backoff
Nach dem Terminal-StatusPollen Sie nicht erneut, es sei denn, der Benutzer aktualisiert den Datensatz explizit

Senden Sie keine zweite Erstellungsanfrage, nur weil der Browser aktualisiert wurde oder ein Status-Polling fehlgeschlagen ist.

Abrechnungsdatensätze

Ein asynchroner Task kann seine geschätzten Kosten reservieren, wenn er akzeptiert wird. Der endgültige Betrag wird aufgezeichnet, nachdem der Task abgeschlossen oder fehlgeschlagen ist. Statusantworten können billing_transaction_id und den Header X-Billing-Transaction-ID enthalten.

Bewahren Sie diese Identifikatoren zusammen auf:

  • request_id aus der Erstellungsanfrage.
  • task_id / id aus dem Task.
  • billing_transaction_id, falls vorhanden.
  • Ihre eigene Benutzer-ID, Projekt-ID oder Job-ID.

Abbruch

DELETE /v1/tasks/{id} kann unterstützte Seedance-Video-Tasks abbrechen, solange sie noch in der Warteschlange stehen, einschließlich seedance-2.0 und seedance-2.0-fast.

Nicht unterstützte Tasks geben 400 unsupported_task_cancel zurück. Ein Task, der bereits läuft oder abgeschlossen ist, gibt 409 task_not_cancellable zurück. Ein Abbruch ist eine Anfrage, keine Garantie, dass bereits laufende Arbeiten gestoppt werden. Ein erfolgreicher Abbruch gibt 200 mit status: "failed", cancelled: true und cancellation_status: "cancelled" zurück. Ein abgebrochener Task wird nicht berechnet.

Fehlerbehebung

SymptomWahrscheinliche UrsacheWas zu prüfen ist
404 async_task_not_foundDie Task-ID ist unbekannt, gehört zu einem anderen Workspace oder der abgeschlossene Task liegt außerhalb seines StatusfenstersPrüfen Sie die gespeicherte task_id und den Workspace des API-Keys
403 task_not_ownedDie Task-Inhaberschaft kann für den aktuellen Workspace nicht bestätigt werdenBestätigen Sie den Workspace oder die Organisation, die mit dem API-Key verknüpft ist
503 async_task_owner_unavailableDie Task-Inhaberschaft konnte derzeit nicht geprüft werden. retryable ist trueWiederholen Sie die Statusanfrage mit Backoff
Task scheint nie fertig zu werdenClient pollt weiterhin die falsche URL oder hat vor dem Terminal-Status gestopptPollen Sie GET /v1/tasks/{id} mit der gespeicherten Task-ID und prüfen Sie den neuesten Status
Endgültige Medien-URL fehltTask ist nicht abgeschlossen oder wurde ohne verwendbare Datei beendetPollen Sie weiter, bis er abgeschlossen ist, und behandeln Sie ein fehlendes Ergebnis dann als fehlgeschlagen
Benutzer sieht DuplikateWiederholungspfad hat nach Timeout oder Aktualisierung einen neuen Task erstelltDeduplizieren Sie anhand Ihrer eigenen Job-ID und der gespeicherten task_id
AbrechnungsdiskrepanzEndgültige Abrechnung ist noch nicht erfasst oder es werden falsche IDs verglichenVergleichen Sie request_id, task_id und billing_transaction_id

Was an den Support zu senden ist

Fügen Sie request_id, task_id, billing_transaction_id (falls vorhanden), Endpunkt, Modell, Uhrzeit und die Namen der gesendeten Felder bei. Senden Sie niemals API-Keys, private Medien, signierte URLs oder vollständige Prompts, es sei denn, der Support fragt ausdrücklich nach einem redigierten Beispiel.

API-Referenz

ThemaReferenz
Task-Status abrufenTask-Status abrufen
Task abbrechenTask abbrechen
BildgenerierungBildgenerierung
VideogenerierungVideogenerierung
MusikgenerierungMusikgenerierung
3D-Generierung3D-Generierung
Abrechnung & PreiseAbrechnung & Preise

Stoppen Sie das Polling von Terminal-Tasks und stoppen Sie bei 401, 403, 404 oder einem nicht wiederholbaren Fehler. Um Task-Ergebnisse ohne Polling zu erhalten, konfigurieren Sie die Webhook-Management-API mit einem mt-… Management Token.

Task-Antworten enthalten auch die Header X-Task-ID, X-Task-Type und X-Billing-Transaction-ID, die Sie neben der Task-ID protokollieren können.

Auf dieser Seite