Animasyon API

Kullanılabilir animasyonları keşfetmek ve bunları rig'lenmiş karakterlere uygulamak için endpoint'ler.


POST/openapi/v1/animations

Bir Animasyon Görevi Oluştur

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.

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 only
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -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 action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -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 action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -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 FPS
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -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
    }
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

GET/openapi/v1/animations/:id

Bir Animasyon Görevini Getirme

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.

Request

GET
/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791
curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/animations/:id

Bir Animasyon Görevini Sil

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.

Request

DELETE
/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 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."
}

GET/openapi/v1/animations

Animasyon Görevlerini Listele

Ç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.

Request

GET
/openapi/v1/animations
curl "https://api.meshy.ai/openapi/v1/animations?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/animations/:id/stream

Bir Animasyon Görevini Akışla Al

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir Animasyon görevi için gerçek zamanlı güncellemeleri akış olarak sağlar.

Parametreler

  • Name
    id
    Type
    path
    Description

    Akışı alınacak Animasyon görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Server-Sent Events olarak Animasyon Görevi Nesneleri akışını döndürür.

PENDING veya IN_PROGRESS durumundaki görevler için yanıt akışı yalnızca gerekli progress ve status alanlarını içerecektir.

Request

GET
/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream
curl -N https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream 
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Animation Task Object structure
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

Animasyon Görevi Nesnesi

Animasyon Görevi nesnesi, riglenmiş bir karaktere animasyon uygulama iş birimini temsil eder.

Özellikler

  • Name
    id
    Type
    string
    Description

    Görev için benzersiz tanımlayıcı.

  • Name
    type
    Type
    string
    Description

    Animasyon görevinin türü. Değer animate şeklindedir.

  • Name
    status
    Type
    string
    Description

    Görevin durumu. Olası değerler: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Görevin progress değeri (0-100).

  • Name
    created_at
    Type
    timestamp
    Description

    Görevin oluşturulduğu zaman damgası (epoch'tan bu yana geçen milisaniye).

  • 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.

Example Animation Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

GET/openapi/v1/animations/library

Animasyonları Listele

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.

Aynı kataloğu her eylemin animasyonlu bir önizlemesiyle göz atarak incelemek için Animasyon kütüphanesi referansına bakın.

Bu uç nokta ücretsizdir — hiçbir kredi tüketmez.

Parametreler

  • Name
    search
    Type
    string
    Description

    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:

  • ?action_ids=92&category=Fighting, 92 eylemini döndürür.
  • ?action_ids=92&category=Dancing, [] döndürür — bu bir Dancing animasyonu değildir.
  • ?action_ids=92&search=walk, [] döndürür — adı walk ile eşleşmez.

Kategorilerine bakılmaksızın belirli animasyonları getirmek için action_ids'i tek başına geçirin.

Döndürülenler

Animasyon Nesnelerinin bir listesini döndürür.

Request

GET
/openapi/v1/animations/library
curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

Animasyon Nesnesi

  • Name
    action_id
    Type
    integer
    Description

    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.

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}