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ğinizNe yapmalı
Bir kez kullanılan tek bir görselDesteklenen 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 kullanmaBir 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 kullanmaGö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şımaAction istek yapısını koruyun ve Volc uyumlu materyal referansını kullanın

Gruplar ve materyaller

ÖğeREST alanıAction alanıAnlamı
Materyal grubugroup_idGroupIdİlgili materyalleri bir arada tutar
MateryalidIdİçe aktarılan tek bir görsel, video veya ses dosyası; aktif hale geldikten sonra bu ID'yi kullanın
Sanal avatar grubulibrary_type: "aigc_avatar"GroupType: "AIGC"Gerçek kişi doğrulaması gerektirmez
Gerçek kişi grubulibrary_type: "liveness_face"GroupType: "LivenessFace"Yalnızca başarılı bir görsel doğrulama akışıyla oluşturulur
Proje adıproject_nameProjectNameFarklı 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_preparing hatası 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:

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.

  1. CallbackURL ile Görsel Doğrulama Oturumu Oluştur komutunu çağırın; Result.BytedToken değerini kaydedin ve doğrulanan kişi için Result.H5Link bağlantısını açın.
  2. H5 akışı geri çağırmaya (callback) yönlendirdikten sonra, aynı BytedToken ve ProjectName ile Görsel Doğrulama Sonucunu Al komutunu sorgulayın.
  3. Dönen Result.GroupId değerini saklayın. TokenLab, bu adım sırasında LivenessFace grubunu oluşturur ve bağlar.
  4. Bu grup ID'si ile bir varlık oluşturun, ardından varlık ACTIVE olana 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ürDesteklenen girdi
Görseljpeg, png, webp, bmp, tiff, gif, heic, heif; ≤ 30 MiB; genişlik ve yükseklik [300, 6000] px; en-boy oranı [0.4, 2.5]
Videomp4, mov; ≤ 200 MiB
Sesaac, 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_image veya reference_images içinde asset://<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.

Bu sayfada