TokenLab Seedance Materyalleri: Prodüksiyon İş Akışları için Yeniden Kullanılabilir Video Referansları

Ekibiniz daha önce aynı yüz değiştirme (face-swap) URL'sini üç farklı API çağrısına yapıştırdıysa, Seedance materyal kütüphanesinin neden var olduğunu zaten biliyorsunuzdur. Yeniden kullanılabilir video referansları, bir elektronik tablodan her üretim isteğine kopyalanan tek seferlik URL'ler yerine, yaşam döngüsü durumuna sahip varlıklar olarak daha iyi çalışır. TokenLab, bu varlıkları kuruluşunuza özel olarak tanımlar; böylece referansları çağrılar arasında depolayabilir, doğrulayabilir ve yeniden kullanabilirsiniz. İş akışı yapısını test ettik: gruplar gerçek kişi materyallerini düzenler, varlıklar gerçek referansı tutar ve üretim çağrıları kimlikleri yalnızca durum ACTIVE (AKTİF) seviyesine ulaştıktan sonra tüketir. Örneğin, bir zamanlar görüntü bağlantılarından oluşan bir elektronik tablo tutan ve aynı referans videosunu beş kez yeniden yükleyen bir ekip, bu alışkanlığı tek bir materyal varlık kimliği ile değiştirebilir.

Önemli Çıkarımlar

• Materyal varlığı (material asset), üretime hazır referans nesnesidir; materyal grubu (material group) ise, özellikle gerçek kişi iş akışları için ilgili varlıkları düzenleyen kapsayıcıdır.
• Bir materyal varlığının id değerini, yalnızca durumu ACTIVE seviyesine ulaştıktan sonra material_asset_id olarak (veya material_asset_ids içinde) kullanın.
• İki kütüphane türü mevcuttur: sanal avatar ve gerçek kişi olmayan diğer yeniden kullanılabilir referanslar için aigc_avatar ve doğrulama gerektiren gerçek kişi materyal grupları için liveness_face.
• TokenLab, uyumlu görüntü girdilerini (image, image_url, image_urls, reference_images, start_image, end_image) ayrı bir yükleme adımı olmaksızın otomatik olarak materyal varlıklarına dönüştürebilir.
• Hazırlık süreci 60 saniyeyi aşarsa, API 409 seedance_material_preparing hatasıyla birlikte, sorgulayabileceğiniz ve yeniden deneyebileceğiniz auto_material_asset_ids değerlerini döndürür.
• Seedance, bu materyal sisteminin desteklediği mevcut genel model ailesidir. Belirli bir katmana bağımlılık oluşturmadan önce dokümantasyondaki modele özel yetenek detaylarını doğrulayın.

Seedance Materyal Kütüphanesi: Varlıklar ve Gruplar

Seedance materyali, TokenLab'in istek kapsamlı bir URL yerine kuruluş kapsamlı bir varlık olarak depoladığı yeniden kullanılabilir bir referanstır (görüntü, video veya ses). Her create-video çağrısına ham bir dosya bağlantısı iletmek yerine, referansı bir kez yükler veya içe aktarırsınız, üretime hazır hale gelmesini beklersiniz ve ardından ihtiyaç duyduğunuz kadar çok çağrıda kimliği ile referans gösterirsiniz.

Bu durum üç pratik nedenden dolayı önemlidir. Birincisi, tekrarlanan yüklemeler bant genişliğini boşa harcar ve özellikle büyük referans videoları için her isteğe gecikme ekler. İkincisi, ham URL'lerin süresi dolar, değiştirilir veya orijinal olarak barındırıldıkları depolama sistemi tarafından iptal edilir. TokenLab tarafından yönetilen bir materyal varlığı bu kırılganlığa sahip değildir. Üçüncüsü ve karakter tutarlı veya marka tutarlı video hatları oluşturan ekipler için en önemlisi, materyaller size sürümleyebileceğiniz, denetleyebileceğiniz ve üretim mantığınıza her seferinde dokunmadan değiştirebileceğiniz kararlı bir tanımlayıcı sağlar.

