Rigging API

Rigging API, 3D insansı modellere programlı olarak bir iskelet (iskelet) eklemenizi sağlar, ağı ona bağlayarak animasyona hazır hale getirir. Rigging yapılmış bir karaktere animasyon uygulamak için Animasyon API sayfasına bakın.

Lütfen dikkat edin ki, programlı rigging şu anda yalnızca standart insansı (iki ayaklı) ve açıkça tanımlanmış uzuvlar ve vücut yapısına sahip varlıklarla iyi çalışmaktadır.

POST/openapi/v1/rigging

Bir Rigging Görevi Oluştur

Bu uç nokta, belirli bir 3D model için yeni bir rigging görevi oluşturmanıza olanak tanır. Başarıyla tamamlandığında, standart formatlarda rig edilmiş 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:

Dokulandırılmamış ağlar
İnsan benzeri olmayan varlıklar
Belirsiz uzuv ve vücut yapısına sahip insan benzeri varlıklar

input_task_id kullanıldığında, 300.000'den fazla yüz içeren modeller rigging için desteklenmez. Lütfen yüz sayısını azaltmak için Yeniden Ağ API'sini kullanın.

model_url kullanıldığında, karakterin yüzü +Z eksenine (standart glTF ileri yönü) bakmalıdır. Diğer eksenlere bakan modeller poz tahmininde başarısız olacaktır.

Parametreler

input_task_id veya model_url'dan yalnızca biri gereklidir. Her ikisi de sağlanırsa, input_task_id önceliklidir.

Name
input_task_id
Type
string
Zorunlu
Description
Rig edilmesi gereken giriş görevi. Şu anda dokulandırılmış insan benzeri modelleri destekliyoruz.

Name
model_url
Type
string
Zorunlu
Description
Meshy'nin rig etmesi için genel olarak erişilebilir bir URL veya Data URI aracılığıyla bir 3D model sağlayın. Şu anda dokulandırılmış insan benzeri GLB dosyalarını (.glb formatı) destekliyoruz.

Name
height_meters
Type
number
varsayılan 1.7
Description
Karakter modelinin yaklaşık yüksekliği metre cinsindendir. Bu, ölçekleme ve rigging doğruluğuna yardımcı olur. Pozitif bir sayı olmalıdır.
Name
texture_image_url
Type
string
Description
Modelin UV-açılmış temel renk doku görüntüsü. Genel olarak 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 id değerini içerir.

Başarısızlık Modları

Name
400 - Bad Request
Description
İstek kabul edilemezdi. Yaygın nedenler:
- Eksik parametre: model_url veya input_task_id'den biri sağlanmalıdır.
- Geçersiz model formatı: model_url, desteklenmeyen bir uzantıya sahip bir dosyaya işaret ediyor (sadece .glb desteklenir).
- Ulaşılamaz URL: model_url indirilemedi.
- Geçersiz giriş görevi: input_task_id, geçerli bir API görevine atıfta bulunmuyor.
- Yüz sayısı aşıldı: Giriş modeli 300.000'den fazla yüze sahip. Lütfen rigging öncesinde yüz sayısını azaltmak için Yeniden Ağ API'sini 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 insan benzeri karakter olmayabilir.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

İstek

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
  }'

Yanıt

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

GET/openapi/v1/rigging/:id

Bir Rigging Görevini Al

Bu uç nokta, geçerli bir görev id verildiğinde bir rigging görevini almanıza olanak tanır. Hangi özelliklerin dahil edildiğini görmek için Rigging Görev Nesnesi bölümüne bakın.

Parametreler

Name
id
Type
path
Description
Alınacak rigging görevinin benzersiz tanımlayıcısı.

Dönen Değerler

Yanıt, Rigging Görev nesnesini içerir. Detaylar için Rigging Görev Nesnesi bölümüne bakın.

İstek

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

Yanıt

{
  "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, bir rigging görevini, ilgili tüm modeller ve veriler dahil olmak üzere 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öner.

İstek

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

Yanıt

// Returns 200 Ok on success.

GET/openapi/v1/rigging

Rigging Görevlerini Listele

Çağrıcının rigging görevlerinin sayfalanmış bir listesini, en yeniler önce olacak şekilde döndürür. page_num ve page_size ile standart sayfalama.

API aracılığıyla oluşturulan görevlerin API üzerinden yönetildiğini unutmayın — bunlar web uygulamasının Varlıklarım bölümünde görünmez. Artık kimliğine sahip olmadığınız bir görevi bulmak için bu uç noktayı kullanın.

İstek

GET

/openapi/v1/rigging

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

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

Bir Rigging Görevini Yayınla

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir Rigging görevi için gerçek zamanlı güncellemeler yayınlar.

Parametreler

Name
id
Type
path
Description
Yayınlanacak Rigging görevi için benzersiz tanımlayıcı.

Dönen Değerler

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

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

İstek

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

Yanıt Akışı

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

Rigging Görev Nesnesi

Rigging Görev nesnesi, bir karakterin rigging işlemi 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 olarak belirlenmiştir.
Name
status
Type
string
Description
Görevin durumu. Olası değerler: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Görevin ilerleme durumu (0-100). Başlamadıysa 0, başarılıysa 100.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman damgası (epoch'tan itibaren milisaniye cinsinden).
Bir zaman damgası, 1 Ocak 1970 UTC'den itibaren geçen milisaniye sayısını temsil eder ve RFC 3339 standardını takip eder. Örneğin, Cuma, 1 Eylül 2023 12:00:00 PM GMT, 1693569600000 olarak temsil edilir. Bu, 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 itibaren milisaniye cinsinden). Başlamadıysa 0.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman damgası (epoch'tan itibaren milisaniye cinsinden). Tamamlanmadıysa 0.
Name
expires_at
Type
timestamp
Description
Görev sonucu varlıklarının süresinin dolduğu ve silinebileceği zaman damgası (epoch'tan itibaren milisaniye cinsinden).
Name
task_error
Type
object
Description
Başarısız görevler için hata detayları. Tam 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 mevcut. 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 ise çıktı varlık URL'lerini içerir, aksi takdirde null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  FBX formatında rigging yapılmış karakter için indirilebilir URL.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  GLB formatında rigging yapılmış karakter için indirilebilir URL.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Varsayılan animasyonlar için URL'leri içerir. (örneğin, generate_basic_animations dolaylı olarak doğruysa veya varsayılan olarak etkinleştirilmişse).
  Name
  walking_glb_url
  Type
  string
  Description
  GLB formatında yürüyüş animasyonu için indirilebilir URL (deri ile birlikte).
  Name
  walking_fbx_url
  Type
  string
  Description
  FBX formatında yürüyüş animasyonu için indirilebilir URL (deri ile birlikte).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  GLB formatında yürüyüş animasyonu iskeleti için indirilebilir URL.
  Name
  running_glb_url
  Type
  string
  Description
  GLB formatında koşu animasyonu için indirilebilir URL (deri ile birlikte).
  Name
  running_fbx_url
  Type
  string
  Description
  FBX formatında koşu animasyonu için indirilebilir URL (deri ile birlikte).
  Name
  running_armature_glb_url
  Type
  string
  Description
  GLB formatında koşu 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.

Örnek Rigging Görev Nesnesi

{
  "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
}