Bu uç nokta, önceden rig'lenmiş bir karaktere animasyon uygulamak için yeni bir görev oluşturmanıza olanak tanır — animasyon kütüphanesinden hazır bir aksiyon (action_id), tek bir dosyada birleştirilmiş birden fazla hazır aksiyon (action_ids) veya Text to Motion API ile oluşturduğunuz bir hareket klibi (motion_task_id). Son işleme seçeneklerini de içerir.
Parametreler
Name
rig_task_id
Type
string
Zorunlu
Description
Başarıyla tamamlanmış bir rigging görevinin id değeri (POST /openapi/v1/rigging çağrısından). Bu görevdeki karakter canlandırılacaktır.
Name
action_id
Type
integer
Description
Uygulanacak hazır animasyon aksiyonunun tanımlayıcısı. Kullanılabilir tüm animasyonların tam listesi için Animasyon Kütüphanesi Referansı'na bakın. action_id, action_ids veya motion_task_id parametrelerinden tam olarak birini sağlayın.
Name
action_ids
Type
array of integers
Description
Aynı anda uygulanacak birden fazla hazır animasyon aksiyonu; her aksiyon için bir animasyon klibi içeren tek bir dosya olarak döndürülür — bu, bir oyun motorundaki durum makinesinden bir karakteri yönetmek için kullanışlıdır. Animasyon Kütüphanesi Referansı'ndan 1 ila 10 arasında action_id değeri sağlayın; kimlikler benzersiz olmalıdır. Aksiyon başına 3 kredi ücretlendirilir. action_id, action_ids veya motion_task_id parametrelerinden tam olarak birini sağlayın.
Tek elemanlı bir action_ids göndermek, bu değeri action_id olarak göndermekle eşdeğerdir.
Name
motion_task_id
Type
string
Description
Hazır bir aksiyon yerine uygulanacak, başarıyla tamamlanmış bir Text to Motion görevinin id değeri. Oluşturulan klip, rig'lenmiş karaktere yeniden hedeflenir ve klip oluşturma anında anlık görüntü olarak alınır; bu nedenle kaynak görev daha sonra sona erse veya silinse bile bu görev etkilenmez. Kaynak görevin varlıkları 3 gün boyunca saklanır — klip süresi dolmadan önce uygulayın. İki ayaklı (biped) bir rig gerektirir. action_id, action_ids veya motion_task_id parametrelerinden tam olarak birini sağlayın.
Name
post_process
Type
object
Description
Animasyon çıktısı için isteğe bağlı son işleme. Standart animasyon dosyalarını almak için bunu atlayın.
Yalnızca şu durumlarda geçerli post_process is set
Name
operation_type
Type
string
Zorunlu
Description
Gerçekleştirilecek işlem türü. Kullanılabilir değerler: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
varsayılan 30
Description
Hedef kare hızı. Yalnızca operation_type değeri change_fps olduğunda geçerlidir. İzin verilen değerler: 24, 25, 30, 60.
action_ids kullanıldığında görev, aksiyon başına bir dosya yerine tek bir birleştirilmiş dosya döndürür: animation_glb_url ve animation_fbx_url, her biri istenen her aksiyonu ayrı bir klip olarak içeren tek bir varlığı işaret eder.
Klip sırası: kimliklerin sayısal sırası değil, action_ids dizisinin sırası.
Klip adları: animasyonun kütüphanedeki adı; bu, bir karakterin tüm animasyonlarını Meshy web uygulamasından tek bir dosya olarak dışa aktardığınızda elde ettiğiniz adlarla eşleşir. İstenen iki kimlik aynı klip adına karşılık geliyorsa, sonraki olan, adları benzersiz tutmak için kendi action_id değeriyle sonlandırılır.
Son işleme: tek tek kliplere değil, birleştirilmiş dosyaya uygulanır.
motion_task_id kullanıldığında, yeniden hedefleme yalnızca GLB olan bir animasyon üretebilir. post_process istediyseniz ve FBX kullanılabilir değilse, görev bir task_error ile başarısız olur ve krediniz otomatik olarak iade edilir; post_process olmadan görev başarılı olur ve animation_fbx_url boş kalır.
Dönüş Değerleri
Yanıtın result özelliği, yeni oluşturulan animasyon görevinin görev id değerini içerir.
Hata Modları
Name
400 - Bad Request
Description
İstek kabul edilemedi. Yaygın nedenler:
Eksik parametre: rig_task_id eksik veya action_id, action_ids ve motion_task_id değerlerinden hiçbiri sağlanmamış.
Çakışan parametreler: action_id, action_ids ve motion_task_id değerlerinden birden fazlası sağlanmış — bunlar birbirini dışlar.
Geçersiz rig görevi: rig_task_id geçersiz veya başarısız/olmayan bir göreve işaret ediyor.
Geçersiz aksiyon kimliği: action_id — veya action_ids içindeki bir öğe — geçerli bir animasyona karşılık gelmiyor.
Çok fazla aksiyon: action_ids 10'dan fazla kimlik içeriyor.
Yinelenen aksiyonlar: action_ids aynı kimliği birden fazla kez içeriyor.
Hareket görevi hazır değil: motion_task_id görevi henüz SUCCEEDED durumuna ulaşmadı.
Desteklenmeyen rig: motion_task_id, iki ayaklı (biped) bir rig gerektirir; dört ayaklı (quadruped) rig'ler reddedilir.
Name
401 - Unauthorized
Description
Kimlik doğrulama başarısız oldu. Lütfen API anahtarınızı kontrol edin.
Name
402 - Payment Required
Description
Bu görevi gerçekleştirmek için yetersiz kredi.
Name
404 - Not Found
Description
rig_task_id ile belirtilen rigging görevi bulunamadı, motion_task_id ile belirtilen hareket görevi bulunamadı veya hareket klibinin süresi doldu (kaynak görev varlıkları 3 gün boyunca saklanır).
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.
Request
POST
/openapi/v1/animations
# Animate a rigged model with required params onlycurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579", "action_id": 92 }'# Apply several preset actions and get one file with one clip per actioncurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579", "action_ids": [10, 25, 92] }'# Apply a generated Text to Motion clip instead of a preset actioncurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579", "motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791" }'# With post-processing to change FPScurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579", "action_id": 92, "post_process": { "operation_type": "change_fps", "fps": 24 } }'
Bu uç nokta, geçerli bir görev id'si verildiğinde bir animasyon görevini getirmenizi sağlar. Hangi özelliklerin dahil olduğunu görmek için Animasyon Görevi Nesnesi bölümüne bakın.
Parametreler
Name
id
Type
path
Description
Getirilecek animasyon görevi için benzersiz tanımlayıcı.
Dönüş Değerleri
Yanıt, Animasyon Görevi nesnesini içerir. Ayrıntılar için Animasyon Görevi Nesnesi bölümüne bakın.
Bu uç nokta, ilişkili tüm modeller ve veriler dahil olmak üzere bir animasyon görevini kalıcı olarak siler. Bu işlem geri alınamaz.
Yol Parametreleri
Name
id
Type
path
Description
Silinecek animasyon görevinin ID'si.
Görev Durumu
Hâlâ PENDING durumunda olan bir görev silinir ve oluşturma sırasında
harcanan kredi iade edilir.
Zaten IN_PROGRESS durumunda olan bir görev silinemez: istek
409 Conflict ile reddedilir ve görev çalışmaya devam eder. Worker'ın
zaten başlattığı bir görev için kredi iadesi yapılmaz, bu nedenle görevi
çalışırken silmek hem kredinizi hem de sonucu kaybetmenize neden olur.
Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin,
ardından silin.
Bir uç (terminal) durumda (SUCCEEDED, FAILED veya CANCELED) olan bir
görev iade yapılmadan silinir.
Döndürülenler
Başarı durumunda 200 OK, görev IN_PROGRESS durumundayken ise
409 Conflict döndürür.
// 200 OK on success, with an empty body.//// 409 Conflict when the task is IN_PROGRESS — the task is left running:{"message":"Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."}
Çağıranın animasyon görevlerinin, en yeniden en eskiye sıralanmış, sayfalanmış bir listesini döndürür. page_num ve page_size üzerinden standart sayfalama kullanılır.
API aracılığıyla oluşturulan görevlerin API aracılığıyla yönetildiğini unutmayın — bunlar web uygulamasının My Assets bölümünde görünmez. Artık kimliğini elinizde bulundurmadığınız bir görevi bulmak için bu uç noktayı kullanın.
Görevin oluşturulduğu zaman damgası (epoch'tan bu yana geçen milisaniye).
Bir zaman damgası, RFC 3339 standardını takip ederek
1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısını temsil eder.
Örneğin, 1 Eylül 2023 Cuma günü, GMT saatiyle 12:00:00, 1693569600000 olarak temsil edilir. Bu durum
Meshy API'deki tüm zaman damgaları için geçerlidir.
Name
started_at
Type
timestamp
Description
Görevin işlenmeye başladığı zaman damgası (epoch'tan bu yana geçen milisaniye). Başlamadıysa 0 değerini alır.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman damgası (epoch'tan bu yana geçen milisaniye). Tamamlanmadıysa 0 değerini alır.
Name
expires_at
Type
timestamp
Description
Görev sonucundaki assetlerin süresinin dolacağı zaman damgası (epoch'tan bu yana geçen milisaniye).
Name
task_error
Type
object
Description
Başarısız olan görevler için hata ayrıntıları. task_error nesnesinin tam referansı için Hatalar bölümüne bakın.
Name
consumed_credits
Type
integer
Description
Bu görev tarafından tüketilen kredi sayısı. Görev durumu PENDING, IN_PROGRESS veya SUCCEEDED olduğunda mevcuttur. FAILED görevler için 0 döner (başarısızlık durumunda kredi iadesi yapılır).
Name
result
Type
object
Description
Görev SUCCEEDED olduğunda çıktı animasyon URL'lerini içerir.
Name
animation_glb_url
Type
string
Description
GLB formatındaki animasyon için indirilebilir URL. action_ids ile oluşturulan bir görev için bu tek dosya, istenen her eylemi ayrı bir klip olarak içerir.
Name
animation_fbx_url
Type
string
Description
FBX formatındaki animasyon için indirilebilir URL. action_ids ile oluşturulan bir görev için bu tek dosya, istenen her eylemi ayrı bir klip olarak içerir.
Name
processed_usdz_url
Type
string
Description
USDZ formatında işlenmiş animasyon için indirilebilir URL.
Name
processed_armature_fbx_url
Type
string
Description
FBX formatında işlenmiş iskelet için indirilebilir URL.
Name
processed_animation_fps_fbx_url
Type
string
Description
FBX formatında FPS'i değiştirilmiş animasyon için indirilebilir URL (örneğin, change_fps işlemi kullanıldıysa).
Name
preceding_tasks
Type
integer
Description
Kuyruktaki önceki görevlerin sayısı. Yalnızca durum PENDING olduğunda anlamlıdır.
Kütüphanedeki her animasyonu, action_id sırasına göre döndürür. Yanıt, sayfalanmış değil eksiksiz bir listedir, bu nedenle bir eylem seçicisini doldurmak için tek bir çağrı yeterlidir. Filtreler sonucu daraltır; her şeyi getirmek için hepsini boş bırakın.
name veya key üzerinde büyük/küçük harf duyarsız alt dize eşleşmesi. Harfi harfine eşleştirilir, bu nedenle % ve _ joker karakter değil sıradan karakterlerdir.
Name
category
Type
string
Description
category üzerinde tam eşleşme.
Kullanılabilir değerler:
WalkAndRun
BodyMovements
DailyActions
Fighting
Dancing
Name
sub_category
Type
string
Description
sub_category üzerinde tam eşleşme. Tek başına kabul edilir — alt kategori adları kategoriler arasında benzersiz değildir (Transitioning, hem Fighting hem de DailyActions altında görünür), bu nedenle bir category olmadan filtre, o alt kategoriyi göründüğü her yerde eşleştirir.
Name
action_ids
Type
string
Description
Belirli id'leri çözümlemek için, göz atmak yerine döndürülecek action_id değerlerinin virgülle ayrılmış listesi. En fazla 200 id kabul eder. Hiçbir animasyonun taşımadığı id'ler yanıtta basitçe bulunmaz, bu nedenle bunu ayrıca sakladığınız id'lerin hâlâ kullanılabilir olup olmadığını kontrol etmek için de kullanabilirsiniz.
Filtreleri birleştirme
Filtreler birlikte uygulanır — her biri sonucu daha da daraltır, bu nedenle bir animasyon yalnızca hepsini karşılıyorsa döndürülür. Tek bir filtre içinde, birden çok değer bunlardan herhangi biriyle eşleşir: search, name veya key ile eşleşir ve action_ids listedeki herhangi bir id ile eşleşir.
Bu, örtüşme olmayan bir kombinasyonun bir hata yerine boş bir dizi döndüreceği anlamına gelir. 92 eylemi, bir Fighting animasyonu olan "Double Combo Attack"tir:
Burada döndürülen her action_id, yukarıdaki Bir Animasyon Görevi Oluştur tarafından kabul edilir ve kabul ettiği her id burada döndürülür. Kullanımdan kaldırılan animasyonlar her ikisinde de bulunmaz. Kütüphaneyi önbelleğe alıyorsanız, kullanımdan kaldırılan bir id'nin seçicinizde kalmaması için periyodik olarak yenileyin.
Bir animasyon görevi oluştururken action_id olarak geçirilecek değer. Benzersiz ve sabittir, ancak ardışık değildir — kullanımdan kaldırılan animasyonlar numaralandırmada boşluklar bırakır, bu yüzden hiçbir zaman bir id aralığının geçerli olduğunu varsaymayın.
Name
name
Type
string
Description
Görüntüleme için insan tarafından okunabilir etiket. Benzersiz değildir: bazı animasyonlar farklı bir varyantla aynı adı paylaşır, bu yüzden kimlik olarak action_id veya key kullanın.
Name
key
Type
string
Description
Animasyon için benzersiz ve sabit kısa ad (slug). Kendi depolamanızı anahtarlamak için sayısal olmayan bir tanımlayıcıya ihtiyaç duyduğunuzda bunu kullanın.
Name
category
Type
string
Description
Üst düzey gruplama, örn. Fighting.
Name
sub_category
Type
string
Description
Kategori içindeki gruplama, örn. AttackingwithWeapon.
Name
preview_url
Type
string
Description
Eylemi önizleyen, doğrudan kendi seçicinizde oluşturmaya uygun bir animasyonlu GIF'in URL'si.