Medya kılavuzları
Seedance'i Volcengine'den Taşıma
Volcengine istek formatınızı koruyun ve Seedance'i TokenLab'e geçirin
Uygulamanız halihazırda Volcengine Seedance API'sini kullanıyorsa, REST yollarını, content[] gövdesini, yanıt alanlarını, geri çağrıları (callbacks) ve PascalCase materyal Action'larını koruyabilirsiniz. API ana bilgisayarını (host) değiştirin ve AK/SK imzalama yöntemini bir TokenLab API anahtarı ile değiştirin.
Neler Değişiyor
| Değişiklik | Mevcut Volcengine istemcisi | TokenLab |
|---|---|---|
| Temel URL | Volcengine uç noktanız | https://api.tokenlab.sh/ |
| Kimlik Doğrulama | AK/SK istek imzalama | Authorization: Bearer <TOKENLAB_API_KEY> |
| Görev aktarımı | Resmi /api/v3/contents/generations/tasks REST yolları | Korundu |
| Materyal/doğrulama Action'ları | Action ve Version sorgu parametreleri | Korundu |
| Görev gövdesi | Volcengine tarzı content[] | Korundu |
| Materyal gövdesi | GroupId ve ProjectName gibi PascalCase alanlar | Korundu |
| Asenkron sonuç | Volcengine görev yaşam döngüsü | Yoklama (polling) ve isteğe bağlı geri çağrı ile TokenLab cgt-... görev kimliği |
Yalnızca AK/SK ile imzalanan istekler 401 AuthenticationError döndürür. Her TokenLab isteği Authorization: Bearer <TOKENLAB_API_KEY> içermelidir.
Bir uç nokta seçin
| Mevcut istemci | TokenLab uç noktası |
|---|---|
| Volcengine REST görev istemcisi | /api/v3/contents/generations/tasks ve görev yolları |
| Materyal veya doğrulama Action istemcisi | POST /?Action=...&Version=2024-01-01 veya POST /api/v3?Action=...&Version=2024-01-01 |
Video görevleri için mevcut REST yöntemini, yolunu ve JSON gövdesini koruyun. Materyal ve doğrulama istekleri, Action ve Version sorgu parametrelerini kullanmaya devam eder. Action uç noktası ayrıca CreateContentsGenerationsTasks, GetContentsGenerationsTask, ListContentsGenerationsTasks ve DeleteContentsGenerationsTasks görev Action'larını da kabul eder; yeni çalışmalar için REST yollarını kullanın.
Resmi Görev Yolları
| Yöntem ve yol | Amaç |
|---|---|
POST /api/v3/contents/generations/tasks | Bir video görevi oluşturun |
GET /api/v3/contents/generations/tasks/{id} | Bir görevi okuyun |
GET /api/v3/contents/generations/tasks | Görevleri listeleyin |
DELETE /api/v3/contents/generations/tasks/{id} | Kuyruktaki bir görevi iptal edin. Başlamış bir görev 409 task_not_cancellable döndürür |
REST istemcileri şu eşdeğer referansları kullanabilir:
- Görev Oluştur (Volc Uyumlu)
- Görevi Al (Volc Uyumlu)
- Görevleri Listele (Volc Uyumlu)
- Görevi İptal Et (Volc Uyumlu)
İstek Gövdesi Kuralları
content[];text,image_url,video_url,audio_urlvedraft_tasköğelerini kabul eder.image_urliçinrolekısmını boş bırakın veya görüntüden videoya (image-to-video) dönüştürme içinfirst_framekullanın. İlk kare ile birliktelast_frameveya referanstan videoya (reference-to-video) dönüştürme içinreference_imagekullanın.- Seçilen Seedance iş akışının ilgili medya rolünü kabul ettiği durumlarda
asset://asset-YYYYMMDDHHMMSS-xxxxxgibi genel bir materyal URI'si kullanılabilir. - REST gövdesi;
model,content,ratio,duration,resolution,generate_audio,watermark,return_last_frame,seed,execution_expires_aftervesafety_identifierdahil olmak üzere yalnızca resmi alanları kabul eder. Varsayılanlar modele bağlıdır:generate_audio,seedance-2.0modelleri içinfalse,seedance-2.5içintruedeğerindedir;durationiseseedance-2.0modelleri için5,seedance-2.5için-1değerindedir. Bu REST formatı480p,720pve1080p(seedance-2.5için480pve720p) çözünürlük değerlerini kabul eder, ancak yalnızca birleşik/v1/videos/generationsAPI'sinin kabul ettiği4kdeğerini kabul etmez.seedance-2.5,seed,framesvecamera_fixedparametrelerini reddeder. callback_url, genel bir HTTP(S) uç noktasını kabul eder. TokenLab;queued,running,succeeded,failedveexpireddurumları için aynı sorgu-görev gövdesini gönderir; yalnızcasucceededvefailedresmi davranışı izler: beş saniyelik bir zaman aşımı ve uç noktanız bildirimi onaylamadığında yeniden deneme.
Minimal REST Örneği
curl 'https://api.tokenlab.sh/api/v3/contents/generations/tasks' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Idempotency-Key: $CLIENT_JOB_ID" \
-H "Content-Type: application/json" \
-d '{
"model": "seedance-2.5",
"content": [
{"type":"text","text":"A cinematic product reveal"},
{"type":"image_url","role":"reference_image","image_url":{"url":"https://example.com/reference.png"}}
],
"ratio": "16:9",
"duration": 5,
"resolution": "720p"
}'Döndürülen cgt-... kimliğini saklayın. status değeri succeeded, failed, cancelled veya expired olana kadar yoklama yapın; oluşturma yanıtını tamamlanmış bir video olarak değerlendirmeyin. callback_url sağlarsanız, tekrarlanan succeeded veya failed bildirimlerine izin verin ve kurtarma yolu olarak yoklamaya devam edin.
v1 ve v3 Türlerini Ayrı Tutun
Bu uç nokta için /v1/tasks/{id} yanıt yapısını yeniden kullanmayın. Birleşik v1 API; pending, processing, completed ve failed durumlarını bildirirken, Volc uyumlu v3 API; queued, running, succeeded, failed, cancelled ve expired durumlarını bildirir. Resmi v3 yanıtı ayrıca duration değerini bir JSON dizgesi olarak temsil eder ve başarısız olmayan görevlerde error alanını atlar.
Oluşturma zaman aşımı veya bağlantı kesilmesinden sonra güvenli kurtarma için, REST oluşturma isteğine benzersiz bir Idempotency-Key ekleyin. Aynı gövdeyi aynı anahtarla yeniden denemek orijinal cgt-... kimliğini döndürür; farklı bir gövde ile aynı anahtar 409 döndürür.
Materyaller ve Gerçek Kişi Doğrulaması
Aynı Action uç noktası, 10 materyal ve materyal grubu işlemini de destekler. Tam PascalCase gövdeleri, filtreler, sayfalama, yanıt zarfı ve 12 saatlik materyal URL'leri için Materyal Action'ları (Volc Uyumlu) bölümüne bakın.
Gerçek kişi materyalleri, yüklemeden önce iki Action ekler:
İkinci Action, doğrulanmış GroupId değerini döndürür. Bu kimliği CreateAsset ile kullanın; bir istemci doğrudan bir LivenessFace grubu oluşturamaz.
Taşıma Kontrol Listesi
- API ana bilgisayarını
https://api.tokenlab.shile değiştirin. - AK/SK imzalama yöntemini bir TokenLab Bearer API anahtarı ile değiştirin.
- Resmi REST görev yöntemini, yolunu ve istek gövdesi büyük/küçük harf kullanımını koruyun; Action ve sürümü yalnızca materyal veya doğrulama işlemleri için tutun.
- İlgili materyal ve doğrulama isteklerinde aynı
ProjectNamedeğerini koruyun. - Bu uç noktalar tarafından döndürülen TokenLab görev, grup ve varlık (asset) kimliklerini saklayın.
- Üretim trafiğini taşımadan önce bir oluşturma, yoklama, listeleme ve hata yanıtını doğrulayın.