Temel kılavuzlar

Asenkron işler ve sorgulama (polling)

Medya görevleri oluşturun ve tamamlanmış sonucu bekleyin

Birçok medya uç noktası, tamamlanmış bir dosya yerine bir görev döndürür. Döndürülen görev kimliğini (task ID) kaydedin ve durum completed (tamamlandı) veya failed (başarısız) olana kadar GET /v1/tasks/{id} uç noktasını sorgulayın. Bu tek uç nokta; görsel, video, müzik, 3D, Worlds ve asenkron ses transkripsiyonu görevleri için hizmet verir.

Asenkron terminal görev anlık görüntüleri, 30 günlük istek/yanıt yakalama penceresinden ayrı bir yaşam döngüsüne sahiptir. Oluşturulan görsel, video, ses, 3D ve Worlds dosya URL'leri, 30 gün boyunca geçerli kalan TokenLab medya sonucu URL'leridir. Tamamlanmış görevlerin durum okumaları yaklaşık 7 gün boyunca çalışır, bu nedenle görev tamamlanır tamamlanmaz sonucu kaydedin. Yanıtın media_retention alanları, her öğenin kaydetme durumunu ve expires_at (son kullanma tarihi) bilgisini bildirir; kaydetme durumu zamanında bilinmediğinde bu alanlar eksik olabilir ancak URL yine de çalışır. Başarısız olan ve devam eden görevler boş medya URL alanları döndürür. Bkz. Veri saklama.

Kaydedilecek alanlar

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

AlanAnlamıNe yapmalı
idTokenLab görev kimliğiKendi iş kaydınızla birlikte saklayın
task_idAynı görev kimliği için başka bir isimid ile eşdeğer kabul edin
statusMevcut görev durumuTamamlanana veya başarısız olana kadar kontrol etmeye devam edin
poll_urlGörev için durum URL'siSaklayın; görev kimliği ile /v1/tasks/{id} adresini sorgulayın
modelGörev için kullanılan modelGörev kaydıyla birlikte saklayın

Tek durum uç noktası

Oluşturma yanıtındaki id veya task_id ile GET /v1/tasks/{id} adresini sorgulayın. Bu, her görev türü için çalışır. Çoğu görev için poll_url aynı yoldur. Bir Worlds oluşturma yanıtı, /v1/worlds/generations/{id} altında bir poll_url döndürür; Worlds için de görev id'si ile /v1/tasks/{id} adresini sorgulayın.

/v1/videos/generations/{id} gibi modalite bazlı durum yolları, mevcut entegrasyonlar için desteklenmeye devam eder. Yeni entegrasyonlar /v1/tasks/{id} kullanmalıdır.

Görevi kaydedin ve durumunu kontrol edin

Oluşturma isteği başarılı olur olmaz id veya task_id değerini kaydedin. Bununla birlikte poll_url, model, uç nokta ve kendi kullanıcı veya iş kimliğinizi saklayın. Uzun süren medya işleri için genellikle 5–10 saniyede bir kontrol etmek yeterlidir.

Durum completed veya failed olduğunda durun. Tamamlanmış bir görev medya sonucunu içerir; başarısız bir görev ise gösterebileceğiniz veya günlüğe kaydedebileceğiniz hatayı içerir. Başarısız bir üretimi yeniden denemek yeni bir görev oluşturur ve yeni bir ücretlendirmeye neden olabilir.

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

Sorgulama (Polling) Örneği

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

Durumlar pending, processing, completed ve failed şeklindedir. İptal edilen bir görev, cancelled: true ve cancellation_status: "cancelled" ile birlikte failed durumunu kullanır.

Başarılı bir durum okuması, görev başarısız olsa bile HTTP 200 döndürür. Üretimin başarılı olup olmadığına karar vermek için görevin status alanını kullanın. error alanı, dize veya nesne şeklini korur. Başarısız görevler ayrıca status (iş hatası durumu), type, code, message, param ve retryable içeren error_details alanını da içerebilir. Örneğin, param: "size" ile error_details.status: 400, isteğin düzeltilmesi gerektiği anlamına gelir; durum isteğinin kendisinin başarısız olduğu anlamına gelmez. Belirli bir alan bilinmediğinde param atlanır. error_details.projection_version değeri 2 olduğunda, message hatanın nihai nedenidir; genellikle parametre sınırı veya içerik politikası kararı gibi yukarı akış hizmetinin kendi açıklamasıdır. Official rotasında çalışan bir görev için error_details.upstream, bildirildiği şekliyle yukarı akış hatasını da taşır: message ve bilindiğinde code, param ve source (yukarı akış hizmet adı). code ve type üzerinden dallanmaya devam edin; upstream.code değerleri yukarı akış hizmeti tarafından tanımlanır ve değişebilir.

Bir görev kabul edilmeden önce oluşturma isteğini reddeden hatalar, normal HTTP hata durumunu ve yapılandırılmış error nesnesini kullanır. Aynı idempotent oluşturma isteğini tekrarlamak bu reddi korur. Başarısız bir durum okuması, görevin terminal durumunu değiştirmez.

