TokenLab Seedance Görev İptali ve Kuyruktaki İşlerin Faturalandırılması Rehberi

Video üretimi görevleri asenkrondur. POST /v1/videos/generations aracılığıyla bir video üretim isteği gönderdiğinizde, TokenLab bir görev tanımlayıcısı döndürür ve işi kuyruğa alır. Bir istek yanlışlıkla gönderilirse, bir ağ yeniden denemesi sırasında yinelenirse veya son kullanıcı tarafından terk edilirse, görev kuyrukta beklerken iptal edilmesi gereksiz bilgi işlem ve üretim ücretlerini önler.

Bu rehber; görev iptal uç noktasının nasıl çağrılacağını, API yanıt kodlarının nasıl ele alınacağını, faturalandırma rezervasyonlarının ve sorgulama (polling) geçişlerinin nasıl yönetileceğini açıklar.

Görev İptali Nasıl Çalışır

Görev iptali, hâlâ pending durumunda kuyrukta bekleyen asenkron işleri hedefler. Bir model çalışanı (worker) kare üretmeye başladığında (görevi processing durumuna geçirerek) veya görev son bir duruma (completed veya failed) ulaştığında artık iptal işlemi gerçekleştirilemez.

TokenLab; seedance-2.0, seedance-2.0-fast ve seedance-2.5 dahil olmak üzere kuyruktaki Seedance video modellerinde iptal işlemini destekler. Volcengine uyumluluk uç noktasını kullanan entegrasyonlar için Volc Uyumlu Görev İptali referansı sayfasına bakın.

Görev Yaşam Döngüsü Durumları

• pending: Görev kuyruğa alınmıştır ve uygun bir çalışan beklemektedir. Bu aralıkta iptal işlemi desteklenir.
• processing: Model yürütmesi başlamıştır. İptal istekleri reddedilecektir.
• completed: Video üretimi başarıyla tamamlanmıştır. Sonuç hazırdır.
• failed: Görev bir hatayla karşılaşmıştır veya yürütülmeden önce iptal edilmiştir.

Ücretlendirme ve Rezervasyon Anlambilimi

TokenLab'in Faturalandırma ve Fiyatlandırma rehberi uyarınca, asenkron medya işlerinin faturalandırılması iki aşamalı bir rezervasyon ve mutabakat modelini izler:

1. Ön Yetkilendirme / Rezervasyon: Asenkron bir video görevi kabul edildiğinde TokenLab, seçilen modele ve parametrelere göre tahmini bir tutarı bloke edebilir veya rezerve edebilir.
2. Mutabakat (Settlement): Nihai ücret yalnızca görev completed durumuna ulaştığında tahsil edilir. Tamamlanan görevler, nihai defter kaydını temsil eden bir billing_transaction_id içerir.
3. İptal ve Başarısızlık: Kuyrukta beklerken iptal edilenler de dahil olmak üzere failed durumunda sonlanan görevler ücretlendirilmez. Kullanılmayan tüm rezervasyonlar veya geçici blokajlar çalışma alanı bakiyenize iade edilir.

Kuyrukta iptal edilen bir görev üretimi hiçbir zaman tamamlamadığı için, tamamlanmış bir fatura mutabakatı oluşturmaz.

Kuyruktaki Bir Görevi API Aracılığıyla İptal Etme

Bir görevi iptal etmek için, oluşturma sırasında döndürülen görev kimliğiyle /v1/tasks/{id} uç noktasına bir DELETE isteği gönderin. Eksiksiz şema ayrıntıları için Görev İptali API referansı belgesine bakın.

İstek Örneği

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

Başarılı Yanıt (HTTP 200)

Bir görev yürütme başlamadan önce başarıyla iptal edildiğinde API, HTTP 200 ile yanıt verir. Görev durumu doğrudan cancelled: true olarak işaretlenmiş şekilde failed durumuna geçer:

{
  "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"
}

Hata Kodları ve Reddedilme Yönetimi

Bir DELETE çağrısının her zaman başarılı olacağını varsaymayın. Uygulamanız belirli HTTP hata durumlarını ele almalıdır:

HTTP Durumu	Hata Kodu	Anlamı	Önerilen Eylem
400	unsupported_task_cancel	Model veya görev türü iptal işlemini desteklemiyor.	Görevin normal şekilde tamamlanmasına izin verin veya model desteğini inceleyin.
403	task_not_owned	API anahtarı bu görevin sahibi değil.	Çalışma alanı kimlik bilgilerini ve API anahtarı kapsamını doğrulayın.
404	async_task_not_found	Görev kimliği mevcut değil veya süresi dolmuş.	Yerel kuyruk veritabanınızda depolanan görev kimliğini teyit edin.
409	task_not_cancellable	Görev zaten processing aşamasına geçmiş veya son bir durumda (completed/failed).	Üretimin çoktan başladığını kabul edin; silme çağrısını bir döngü içinde yeniden denemeyin.

İptal Edilen Görevleri Sorgulama (Polling)

GET /v1/tasks/{id} veya döndürülen poll_url aracılığıyla bir görevi sorgularken (Asenkron İşler ve Sorgulama rehberinde belgelendiği gibi), aşağıdaki davranışları aklınızda bulundurun:

1. Son Durumdaki Görevlerde HTTP 200: Başarısız veya iptal edilmiş bir görevin durumunu okumak HTTP 200 döndürür. HTTP yanıt kodlarına güvenmek yerine JSON gövdesindeki status ve cancelled alanlarını inceleyin.
2. Durum Tespiti: İptal edilen bir görev "status": "failed", "cancelled": true ve "cancellation_status": "cancelled" değerlerini görüntüler.
3. Mutabakat Kimliklerinin Bulunmaması: Herhangi bir ücret mutabakatı gerçekleşmediğinden, iptal edilen görevler bir billing_transaction_id içermez.

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

Prodüksiyon Kuyruk Entegrasyonu Kontrol Listesi

Seedance video iş akışlarını çalışan (worker) mimarilerine entegre ederken bu en iyi uygulamaları takip edin:

• Kimlikleri Anında Kaydedin: Aşağı yönlü işleri dağıtmadan önce POST /v1/videos/generations yanıtındaki hem id (veya task_id) hem de poll_url değerlerini saklayın.
• Gönderim Sırasında Tekilleştirin: Görevleri oluşturmadan önce istemci tarafındaki çift tıklamaları ve yukarı yönlü ağ yeniden denemelerini tekilleştirerek yanlışlıkla görev oluşturulmasını önleyin.
• 409 Yanıtını Kritik Olmayan Olarak Ele Alın: Bir iptal isteği 409 task_not_cancellable döndürürse, bunu işlemenin başladığının bir işareti olarak kabul edin. Sonucu beklemeye ve artık gerekmiyorsa çıktıyı göz ardı etmeye geri dönün.
• İptal İşaretçisini Ayrıştırın: Kullanıcı kaynaklı iptalleri altyapı hatalarından ayırt etmek için sorgulama döngünüzde hem status == "failed" hem de cancelled is True durumunu kontrol edin.
• İşlem Kimliklerini Kullanarak Faturalandırmayı Karşılaştırın: billing_transaction_id değerini yalnızca tamamlanan işlerde mevcut olduğunda saklayın. İptal edilmiş veya başarısız olmuş görevlerde işlem kimlikleri beklemeyin.

Ek entegrasyon modelleri için Video Üretim Rehberi ve Video Durumunu Alma API Referansı sayfalarını inceleyin.