Temel kılavuzlar
Asenkron İşler & Anket
Asenkron medya işleri oluşturun, genel TokenLab görev durumunu sorgulayın ve sağlayıcıya özgü kimlikler olmadan nihai sonuçları uzlaştırın.
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
modelile 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
completedveyafailedolduğunda durun. completeddurumunda, medya özel sonuç alanlarını okuyun ve nihai URL'leri veya meta verileri saklayın.faileddurumunda, 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} bilinçli olarak dar tutulmuştur. Seçilen görev iptali desteklediğinde seedance-1.5-pro, seedance-2.0 ve seedance-2.0-fast gibi kuyruktaki Seedance video görevleri için geçerlidir.
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 |
|---|---|---|
404 async_task_not_found | Görevin süresi dolmuş veya görev artık kullanılamıyor | Kaydedilen task_id ve poll_url değerlerini kontrol edin |
403 task_not_owned | Görevin mevcut çalışma alanına ait olduğu doğrulanamıyor | API anahtarına bağlı çalışma alanını veya kuruluşu kontrol edin |
| 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 |