Materyal Varlıkları ve Materyal Grupları

Bu sistemdeki iki temel nesne, materyal varlığı ve materyal varlık grubudur. API referansını dikkatlice okumadıysanız bunları karıştırmak kolaydır.

Materyal varlığı, tek bir referans nesnesidir; bir avatar görüntüsü, bir canlılık doğrulaması yapılmış yüz, bir referans video klibi. Bunu oluşturduğunuzda, API bir id döndürür. Varlık ACTIVE durumuna ulaştığında video üretim çağrılarına ileteceğiniz değer bu id'dir.

Materyal varlık grubu, group_id ile tanımlanan bir kapsayıcıdır. Gruplar, ilgili varlıkları bir arada düzenler. Bunlar, bireysel varlıklar yüklenmeden önce doğrulamanın grup düzeyinde yapıldığı gerçek kişi (liveness_face) iş akışları için yapısal olarak gereklidir.

Kısacası: group_id düzenler; material_asset_id üretir. API'nin farklı bölümlerinde her iki alanı da göreceksiniz. Yanlış olanı yanlış yerde kullanmak, ekiplerin bu sistemle yaptığı en yaygın entegrasyon hatasıdır.

Alan	Tanımladığı şey	Nerede kullanılır
group_id	Materyal varlık grubu (kapsayıcı)	Bir grup oluştururken veya referans verirken, özellikle gerçek kişi doğrulama akışlarında
id (materyal varlığında)	Tek bir yeniden kullanılabilir referans	ACTIVE olduğunda material_asset_id olur
material_asset_id	Tekil bir varlık referansı	Bir referans yuvası için create-video içine iletilir
material_asset_ids	Varlık referansları dizisi	Birden fazla yeniden kullanılabilir referans gerektiğinde create-video içine iletilir

Tam alan tanımları ve gerekli parametreler, materyal varlığı oluşturma ve materyal varlık grubu oluşturma API referanslarında belgelenmiştir. Bunları üretim koduna yerleştirmeden önce okuyun. Dokümanlar iş akışı şeklini kapsar, her istek parametresini değil.

Sanal Avatar ve Gerçek Kişi İş Akışları

Seedance materyalleri iki kütüphane türünü destekler. Bu ayrım kozmetik değildir; iki farklı güvenlik ve rıza duruşunu yansıtır.

aigc_avatar: Sanal Avatarlar ve Gerçek Kişi Olmayan Referanslar

aigc_avatar türü, doğrulanmış gerçek bir kişiye bağlı olmayan yeniden kullanılabilir referansları kapsar: resimli karakterler, sentetik avatarlar, stilize figürler, ürün maskotları ve benzeri varlıklar. Bunları, doğrulama adımı olmaksızın doğrudan materyal varlığı oluşturma akışı üzerinden oluşturabilirsiniz.

Ürününüz kurgusal karakterler veya marka avatarları etrafında videolar üretiyorsa, bu kesinlikle istediğiniz kütüphane türüdür. Kimlik doğrulama gereksinimi olmadığı için daha basit bir oluşturma yoluna sahiptir.

liveness_face: Gerçek Kişi Materyal Grupları

liveness_face türü, gerçek bir kişinin benzerliği etrafında oluşturulan materyal grupları içindir. Bu, gerçek bir bireyi içeren, yüz tutarlı video üretimi için kullanılan referans türüdür. Bu durum kimlik ve rıza ile ilgili olduğundan, TokenLab, varlıklar gruba yüklenmeden önce bir doğrulama akışı gerektirir.

Doğrulama dizisi birkaç farklı adımdan oluşur:

