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:
| Feld | Bedeutung | Was zu tun ist |
|---|---|---|
id | TokenLab Task-ID | Speichern Sie diese mit Ihrem eigenen Job-Datensatz |
task_id | Ein anderer Name für dieselbe Task-ID | Behandeln Sie diese als äquivalent zu id |
status | Aktueller Task-Status | Prüfen Sie weiter, bis der Task abgeschlossen oder fehlgeschlagen ist |
poll_url | Status-URL für den Task | Speichern Sie diese; pollen Sie /v1/tasks/{id} mit der Task-ID |
model | Für den Task verwendetes Modell | Speichern 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 auftritt | Sichereres Verhalten |
|---|---|
| Bevor Ihr Server eine Erstellungsantwort erhält | Senden 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 wurde | Setzen Sie das Polling der gespeicherten task_id fort |
| Während des Pollings | Wiederholen Sie die Statusanfrage mit Backoff |
| Nach dem Terminal-Status | Pollen 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_idaus der Erstellungsanfrage.task_id/idaus 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
| Symptom | Wahrscheinliche Ursache | Was zu prüfen ist |
|---|---|---|
404 async_task_not_found | Die Task-ID ist unbekannt, gehört zu einem anderen Workspace oder der abgeschlossene Task liegt außerhalb seines Statusfensters | Prüfen Sie die gespeicherte task_id und den Workspace des API-Keys |
403 task_not_owned | Die Task-Inhaberschaft kann für den aktuellen Workspace nicht bestätigt werden | Bestätigen Sie den Workspace oder die Organisation, die mit dem API-Key verknüpft ist |
503 async_task_owner_unavailable | Die Task-Inhaberschaft konnte derzeit nicht geprüft werden. retryable ist true | Wiederholen Sie die Statusanfrage mit Backoff |
| Task scheint nie fertig zu werden | Client pollt weiterhin die falsche URL oder hat vor dem Terminal-Status gestoppt | Pollen Sie GET /v1/tasks/{id} mit der gespeicherten Task-ID und prüfen Sie den neuesten Status |
| Endgültige Medien-URL fehlt | Task ist nicht abgeschlossen oder wurde ohne verwendbare Datei beendet | Pollen Sie weiter, bis er abgeschlossen ist, und behandeln Sie ein fehlendes Ergebnis dann als fehlgeschlagen |
| Benutzer sieht Duplikate | Wiederholungspfad hat nach Timeout oder Aktualisierung einen neuen Task erstellt | Deduplizieren Sie anhand Ihrer eigenen Job-ID und der gespeicherten task_id |
| Abrechnungsdiskrepanz | Endgültige Abrechnung ist noch nicht erfasst oder es werden falsche IDs verglichen | Vergleichen 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
| Thema | Referenz |
|---|---|
| Task-Status abrufen | Task-Status abrufen |
| Task abbrechen | Task abbrechen |
| Bildgenerierung | Bildgenerierung |
| Videogenerierung | Videogenerierung |
| Musikgenerierung | Musikgenerierung |
| 3D-Generierung | 3D-Generierung |
| Abrechnung & Preise | Abrechnung & 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.