Medya kılavuzları
Seedance Materyalleri ve Gerçek Kişi Doğrulaması
Seedance içinde görsel, video, ses veya doğrulanmış bir kişiyi yeniden kullanın
Seedance materyalleri, her üretim için ayrı ayrı içe aktarmak zorunda kalmadan bir görsel, video veya ses dosyasını yeniden kullanmanıza olanak tanır. Gerçek bir kişiye yapılan referanslar onay ve görsel doğrulama gerektirir; sanal kişiler, ürünler ve stiller için bu gerekli değildir.
Bir materyal türü seçin
| Yeniden kullanmak istediğiniz | Ne yapmalı |
|---|---|
| Bir kez kullanılan tek bir görsel | Desteklenen bir görsel alanında URL'sini gönderin; bu, yeniden kullanılabilir bir materyal ID'si oluşturmaz |
| Sanal bir kişiyi, ürünü veya stili yeniden kullanma | Bir aigc_avatar grubu oluşturun, bir varlık (asset) oluşturun, ACTIVE durumuna gelmesini bekleyin ve ardından varlık ID'sini kullanın |
| Gerçek bir kişiyi yeniden kullanma | Görsel doğrulamayı tamamlayın, GroupId değerini alın, bu grupta bir varlık oluşturun, ACTIVE durumuna gelmesini bekleyin ve ardından varlık ID'sini kullanın |
| Mevcut bir Volcengine materyal istemcisini taşıma | Action istek yapısını koruyun ve Volc uyumlu materyal referansını kullanın |
Gruplar ve materyaller
| Öğe | REST alanı | Action alanı | Anlamı |
|---|---|---|---|
| Materyal grubu | group_id | GroupId | İlgili materyalleri bir arada tutar |
| Materyal | id | Id | İçe aktarılan tek bir görsel, video veya ses dosyası; aktif hale geldikten sonra bu ID'yi kullanın |
| Sanal avatar grubu | library_type: "aigc_avatar" | GroupType: "AIGC" | Gerçek kişi doğrulaması gerektirmez |
| Gerçek kişi grubu | library_type: "liveness_face" | GroupType: "LivenessFace" | Yalnızca başarılı bir görsel doğrulama akışıyla oluşturulur |
| Proje adı | project_name | ProjectName | Farklı projelerdeki materyalleri ayrı tutar; varsayılan olarak default değerini alır |
Grup ID'leri ile varlık ID'lerini ayrı tutun. Bir grup, yüklemeleri düzenler; varlık ID'si ise video üretimi tarafından kullanılan referanstır. Genel ID'ler group-20260720123456-vrt01 ve asset-20260720123457-def45 gibi görünür.
Materyal Saklama
TokenLab, siz varlığı veya grubunu silene kadar her materyal varlığını saklar. Hareketsizlik nedeniyle temizlenmez.
- Bir varlığın kullanıldığında tekrar hazırlanması gerekiyorsa, ilk üretim biraz daha uzun sürebilir. Henüz hazır değilse, istek
409 seedance_material_preparinghatası döndürür; kısa süre sonra tekrar deneyin. - Bir varlığı veya grubu silmek kalıcıdır ve geri alınamaz.
Görsel URL'leri ve yeniden kullanılabilir materyaller
Seçtiğiniz model tarafından kabul edilen görsel alanlarında herkese açık HTTP(S) URL'lerini veya desteklenen veri URL'lerini gönderin. Bu girdiler normal medya yolunu izler ve otomatik olarak yeniden kullanılabilir materyal ID'leri oluşturmaz.
Yeniden kullanılabilir materyaller için, materyal API'si aracılığıyla bir varlık oluşturun, ACTIVE durumuna gelmesini bekleyin ve ardından desteklenen bir medya alanında material_asset_id, material_asset_ids veya asset://<id> kullanın. Hedeflenen ilk kare, son kare veya referans görseli rolünü koruyun.
Belirli bir materyal henüz hazırlanıyorsa, POST /v1/videos/generations isteği inactive_asset_ids ile birlikte 409 seedance_material_preparing hatası döndürür. Bu varlıkları ACTIVE olana kadar sorgulayın, ardından aynı materyal ID'leri ile tekrar deneyin. Bir varlık FAILED durumundaysa, error_message kısmını inceleyin ve tekrar denemeden önce düzeltin veya yeniden içe aktarın. Başarısız bir varlığı kullanan bir üretim isteği, failed_asset_ids ile birlikte 422 seedance_material_failed hatası döndürür.
Sanal Avatar Materyalleri
Bir aigc_avatar grubu oluşturmak için Materyal Varlık Grubu Oluştur komutunu kullanın. REST varlık oluşturma işleminde, group_id yalnızca project_name değeri default olduğunda isteğe bağlıdır; TokenLab bu durumda organizasyonun varsayılan sanal avatar grubunu kullanır veya oluşturur. default olmayan bir project_name ve tüm gerçek kişi varlıkları için group_id zorunludur.
Bir grup oluşturulduktan sonra şu komutlarla yönetebilirsiniz:
- Materyal Varlık Gruplarını Listele
- Materyal Varlık Grubunu Al
- Materyal Varlık Grubunu Güncelle
- Materyal Varlık Grubunu Sil
Bir grubu silmek, içerdiği TokenLab materyallerini de siler ve bu işlem geri alınamaz.
Gerçek Kişi Doğrulaması
Ürününüzün, gerçek bir kişiyi Seedance referansı olarak yeniden kullanmadan önce onay alması ve yüz doğrulaması yapması gerektiğinde bu akışı kullanın.
CallbackURLile Görsel Doğrulama Oturumu Oluştur komutunu çağırın;Result.BytedTokendeğerini kaydedin ve doğrulanan kişi içinResult.H5Linkbağlantısını açın.- H5 akışı geri çağırmaya (callback) yönlendirdikten sonra, aynı
BytedTokenveProjectNameile Görsel Doğrulama Sonucunu Al komutunu sorgulayın. - Dönen
Result.GroupIddeğerini saklayın. TokenLab, bu adım sırasındaLivenessFacegrubunu oluşturur ve bağlar. - Bu grup ID'si ile bir varlık oluşturun, ardından varlık
ACTIVEolana kadar sorgulayın.
BytedToken 30 dakika boyunca geçerlidir. Bir istemci, CreateAssetGroup ile LivenessFace grubu oluşturamaz; bu, doğrulanmamış bir grubun doğrulanmış gibi sunulmasını engeller.
Dönen H5Link bağlantısını oluşturulduktan hemen sonra açın. Token geçerliliği, doğrulama sayfasının bu süre zarfında herhangi bir noktada ilk kez açılabileceği anlamına gelmez.
Gerçek kişi grubu için yüklemeler, doğrulanmış yüz ile karşılaştırılarak kontrol edilir. Bir varlık, birden fazla yüz içeriyorsa veya yüz eşleşmiyorsa başarısız olabilir. En iyi sonuçlar için, tam vücut önden bir referans ve net, önden çekilmiş bir yakın plan yükleyin.
Bir Varlık Oluşturun ve Hazırlayın
Her seferinde herkese açık erişilebilir tek bir URL içe aktarmak için Materyal Varlığı Oluştur komutunu kullanın.
| Tür | Desteklenen girdi |
|---|---|
| Görsel | jpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; genişlik ve yükseklik [300, 6000] px; en-boy oranı [0.4, 2.5] |
| Video | mp4, mov; ≤ 200 MiB |
| Ses | aac, wav, mp3; ≤ 15 MiB |
Bunlar dosya içe aktarma limitleridir. Başarılı bir içe aktarma isteği, medya veya gerçek kişi doğrulamasının geçeceğini garanti etmez. ACTIVE durumunu bekleyin; varlık FAILED durumuna düşerse, tekrar içe aktarmadan önce kaynağı düzeltmek için error_message kısmını kullanın.
Materyal alımı asenkrondur. status değeri ACTIVE olana kadar Materyal Varlığını Al komutunu sorgulayın. HTTP başarısı, içe aktarmanın kabul edildiği anlamına gelir, varlığın hazır olduğu anlamına gelmez. Varlık FAILED durumuna düşerse, error_message kısmını inceleyin, kaynağı düzeltin ve yeni bir varlık oluşturun.
Kaynak URL yalnızca içe aktarma için kullanılır. TokenLab kendi varlık ID'sini döndürür ve siz varlığı veya grubunu silene kadar varlığı organizasyonunuzun materyal kütüphanesinde tutar.
Video Üretiminde Varlık Kullanımı
Bir varlık ACTIVE olduktan sonra, Video Oluştur komutunu çağırırken şu formlardan birini seçin:
- Genel bir materyal referansı için
material_asset_id - Birden fazla genel referans için
material_asset_ids - Medya rolünün açık olması gerektiğinde
image_url,start_image,end_imageveyareference_imagesiçindeasset://<asset-id>
Materyal referansları, seçilen modelin Seedance referans limitlerine dahil edilir. API Seedance material asset not found or not accessible hatası döndürürse, değerin bir grup ID'si değil varlık ID'si olduğunu, aynı organizasyona ve projeye ait olduğunu, silinmediğini ve ACTIVE olduğunu doğrulayın.
REST veya Volcengine Action
TokenLab yerel entegrasyonları, snake_case /v1/videos/assets* REST uç noktalarını kullanmaya devam edebilir. Mevcut Volcengine istemcileri, Materyal İşlemleri (Volc Uyumlu) ile PascalCase gövdelerini koruyabilir. Her iki arayüz de aynı organizasyon ve proje kapsamındaki materyal verileri üzerinde çalışır.
REST Örneği: Sanal Avatar Varlığı
curl https://api.tokenlab.sh/v1/videos/assets/groups \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"library_type":"aigc_avatar","group_name":"Product references","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_name":"Front view","asset_type":"Image","project_name":"default"}'
curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45?project_name=default \
-H "Authorization: Bearer $TOKENLAB_API_KEY"Action Örneği: Doğrulanmış Gerçek Kişi Varlığı
Önce görsel doğrulamayı oluşturun ve tamamlayın:
curl 'https://api.tokenlab.sh/?Action=CreateVisualValidateSession&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'
curl 'https://api.tokenlab.sh/?Action=GetVisualValidateResult&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'Ardından dönen GroupId değerini CreateAsset komutuna iletin:
curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"GroupId":"group-20260720123456-real1",
"URL":"https://example.com/person-front.png",
"Name":"Verified front view",
"AssetType":"Image",
"ProjectName":"default"
}'Durumu Active olana kadar GetAsset ile sorgulayın, ardından dönen varlık ID'sini video üretimine iletin. 10 Action işleminin tamamı, filtreler, sayfalama, yanıt şekilleri ve hatalar için Materyal İşlemleri (Volc Uyumlu) bölümüne bakın.