Panduan Pembatalan Tugas Seedance dan Penagihan Pekerjaan dalam Antrean TokenLab

Tugas pembuatan video bersifat asinkron. Saat Anda mengirimkan permintaan pembuatan video melalui POST /v1/videos/generations, TokenLab mengembalikan pengidentifikasi tugas dan memasukkan pekerjaan ke dalam antrean. Jika permintaan terkirim secara tidak sengaja, terduplikasi selama percobaan ulang jaringan, atau dibatalkan oleh pengguna akhir, membatalkan tugas saat masih berada dalam antrean akan mencegah biaya komputasi dan pembuatan yang tidak perlu.

Panduan ini menjelaskan cara memanggil endpoint pembatalan tugas, menangani kode respons API, serta mengelola reservasi penagihan dan transisi polling.

Cara Kerja Pembatalan Tugas

Pembatalan tugas menargetkan pekerjaan asinkron yang masih mengantre dalam status pending. Begitu worker model mulai membuat frame (mentransisikan tugas ke processing) atau tugas mencapai status akhir (completed atau failed), pembatalan tidak lagi dapat dilakukan.

TokenLab mendukung pembatalan pada model video Seedance yang sedang mengantre, termasuk seedance-2.0, seedance-2.0-fast, dan seedance-2.5. Untuk integrasi yang menggunakan endpoint kompatibilitas Volcengine, lihat referensi Pembatalan Tugas Kompatibel Volc.

Status Siklus Hidup Tugas

• pending: Tugas dimasukkan ke dalam antrean dan menunggu worker yang tersedia. Pembatalan didukung dalam rentang waktu ini.
• processing: Eksekusi model telah dimulai. Permintaan pembatalan akan ditolak.
• completed: Pembuatan video selesai dengan sukses. Hasilnya siap digunakan.
• failed: Tugas mengalami kesalahan atau dibatalkan sebelum dieksekusi.

Semantik Biaya dan Reservasi

Berdasarkan panduan Penagihan dan Penetapan Harga TokenLab, penagihan untuk pekerjaan media asinkron mengikuti model reservasi dan penyelesaian dua fase:

1. Pra-otorisasi / Reservasi: Ketika tugas video asinkron diterima, TokenLab dapat menahan atau mereservasi perkiraan jumlah biaya berdasarkan model dan parameter yang dipilih.
2. Penyelesaian: Biaya akhir hanya diselesaikan ketika tugas mencapai completed. Tugas yang selesai akan menyertakan billing_transaction_id yang mewakili entri buku besar final.
3. Pembatalan dan Kegagalan: Tugas yang berakhir dalam status failed—termasuk yang dibatalkan saat masih dalam antrean—tidak dikenakan biaya. Setiap reservasi atau penahanan dana sementara yang tidak terpakai akan dikembalikan ke saldo workspace Anda.

Karena tugas yang dibatalkan dalam antrean tidak pernah menyelesaikan proses pembuatan, tugas tersebut tidak menghasilkan penyelesaian penagihan yang selesai.

Membatalkan Tugas dalam Antrean melalui API

Untuk membatalkan tugas, kirimkan permintaan DELETE ke /v1/tasks/{id} dengan ID tugas yang dikembalikan saat pembuatan. Untuk detail skema lengkap, lihat referensi API Batalkan Tugas.

Contoh Permintaan

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

Respons Berhasil (HTTP 200)

Ketika tugas berhasil dibatalkan sebelum eksekusi dimulai, API merespons dengan HTTP 200. Status tugas langsung beralih ke failed, ditandai dengan 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"
}

Kode Kesalahan dan Penanganan Penolakan

Jangan berasumsi panggilan DELETE selalu berhasil. Aplikasi Anda harus menangani status kesalahan HTTP tertentu:

Status HTTP	Kode Kesalahan	Arti	Tindakan yang Disarankan
400	unsupported_task_cancel	Model atau jenis tugas tidak mendukung pembatalan.	Biarkan tugas selesai seperti biasa atau tinjau dukungan model.
403	task_not_owned	API key bukan pemilik tugas tersebut.	Verifikasi kredensial workspace dan cakupan API key.
404	async_task_not_found	ID tugas tidak ada atau telah kedaluwarsa.	Konfirmasikan ID tugas yang disimpan di database antrean lokal Anda.
409	task_not_cancellable	Tugas sudah mulai masuk tahap processing atau berada dalam status akhir (completed/failed).	Terima bahwa pembuatan sudah berlangsung; jangan mencoba ulang panggilan penghapusan secara berulang.

Melakukan Polling pada Tugas yang Dibatalkan

Saat melakukan polling tugas melalui GET /v1/tasks/{id} atau poll_url yang dikembalikan (sebagaimana didokumentasikan dalam panduan Pekerjaan Asinkron dan Polling), perhatikan perilaku berikut:

1. HTTP 200 pada Tugas Status Akhir: Membaca status tugas yang gagal atau dibatalkan akan mengembalikan HTTP 200. Periksa bidang status dan cancelled pada body JSON alih-alih mengandalkan kode respons HTTP.
2. Identifikasi Status: Tugas yang dibatalkan menampilkan "status": "failed", "cancelled": true, dan "cancellation_status": "cancelled".
3. Ketiadaan ID Penyelesaian: Tugas yang dibatalkan tidak akan memuat billing_transaction_id karena tidak ada penyelesaian biaya yang terjadi.

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

Checklist Integrasi Antrean Produksi

Saat mengintegrasikan alur kerja video Seedance ke dalam arsitektur worker, ikuti praktik terbaik berikut:

• Simpan ID Segera: Simpan id (atau task_id) dan poll_url dari respons POST /v1/videos/generations sebelum mengirimkan pekerjaan ke sistem hilir.
• Deduplikasi saat Pengiriman: Cegah pembuatan tugas yang tidak disengaja dengan melakukan deduplikasi klik ganda di sisi klien dan percobaan ulang jaringan hulu sebelum membuat tugas.
• Tangani 409 sebagai Non-Fatal: Jika permintaan pembatalan mengembalikan 409 task_not_cancellable, anggap itu sebagai indikasi bahwa pemrosesan telah dimulai. Beralihlah ke menunggu hasil dan membuang output jika tidak lagi diperlukan.
• Urai Penanda Pembatalan: Dalam loop polling Anda, periksa status == "failed" dan cancelled is True untuk membedakan pembatalan yang diinisiasi pengguna dari kesalahan infrastruktur.
• Rekonsiliasi Penagihan Menggunakan ID Transaksi: Simpan billing_transaction_id hanya jika ada pada pekerjaan yang selesai. Jangan mengharapkan ID transaksi pada tugas yang dibatalkan atau gagal.

Untuk pola integrasi tambahan, tinjau Panduan Pembuatan Video dan Referensi API Dapatkan Status Video.