TokenLab Seedance-Task-Stornierung und Abrechnungsleitfaden für Jobs in der Warteschlange

Videogenerierungs-Tasks sind asynchron. Wenn Sie eine Videogenerierungsanfrage über POST /v1/videos/generations einreichen, gibt TokenLab eine Task-Kennung zurück und reiht den Job in die Warteschlange ein. Wenn eine Anfrage versehentlich eingereicht, bei einem Netzwerk-Retry dupliziert oder von einem Endbenutzer abgebrochen wird, verhindert das Stornieren des Tasks, während er sich noch in der Warteschlange befindet, unnötige Rechen- und Generierungskosten.

Dieser Leitfaden erklärt, wie Sie den Endpunkt zur Task-Stornierung aufrufen, API-Antwortcodes handhaben und Abrechnungsreservierungen sowie Polling-Übergänge verwalten.

Wie die Task-Stornierung funktioniert

Die Task-Stornierung zielt auf asynchrone Jobs ab, die sich noch im Zustand pending in der Warteschlange befinden. Sobald ein Modell-Worker mit der Generierung von Frames beginnt (wodurch der Task in den Zustand processing übergeht) oder der Task einen Endzustand erreicht (completed oder failed), kann keine Stornierung mehr stattfinden.

TokenLab unterstützt die Stornierung von in der Warteschlange befindlichen Seedance-Videomodellen, einschließlich seedance-2.0, seedance-2.0-fast und seedance-2.5. Informationen zu Integrationen, die den Volcengine-Kompatibilitätsendpunkt verwenden, finden Sie in der Referenz zur Volc-kompatiblen Task-Stornierung.

Task-Lebenszyklus-Zustände

• pending: Der Task befindet sich in der Warteschlange und wartet auf einen verfügbaren Worker. Die Stornierung wird in diesem Zeitfenster unterstützt.
• processing: Die Modellausführung hat begonnen. Stornierungsanfragen werden abgelehnt.
• completed: Die Videogenerierung wurde erfolgreich abgeschlossen. Das Ergebnis ist bereit.
• failed: Beim Task ist ein Fehler aufgetreten oder er wurde vor der Ausführung storniert.

Kosten- und Reservierungssemantik

Gemäß TokenLabs Abrechnungs- und Preisleitfaden folgt die Abrechnung für asynchrone Medien-Jobs einem zweiphasigen Reservierungs- und Abwicklungsmodell:

1. Vorautorisierung / Reservierung: Wenn ein asynchroner Video-Task akzeptiert wird, kann TokenLab einen geschätzten Betrag basierend auf dem ausgewählten Modell und den Parametern einbehalten oder reservieren.
2. Abwicklung: Die endgültige Gebühr wird erst abgerechnet, wenn der Task completed erreicht. Abgeschlossene Tasks enthalten eine billing_transaction_id, die den endgültigen Hauptbucheintrag darstellt.
3. Stornierung und Fehlschlag: Tasks, die im Zustand failed enden – einschließlich derjenigen, die in der Warteschlange storniert wurden –, werden nicht berechnet. Jede ungenutzte Reservierung oder vorübergehende Einbehaltung wird wieder für Ihr Workspace-Guthaben freigegeben.

Da ein in der Warteschlange stornierter Task die Generierung nie abschließt, erzeugt er keine vollendete Abrechnungsabwicklung.

Stornieren eines Tasks in der Warteschlange über die API

Um einen Task zu stornieren, senden Sie eine DELETE-Anfrage an /v1/tasks/{id} mit der bei der Erstellung zurückgegebenen Task-ID. Vollständige Schemadetails finden Sie in der API-Referenz zu Task stornieren.

Anfragebeispiel

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

Erfolgsantwort (HTTP 200)

Wenn ein Task vor Beginn der Ausführung erfolgreich storniert wird, antwortet die API mit HTTP 200. Der Task-Status wechselt direkt zu failed, gekennzeichnet mit cancelled: true:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "failed",
  "cancelled": true,
  "cancellation_status": "cancelled",
  "error": "Task cancelled before execution"
}

Fehlercodes und Ablehnungsbehandlung

Gehen Sie nicht davon aus, dass ein DELETE-Aufruf immer erfolgreich ist. Ihre Anwendung muss bestimmte HTTP-Fehlerstatus verarbeiten:

HTTP-Status	Fehlercode	Bedeutung	Empfohlene Maßnahme
400	unsupported_task_cancel	Das Modell oder der Task-Typ unterstützt keine Stornierung.	Lassen Sie den Task normal beenden oder prüfen Sie die Modellunterstützung.
403	task_not_owned	Der API-Schlüssel ist nicht Eigentümer des Tasks.	Überprüfen Sie die Workspace-Anmeldeinformationen und den Gültigkeitsbereich des API-Schlüssels.
404	async_task_not_found	Die Task-ID existiert nicht oder ist abgelaufen.	Bestätigen Sie die in Ihrer lokalen Warteschlangen-Datenbank gespeicherte Task-ID.
409	task_not_cancellable	Der Task hat bereits mit processing begonnen oder befindet sich in einem Endzustand (completed/failed).	Akzeptieren Sie, dass die Generierung bereits im Gange ist; wiederholen Sie den Löschaufruf nicht in einer Schleife.

Polling stornierter Tasks

Beachten Sie beim Abfragen eines Tasks über GET /v1/tasks/{id} oder die zurückgegebene poll_url (wie im Leitfaden für Asynchrone Jobs und Polling dokumentiert) die folgenden Verhaltensweisen:

1. HTTP 200 bei finalen Tasks: Das Auslesen des Status eines fehlgeschlagenen oder stornierten Tasks liefert HTTP 200 zurück. Überprüfen Sie die Felder status und cancelled des JSON-Bodys, anstatt sich auf HTTP-Antwortcodes zu verlassen.
2. Statusidentifikation: Ein stornierter Task zeigt "status": "failed", "cancelled": true und "cancellation_status": "cancelled" an.
3. Fehlen von Transaktions-IDs: Stornierte Tasks enthalten keine billing_transaction_id, da keine Abrechnungsabwicklung stattgefunden hat.

import time
import requests

def cancel_and_verify(task_id: str, api_key: str):
    url = f"https://api.tokenlab.sh/v1/tasks/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    # Attempt cancellation
    cancel_res = requests.delete(url, headers=headers)
    if cancel_res.status_code == 200:
        data = cancel_res.json()
        if data.get("cancelled"):
            print(f"Task {task_id} successfully cancelled.")
            return True
    elif cancel_res.status_code == 409:
        print(f"Task {task_id} already in progress or terminal; cannot cancel.")
    else:
        print(f"Cancellation rejected with HTTP {cancel_res.status_code}: {cancel_res.text}")

    # Poll task to determine terminal state
    poll_res = requests.get(url, headers=headers)
    if poll_res.ok:
        status_data = poll_res.json()
        print(f"Current status: {status_data.get('status')}, cancelled: {status_data.get('cancelled', False)}")
    return False

Checkliste für die Integration in Produktions-Warteschlangen

Befolgen Sie bei der Integration von Seedance-Video-Workflows in Worker-Architekturen diese Best Practices:

• IDs unverzüglich persistieren: Speichern Sie sowohl id (oder task_id) als auch poll_url aus der Antwort von POST /v1/videos/generations, bevor Sie nachgelagerte Arbeiten ausführen.
• Beim Einreichen deduplizieren: Verhindern Sie versehentliche Task-Generierungen, indem Sie clientseitige Doppelklicks und vorgelagerte Netzwerk-Retries deduplizieren, bevor Tasks erstellt werden.
• 409 als nicht-fatal behandeln: Wenn eine Stornierungsanfrage 409 task_not_cancellable zurückgibt, behandeln Sie dies als Hinweis darauf, dass die Verarbeitung begonnen hat. Warten Sie ersatzweise auf das Ergebnis und verwerfen Sie die Ausgabe, falls sie nicht mehr benötigt wird.
• Stornierungs-Marker parsen: Prüfen Sie in Ihrer Polling-Schleife sowohl status == "failed" als auch cancelled is True, um vom Benutzer initiierte Stornierungen von Infrastrukturfehlern zu unterscheiden.
• Abrechnung mittels Transaktions-IDs abgleichen: Speichern Sie billing_transaction_id nur dann, wenn sie bei abgeschlossenen Jobs vorhanden ist. Erwarten Sie keine Transaktions-IDs bei stornierten oder fehlgeschlagenen Tasks.

Weitere Integrationsmuster finden Sie im Videogenerierungs-Leitfaden und in der API-Referenz zu Videostatus abrufen.