1. Oturum oluşturma — arka ucunuz grup için bir doğrulama oturumu ister.
2. H5 akışı — doğrulanan kişi, barındırılan bir web akışı aracılığıyla canlılık kontrolünü tamamlar. H5, mobil web doğrulama arayüzünü ifade eder.
3. Geri arama (Callback) — doğrulama oturumu sona erdiğinde TokenLab sisteminizi bilgilendirir.
4. Sonucu bağlama (Bind result) — doğrulanan kimlik materyal grubuna bağlanır.
5. Grup kapsamlı yüklemeler — yalnızca bağlama başarılı olduktan sonra materyal varlıkları o belirli gruba yüklenebilir.

Bu, gerçek kişi materyallerinin doğası gereği grup öncelikli olduğu anlamına gelir. aigc_avatar ile yapabileceğiniz gibi doğrudan varlık oluşturmaya geçemezsiniz. Grubun var olması ve herhangi bir varlık yüklemesi geçerli olmadan önce doğrulamayı geçmesi gerekir.

Kontrol Listesi: Doğru Kütüphane Türünü Seçme

• Referans, gerçek ve tanımlanabilir bir kişinin yüzü veya benzerliği mi? → liveness_face kullanın ve doğrulama akışını planlayın.
• Referans sentetik, resimli veya gerçek kişi olmayan bir avatar mı? → aigc_avatar kullanın ve doğrulamayı atlayın.
• Ürününüz aynı gerçek kişi için birden fazla üretimde tutarlı bir kimliğe ihtiyaç duyuyor mu? → Grubu bir kez oluşturun, bir kez doğrulayın, gelecekteki varlıklar için grubu yeniden kullanın.
• Müşteri tarafından sağlanan bir referansın hangi türe girdiğinden emin değil misiniz? → Aksi kanıtlanana kadar liveness_face olarak değerlendirin; dokümanlardan doğrulayın, varsayımda bulunmayın.

Her üretim modelinin veya her istek türünün her iki kütüphane türünü de aynı şekilde desteklediğini varsaymayın. Bir mimariye karar vermeden önce Seedance Video Modelleri kılavuzundaki mevcut desteği doğrulayın.

Otomatik Materyal Hazırlığı Nasıl Çalışır?

Her referansın manuel bir yükleme adımına ihtiyacı yoktur. TokenLab, uyumlu görüntü girdilerini bir üretim isteğinin parçası olarak otomatik olarak materyal varlıklarına dönüştürebilir. Bu, basit durumlar için bir gidiş-dönüş süresini ortadan kaldırır.

Otomatik hazırlık için tanıdığı alanlar şunlardır:

• image
• image_url
• image_urls
• reference_images
• start_image
• end_image

Bunlardan herhangi birini doğrudan bir üretim çağrısına iletirseniz, TokenLab içe aktarma ve hazırlık işlemlerini arka planda halleder. Materyal varlığı uç noktasını önce ayrı olarak çağırmanız gerekmez.

Hazırlık 60 Saniyeden Uzun Sürdüğünde Ne Olur?

Hazırlık genellikle hızlıdır. Daha büyük veya daha karmaşık referans görüntülerinin üretime hazır bir varlığa dönüştürülmesi daha uzun sürebilir. Hazırlık 60 saniyeyi aşarsa, API şu yanıtı verir:

409 seedance_material_preparing

bununla birlikte hala hazırlanmakta olan varlıkların kimliklerini içeren bir auto_material_asset_ids alanı döner.

Bu, geleneksel anlamda bir hata değildir. Yeniden deneme sinyalidir. Entegrasyonunuz 409 seedance_material_preparing durumunu son kullanıcıya gösterilecek bir başarısızlık olarak değil, "kısa süre sonra tekrar kontrol et" yanıtı olarak değerlendirmelidir. Döndürülen varlık kimliklerini sorgulayın, ACTIVE durumunu bekleyin ve ardından bu kimlikleri kullanarak üretime devam edin.

Kendi hattımızda, bu durumu hız sınırı (rate-limit) geri çekilmesi gibi ele alıyoruz: beklenen, geçici ve kullanıcıya yönelik bir hata olarak raporlanmak yerine kod içinde ele alınan bir durum. Tek bir try/catch yerine küçük bir yeniden deneme döngüsü öneriyoruz.

