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şturun

Bu uç nokta, daha önce kemik yapısı verilmiş (rigged) bir karaktere animasyon uygulamak için yeni bir görev oluşturmanızı sağlar — bu, animasyon kütüphanesinden hazır bir eylem (action_id) veya Text to Motion API ile oluşturduğunuz bir hareket klibi (motion_task_id) olabilir. Son işleme seçeneklerini 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'den). Bu görevdeki karakter canlandırılacaktır.
Name
action_id
Type
integer
Description
Uygulanacak hazır animasyon eyleminin tanımlayıcısı. Kullanılabilir animasyonların tam listesi için Animasyon kütüphanesi Referansı'na bakın. action_id veya motion_task_id'den yalnızca birini sağlayın.
Name
motion_task_id
Type
string
Description
Hazır bir eylem yerine uygulanacak, başarıyla tamamlanmış bir Text to Motion görevinin id değeri. Oluşturulan klip, kemik yapısı verilmiş karaktere yeniden hedeflenir ve klip oluşturma anında anlık görüntüsü alınır, bu nedenle kaynak görev daha sonra süresi dolsa veya silinse bile bu görev etkilenmez. Kaynak görevin varlıkları 3 gün boyunca saklanır — klibi süresi dolmadan önce uygulayın. İki ayaklı (biped) bir rig gerektirir. action_id veya motion_task_id'den yalnızca 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şlemin 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.

motion_task_id ile yeniden hedefleme yalnızca GLB olan bir animasyon üretebilir. post_process talep ettiyseniz ve FBX mevcut 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 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 ne action_id ne de motion_task_id sağlanmış.
- Çakışan parametreler: hem action_id hem de motion_task_id sağlanmış — bunlar birbirini dışlar.
- Geçersiz rig görevi: rig_task_id geçersiz veya başarısız/mevcut olmayan bir göreve işaret ediyor.
- Geçersiz eylem kimliği: action_id, geçerli bir animasyona karşılık gelmiyor.
- Hareket görevi hazır değil: motion_task_id görevi henüz SUCCEEDED durumuna ulaşmamış.
- 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 dolmuş (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 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.

Dönüş Değerleri

Başarı durumunda 200 OK döner.

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

// Returns 200 Ok on success.

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, iskelet verilmiş 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 olur.
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).
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, Meshy API'sindeki 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.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman damgası (epoch'tan bu yana geçen milisaniye). Tamamlanmadıysa 0.
Name
expires_at
Type
timestamp
Description
Görev sonucu varlıkların süresinin dolacağı zaman damgası (epoch'tan bu yana geçen milisaniye).
Name
task_error
Type
object
Description
Başarısız görevler için hata ayrıntıları. Eksiksiz task_error nesne referansı için Hatalar sayfasına 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 krediler iade edilir).
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.
- Name
  animation_fbx_url
  Type
  string
  Description
  FBX formatındaki animasyon için indirilebilir URL.
- 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 ise 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
}