Asenkron İşler & Anket

Birçok medya uç noktası asenkron olarak çalışır. Bir oluşturma isteği, çalışmayı başlatır ve genel bir TokenLab görev kimliği döndürür; uygulamanız, o görev terminal bir duruma ulaşana kadar sorgulama yapar. Müşteri iş akışlarını yukarı akış görev URL’leri, yönlendirme kimlikleri veya sağlayıcı geri çağırma davranışları etrafında inşa etmeyin.

Genel Görev Sözleşmesi

Oluşturma yanıtları şunları içerebilir:

Alan	Anlamı	Ne yapılmalı
`id`	Genel TokenLab görev kimliği	Kendi iş kaydınızla saklayın
`task_id`	Aynı genel görev kimliği için uyumluluk takma adı	Bunu `id` ile eşdeğer olarak değerlendirin
`status`	Mevcut genel görev durumu	Terminal değilse sorgulamaya başlayın
`poll_url`	Tercih edilen durum URL’si	Varsa bunu önce kullanın
`model`	Uç nokta tarafından talep edilen veya çözülen model	Destek ve faturalama uzlaştırması için saklayın

/v1/tasks/{id} genel asenkron medya işleri için kanonik sabit durum uç noktasıdır. Uyumluluk için medya özel durum yolları mevcut olabilir, ancak yeni entegrasyonlar poll_url veya /v1/tasks/{id}’yi tercih etmelidir.

Önerilen Akış

Kullanıcı isteğini doğrulayın ve açık bir model ile oluşturma çağrısını gönderin.
Kontrolü UI’ye geri vermeden önce id / task_id, poll_url, uç nokta, model, kullanıcı kimliği ve kendi iş kimliğinizi saklayın.
Uzun süreli medya görevleri için her 5-10s’de sorgulama yapın.
Görev completed veya failed olduğunda durun.
completed durumunda, medya özel sonuç alanlarını okuyun ve nihai URL’leri veya meta verileri saklayın.
failed durumunda, genel hatayı saklayın ve yalnızca yeni kullanıcıya görünür bir iş olarak yeniden denemeyi teklif edin.

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

Sorgulama Örneği

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

Beklenen genel durumlar pending, processing, completed ve failed’dir. İptal edilen görevler failed olarak cancelled: true ve cancellation_status: "cancelled" ile temsil edilir, böylece eski durum işleme devam eder.

İstemci Yeniden Deneme Kuralları

Ağ zaman aşımı, çoğaltılmış işlerin en yaygın kaynağıdır. Bu kuralı kullanın:

Zaman aşımı nerede gerçekleşiyor	Daha güvenli davranış
Sunucunuz bir oluşturma yanıtı alana kadar	`request_id` için sunucu günlüklerini kontrol edin; yalnızca görev oluşturulmadıysa yeniden deneyin
Bir oluşturma yanıtı saklandıktan sonra	Saklanan `task_id` ile sorgulamaya devam edin
Sorgulama sırasında	Geri alma ile durum isteğini yeniden deneyin
Terminal durumdan sonra	Kullanıcı açıkça kaydı yenilemedikçe tekrar sorgulamayın

Tarayıcı yenilendiği veya bir durum sorgulaması başarısız olduğu için ikinci bir oluşturma isteği göndermeyin.

Faturalama ve Uzlaştırma

Asenkron işler, oluşturma isteği kabul edildiğinde tahmini bir miktarı rezerve edebilir. Nihai uzlaştırma, terminal durumdan sonra gerçekleşir. Mevcut olduğunda, görev durumu yanıtları billing_transaction_id ve X-Billing-Transaction-ID başlığını açığa çıkarabilir. Uzlaştırma için, günlüklerinizde bu tanımlayıcıları birleştirin:

Oluşturma isteğinden request_id.
Görevden task_id / id.
Varsa billing_transaction_id.
Kendi kullanıcı kimliğiniz, proje kimliğiniz veya iş kimliğiniz.

İptal

DELETE /v1/tasks/{id} kasıtlı olarak dar tutulmuştur. Şu anda seedance-1.5-pro, seedance-2.0 ve seedance-2.0-fast gibi kuyrukta bekleyen Volcengine Seedance video görevlerini desteklemektedir. Desteklenmeyen görevler 400 unsupported_task_cancel döndürür. Zaten çalışan veya terminal olan görevler 409 task_not_cancellable döndürür. İptal UI’sini “iptal talebi” olarak oluşturun, garantili bir durdurma butonu olarak değil.

Sorun Giderme

Belirti	Muhtemel neden	Kontrol edilecekler
`async_task_not_found`	Görev bilinmiyor, süresi dolmuş, bu API anahtarına erişilemez veya genel bir asenkron görev değil	API anahtarı sahipliğini ve saklanan genel `task_id`’yi doğrulayın
Görev asla tamamlanmıyor gibi görünüyor	İstemci yanlış URL’yi sorgulamaya devam ediyor veya terminal durumdan önce durdu	`poll_url` veya `/v1/tasks/{id}` kullanın ve en son durumu kontrol edin
Nihai medya URL’si eksik	Görev tamamlanmamış veya yukarı akış işi kullanılabilir çıktı olmadan tamamlanmış	Terminal olana kadar sorgulamaya devam edin, ardından eksik çıktıyı başarısız olarak yönetin
Kullanıcı kopyaları görüyor	Yeniden deneme yolu zaman aşımından veya yenilemeden sonra yeni bir görev oluşturdu	Kendi iş kimliğiniz ve saklanan `task_id` ile çoğaltmayı önleyin
Faturalama uyuşmazlığı	Uzlaştırma asenkron veya istemci sağlayıcı kimliklerini karşılaştırıyor	`request_id`, `task_id` ve `billing_transaction_id`’yi karşılaştırın

Destek Paketi

Destekle iletişime geçerken, request_id, task_id, varsa billing_transaction_id, uç nokta, model, zaman damgası ve temizlenmiş bir istek şekli ekleyin. Destek, redakte edilmiş bir örnek istemedikçe API anahtarlarını, özel medyayı, imzalı URL’leri veya tam istemleri eklemeyin.

API Referansı

Konu	Referans
Görev Durumunu Al	Görev Durumunu Al
Görevi İptal Et	Görevi İptal Et
Görüntü Üretimi	Görüntü Üretimi
Video Üretimi	Video Üretimi
Müzik Üretimi	Müzik Üretimi
3D Üretimi	3D Üretimi
Faturalama & Fiyatlandırma	Faturalama & Fiyatlandırma

​Genel Görev Sözleşmesi

​Önerilen Akış

​Sorgulama Örneği

​İstemci Yeniden Deneme Kuralları

​Faturalama ve Uzlaştırma

​İptal

​Sorun Giderme

​Destek Paketi

​API Referansı