Üretimde Seedance Materyal Kütüphanesini Kullanma

Bir materyal varlığı — manuel olarak yüklenmiş veya otomatik olarak hazırlanmış olsun — ACTIVE durumuna ulaştığında, id değeri bir create video çağrısında material_asset_id olarak veya material_asset_ids içinde bir girdi olarak kullanılabilir hale gelir.

Temel iş akışı şöyledir:

1. Referansın gerçek kişi olup olmadığına karar verin. Buna göre liveness_face (doğrulamalı) veya aigc_avatar seçin.
2. Gerçek kişi ise: materyal grubunu oluşturun, doğrulama oturumunu ve H5 akışını çalıştırın, geri aramayı alın ve sonucu bağlayın.
3. Materyal varlığını oluşturun veya içe aktarın; doğrudan bir yükleme çağrısı ile veya otomatik hazırlığın bir üretim isteği içindeki uyumlu bir görüntü alanını işlemesine izin vererek.
4. Durumu kontrol edin. Varlık ACTIVE rapor edene kadar varlık kimliğini üretime iletmeyin.
5. 409 seedance_material_preparing alırsanız, döndürülen auto_material_asset_ids değerlerini sorgulayın ve ACTIVE olduklarında yeniden deneyin.
6. Gecikme ve kalite ihtiyaçlarınıza bağlı olarak mevcut bir Seedance modelini hedefleyerek, id değerini create-video çağrınızda material_asset_id olarak veya material_asset_ids içinde kullanın.
7. Referansı yeniden yüklemek yerine, gelecekteki üretim çağrılarında aynı varlık kimliğini yeniden kullanın.

Görev yönetimi de burada önem kazanır. Yeniden kullanılan bir materyal varlığı üzerine inşa edilmiş bir üretim çağrısının orta aşamada durması gerekebilir. Bu, maliyet kontrolü, değişen yaratıcı özet veya kötü bir istem nedeniyle olabilir. İptalin devam eden video işleriyle nasıl etkileşime girdiği hakkında Seedance görev iptali hakkındaki tamamlayıcı yazımıza bakın.

TokenLab'deki video üretim modellerinde nelerin mevcut olduğuna dair daha geniş bir karşılaştırma için, video modelleri kategori sayfası mevcut seçenekleri yan yana listeler.

Pratik Sonraki Adımlar

• Prototip oluşturuyorsanız, aigc_avatar materyalleri ile başlayın. Oluşturma yolu daha basittir ve etrafında inşa edilecek bir doğrulama bağımlılığı yoktur.
• Ürününüz gerçek kişi tutarlılığı gerektiriyorsa, doğrulama akışını (oturum → H5 → geri arama → bağlama) işe alım sürecinizin birinci sınıf bir parçası olarak oluşturun, sonradan eklenen bir özellik olarak değil.
• Üretime herhangi bir şey göndermeden önce 409 seedance_material_preparing için bir yeniden deneme döngüsü ekleyin. Bunu bir uç durum olarak değil, beklenen bir davranış olarak ele alın.
• Materyal varlık kimliklerini kendi dahili referans kayıtlarınızla birlikte saklayın. Bu şekilde, hangi varlığın hangi karakterle veya ürünle eşleştiğini yeniden türetmek zorunda kalmazsınız.
• Materyal varlığı ve materyal varlık grubu API referanslarını doğrudan inceleyin. Dokümanlar iş akışı şeklini tanımlar ve entegrasyon kodunu yazmadan önce kesin istek/yanıt alanları güncel dokümanlara göre doğrulanmalıdır.

Seedance varlık panosu, oluşturduğunuz varlıkların durumunu, kütüphane türünü ve grup ilişkilerini gösterir.