Yinelenen görevlerden kaçının

Çoğu yinelenen üretim, zaman aşımından sonra bir oluşturma isteğinin yeniden denenmesinden kaynaklanır.

Zaman aşımının gerçekleştiği yerDaha güvenli davranış
Sunucunuz oluşturma yanıtını almadan önceOrijinal görevi almak için aynı Idempotency-Key ile isteği tekrar gönderin. Anahtar yoksa, request_id değerini kontrol edin ve yalnızca hiçbir görev oluşturulmadıysa yeniden deneyin
Oluşturma yanıtı kaydedildikten sonraKaydedilen task_id değerini sorgulamaya devam edin
Sorgulama sırasındaDurum isteğini backoff (bekleme süresi artırarak) ile yeniden deneyin
Terminal durumundan sonraKullanıcı kaydı açıkça yenilemediği sürece tekrar sorgulamayın

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

Faturalandırma kayıtları

Asenkron bir görev, kabul edildiğinde tahmini maliyetini rezerve edebilir. Nihai tutar, görev tamamlandıktan veya başarısız olduktan sonra kaydedilir. Durum yanıtları billing_transaction_id ve X-Billing-Transaction-ID başlığını içerebilir.

Bu tanımlayıcıları bir arada tutun:

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

İptal

DELETE /v1/tasks/{id}, desteklenen Seedance video görevlerini, seedance-2.0 ve seedance-2.0-fast dahil olmak üzere, kuyrukta oldukları sürece iptal edebilir.

Desteklenmeyen görevler 400 unsupported_task_cancel döndürür. Zaten çalışmakta olan veya tamamlanmış bir görev 409 task_not_cancellable döndürür. İptal bir istektir, devam eden işin duracağının garantisi değildir. Başarılı bir iptal, status: "failed", cancelled: true ve cancellation_status: "cancelled" ile 200 döndürür. İptal edilen bir görev için ücret alınmaz.

Sorun giderme

BelirtiOlası nedenKontrol edilecekler
404 async_task_not_foundGörev kimliği bilinmiyor, başka bir çalışma alanına ait veya tamamlanmış görev durum penceresini geçmişKaydedilen task_id değerini ve API anahtarının çalışma alanını kontrol edin
403 task_not_ownedMevcut çalışma alanı için görev sahipliği doğrulanamıyorAPI anahtarıyla ilişkili çalışma alanını veya organizasyonu doğrulayın
503 async_task_owner_unavailableGörev sahipliği şu anda kontrol edilemedi. retryable değeri trueDurum isteğini backoff ile yeniden deneyin
Görev asla tamamlanmıyor gibi görünüyorİstemci yanlış URL'yi sorgulamaya devam ediyor veya terminal durumundan önce durduKaydedilen görev kimliği ile GET /v1/tasks/{id} adresini sorgulayın ve en son durumu inceleyin
Nihai medya URL'si eksikGörev tamamlanmadı veya kullanılabilir bir dosya olmadan bittiTamamlanana kadar sorgulamaya devam edin, ardından eksik sonucu başarısız olarak kabul edin
Kullanıcı yinelenenler görüyorYeniden deneme yolu, zaman aşımı veya yenilemeden sonra yeni bir görev oluşturduKendi iş kimliğiniz ve saklanan task_id ile tekilleştirin
Faturalandırma uyuşmazlığıNihai faturalandırma henüz kaydedilmedi veya yanlış kimlikler karşılaştırılıyorrequest_id, task_id ve billing_transaction_id değerlerini karşılaştırın

Destek ekibine ne gönderilmeli

Mevcut olduğunda request_id, task_id, billing_transaction_id, uç nokta, model, zaman ve gönderdiğiniz alanların isimlerini ekleyin. Destek ekibi özellikle düzenlenmiş bir örnek istemedikçe asla API anahtarları, özel medya, imzalı URL'ler veya tam istemler (prompts) göndermeyin.

API Referansı

KonuReferans
Görev Durumunu AlGörev Durumunu Al
Görevi İptal EtGörevi İptal Et
Görsel ÜretimiGörsel Üretimi
Video ÜretimiVideo Üretimi
Müzik ÜretimiMüzik Üretimi
3D Üretimi3D Üretimi
Faturalandırma ve FiyatlandırmaFaturalandırma ve Fiyatlandırma

Terminal görevlerini sorgulamayı bırakın ve 401, 403, 404 veya yeniden denenemez bir hatada durun. Görev sonuçlarını sorgulama yapmadan almak için, bir mt-… Yönetim Token'ı ile Webhook yönetimi API yapılandırmasını kullanın.

Görev yanıtları ayrıca, görev kimliğinin yanında günlüğe kaydedebileceğiniz X-Task-ID, X-Task-Type ve X-Billing-Transaction-ID başlıklarını da taşır.

Bu sayfada