İskelet Bağlama API'si

İskelet Bağlama API'si, 3D insansı modellere programatik olarak bir iskelet (iskelet) eklemenize ve ağı buna bağlayarak animasyona hazır hale getirmenize olanak tanır. İskelet bağlanmış bir karaktere animasyonlar uygulamak için Animasyon API'sine bakın.

Programatik iskelet bağlamanın şu anda yalnızca net şekilde tanımlanmış uzuvlara ve vücut yapısına sahip standart insansı (iki ayaklı) varlıklarla iyi çalıştığını lütfen unutmayın.

POST/openapi/v1/rigging

Rigging Görevi Oluştur

Bu uç nokta, verilen bir 3D model için yeni bir rigging görevi oluşturmanızı sağlar. Başarıyla tamamlandığında, standart formatlarda rigging uygulanmış bir karakter ve isteğe bağlı olarak temel yürüme/koşma animasyonları sağlar.

Şu anda otomatik rigging aşağıdaki modeller için uygun değildir:

Dokusuz meshler
İnsansı olmayan assetler
Uzuv ve gövde yapısı belirsiz olan insansı assetler

input_task_id kullanırken, 300.000'den fazla yüzeye sahip modeller rigging için desteklenmez. Lütfen rigging öncesinde yüzey sayısını azaltmak için Yeniden ağ API kullanın.

model_url kullanırken, karakterin yüzü +Z eksenine (standart glTF ileri yönü) bakmalıdır. Diğer eksenlere bakan modellerde poz tahmini başarısız olur.

Parametreler

input_task_id veya model_url değerlerinden yalnızca biri gereklidir. İkisi de sağlanırsa, input_task_id öncelik alır.

Name
input_task_id
Type
string
Zorunlu
Description
Rigging uygulanması gereken girdi görevi. Şu anda dokulu insansı modelleri destekliyoruz.

Name
model_url
Type
string
Zorunlu
Description
Lütfen Meshy'nin rigging uygulaması için herkese açık erişilebilir bir URL veya Data URI üzerinden bir 3D model sağlayın. Şu anda dokulu insansı GLB dosyalarını (.glb formatı) destekliyoruz.

Name
height_meters
Type
number
varsayılan 1.7
Description
Karakter modelinin metre cinsinden yaklaşık yüksekliği. Bu, ölçeklendirme ve rigging doğruluğuna yardımcı olur. Pozitif bir sayı olmalıdır.
Name
texture_image_url
Type
string
Description
Modelin UV açılımı yapılmış temel renk doku görüntüsü. Herkese açık erişilebilir URL veya Data URI. Şu anda .png formatlarını destekliyoruz.

Dönen Değerler

Yanıtın result özelliği, yeni oluşturulan rigging görevinin görev id değerini içerir.

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemezdi. Yaygın nedenler:
- Eksik parametre: model_url veya input_task_id sağlanmalıdır.
- Geçersiz model formatı: model_url, desteklenmeyen bir uzantıya sahip bir dosyaya işaret ediyor (yalnızca .glb desteklenir).
- Erişilemeyen URL: model_url indirilemedi.
- Geçersiz girdi görevi: input_task_id geçerli bir API görevine başvurmuyor.
- Yüzey sayısı aşıldı: Girdi modelinde 300.000'den fazla yüzey var. Lütfen rigging öncesinde yüzey sayısını azaltmak için Yeniden ağ API kullanın.
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
422 - Unprocessable Entity
Description
Poz tahmini başarısız oldu. Sağlanan model geçerli bir insansı karakter olmayabilir.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

Request

POST

/openapi/v1/rigging

# Rig a model from a URL
curl https://api.meshy.ai/openapi/v1/rigging \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model_url": "YOUR_MODEL_URL_OR_DATA_URI",
    "height_meters": 1.8
  }'

Response

{
  "result": "018b314a-a1b5-716d-c222-2f1776f7f579"
}

GET/openapi/v1/rigging/:id

Bir İskelet Bağlama Görevini Al

Bu uç nokta, geçerli bir görev idsi verildiğinde bir iskelet bağlama görevini almanızı sağlar. Hangi özelliklerin dahil edildiğini görmek için İskelet Bağlama Görevi Nesnesi bölümüne bakın.

Parametreler

Name
id
Type
path
Description
Alınacak iskelet bağlama görevi için benzersiz tanımlayıcı.

Döndürür

Yanıt, İskelet Bağlama Görevi nesnesini içerir. Ayrıntılar için İskelet Bağlama Görevi Nesnesi bölümünü kontrol edin.

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

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

Response

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/rigging/:id

Bir Rigging Görevini Sil

Bu uç nokta, ilişkili tüm modeller ve veriler dahil olmak üzere bir rigging görevini kalıcı olarak siler. Bu işlem geri alınamaz.

Yol Parametreleri