AI video API fiyatlandırması 2026 genel bakışımızdaki güncel oranlar, maliyetlerin kullanımla nasıl ölçeklendiğini anlamanıza yardımcı olur. Ayrıca TokenLab panosu kullanım dışa aktarımları bölümündeki rehberliği kullanarak kendi kullanım verilerinizi takip edebilir ve dışa aktarabilirsiniz.

SSS

Materyal varlıkları ve materyal grupları nasıl farklılık gösterir?

Materyal varlığı, tek bir yeniden kullanılabilir referans nesnesidir; bir avatar görüntüsü, bir canlılık doğrulaması yapılmış yüz, bir referans video klibi. id değeri ACTIVE olduğunda material_asset_id olur. Materyal grubu, group_id ile tanımlanan bir kapsayıcıdır. Gruplar ilgili varlıkları düzenler ve liveness_face iş akışları için gereklidir. Kısacası: group_id düzenler; material_asset_id üretir.

Bir üretim çağrısı neden 409 seedance_material_preparing döndürür?

image_url veya start_image gibi uyumlu görüntü alanları tarafından tetiklenen otomatik materyal hazırlığı 60 saniyeden uzun sürebilir. Bu olduğunda, API auto_material_asset_ids ile birlikte 409 seedance_material_preparing döndürür. Bu kimlikleri sorgulayın, ACTIVE olmasını bekleyin ve üretimi yeniden deneyin. Bu, bir başarısızlık değil, geçici bir devam eden durum sinyalidir.

Gerçek kişi referansları her zaman doğrulama gerektirir mi?

Evet. Referans gerçek, tanımlanabilir bir kişinin yüzünü veya benzerliğini içerdiğinde liveness_face türünü ve doğrulama akışını kullanın. Akış, herhangi bir varlık o gruba yüklenmeden önce oturum oluşturma, H5 canlılık kontrolü, geri arama ve bağlama adımı gerektirir. Resimli veya sentetik avatarlar gibi gerçek kişi olmayan referanslar aigc_avatar kullanır ve bu yolu gerektirmez.

Bir materyal varlığını birden fazla Seedance video işinde yeniden kullanabilir miyim?

Evet, varlık ACTIVE durumuna ulaştıktan sonra. id değerini create-video çağrısında material_asset_id olarak veya material_asset_ids içinde kullanın. Referansı yeniden yüklemek yerine, gelecekteki üretim çağrılarında aynı varlık kimliğini yeniden kullanın. Devam eden bir işi durdurmanız gerekirse, Seedance görev iptali bölümüne bakın.

Kaynaklar ve Güncellik

• Seedance Video Modelleri kılavuzu — https://docs.tokenlab.sh/guides/seedance-2-video — gözlemlenen tarih 2026-07-09
• Seedance materyal varlığı oluşturma (API referansı) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — gözlemlenen tarih 2026-07-09
• Seedance materyal varlık grubu oluşturma (API referansı) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — gözlemlenen tarih 2026-07-09
• Video oluşturma (API referansı) — https://docs.tokenlab.sh/api-reference/video/create-video — gözlemlenen tarih 2026-07-09
• TokenLab Seedance varlık panosu — /dashboard/seedance-assets — gözlemlenen tarih 2026-07-09

Burada açıklanan API davranışı, alan adları ve durum semantiği, gözlemlenen tarih itibarıyla genel dokümantasyonu ve pano metinlerini yansıtır. TokenLab'in Seedance materyal sistemi aktif geliştirme aşamasındadır; üretim entegrasyon kodunu tamamlamadan önce bağlantılı dokümanlardaki mevcut parametre adlarını, durum değerlerini ve modele özel desteği doğrulayın.

Kararlı, yeniden kullanılabilir referanslara dayalı bir video hattı oluşturuyorsanız, Seedance Video Modelleri kılavuzu ile başlayın. Mevcut parametre adlarını görmenin ve hedef model katmanınızın aslında neyi desteklediğini doğrulamanın en hızlı yolu budur.