Name
id
Type
path
Description
Silinecek rigging görevinin ID'si.

Dönen Değerler

Başarı durumunda 200 OK döndürür.

Request

DELETE

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/rigging/:id/stream

Bir Rigging Görevini Akış Olarak İzle

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

Parametreler

Name
id
Type
path
Description
Akış olarak izlenecek Rigging görevi için benzersiz tanımlayıcı.

Döndürür

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

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

Request

GET

/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/stream

curl -N https://api.meshy.ai/openapi/v1/rigging/018b314a-a1b5-716d-c222-2f1776f7f579/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": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Rigging Task Object structure
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/.../Character_output.fbx?...",
    "rigged_character_glb_url": "https://assets.meshy.ai/.../Character_output.glb?...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.glb?...",
      "walking_fbx_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin.fbx?...",
      "walking_armature_glb_url": "https://assets.meshy.ai/.../Animation_Walking_withSkin_armature.glb?...",
      "running_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.glb?...",
      "running_fbx_url": "https://assets.meshy.ai/.../Animation_Running_withSkin.fbx?...",
      "running_armature_glb_url": "https://assets.meshy.ai/.../Animation_Running_withSkin_armature.glb?..."
    }
  },
  "preceding_tasks": 0
}

İskelet Bağlama Görev Nesnesi

İskelet Bağlama Görev nesnesi, bir karaktere iskelet bağlama için iş birimini temsil eder.

Özellikler

Name
id
Type
string
Description
Görev için benzersiz tanımlayıcı.
Name
type
Type
string
Description
Rigging görevinin türü. Değer rig ş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). Başlamadıysa 0, başarılı olduysa 100.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman damgası (epoch'tan bu yana milisaniye).
Zaman damgası, 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısını temsil eder ve RFC 3339 standardını izler. Örneğin, 1 Eylül 2023 Cuma 12:00:00 GMT, 1693569600000 olarak temsil edilir. Bu, Meshy API içindeki 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 milisaniye). Başlamadıysa 0.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman damgası (epoch'tan bu yana milisaniye). Tamamlanmadıysa 0.
Name
expires_at
Type
timestamp
Description
Görev sonucu asset'lerinin süresinin dolduğu ve silinebileceği zaman damgası (epoch'tan bu yana milisaniye).
Name
task_error
Type
object
Description
Başarısız görevler için hata ayrıntıları. Tam task_error nesne 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 bulunur. FAILED görevler için 0 döndürür (kredi, başarısızlık durumunda iade edilir).
Name
result
Type
object
Description
Görev SUCCEEDED ise çıktı asset URL'lerini içerir, aksi takdirde null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  FBX formatındaki rigging yapılmış karakter için indirilebilir URL.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  GLB formatındaki rigging yapılmış karakter için indirilebilir URL.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Varsayılan animasyonlar için URL'leri içerir. (örn. generate_basic_animations örtük olarak true ise veya varsayılan olarak etkinleştirildiyse).
  Name
  walking_glb_url
  Type
  string
  Description
  GLB formatındaki yürüme animasyonu için indirilebilir URL (skin ile).
  Name
  walking_fbx_url
  Type
  string
  Description
  FBX formatındaki yürüme animasyonu için indirilebilir URL (skin ile).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  GLB formatındaki yürüme animasyonu iskeleti için indirilebilir URL.
  Name
  running_glb_url
  Type
  string
  Description
  GLB formatındaki koşma animasyonu için indirilebilir URL (skin ile).
  Name
  running_fbx_url
  Type
  string
  Description
  FBX formatındaki koşma animasyonu için indirilebilir URL (skin ile).
  Name
  running_armature_glb_url
  Type
  string
  Description
  GLB formatındaki koşma animasyonu iskeleti için indirilebilir URL.
Name
preceding_tasks
Type
integer
Description
Kuyruktaki önceki görevlerin sayısı. Yalnızca durum PENDING ise anlamlıdır.

Example Rigging Task Object

{
  "id": "018b314a-a1b5-716d-c222-2f1776f7f579",
  "type": "rig",
  "status": "SUCCEEDED",
  "created_at": 1747032400453,
  "progress": 100,
  "started_at": 1747032401314,
  "finished_at": 1747032418417,
  "expires_at": 1747291618417,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5,
  "result": {
    "rigged_character_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.fbx?Expires=...",
    "rigged_character_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Character_output.glb?Expires=...",
    "basic_animations": {
      "walking_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.glb?Expires=...",
      "walking_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin.fbx?Expires=...",
      "walking_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Walking_withSkin_armature.glb?Expires=...",
      "running_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.glb?Expires=...",
      "running_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin.fbx?Expires=...",
      "running_armature_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018b314a-a1b5-716d-c222-2f1776f7f579/output/Animation_Running_withSkin_armature.glb?Expires=..."
    }
  },
  "preceding_tasks": 0
}