Rigging API

Rigging API, 3D insansı modellere programatik olarak bir iskelet (iskelet) eklemenizi ve ağı buna bağlayarak modelleri animasyona hazır hale getirmenizi sağlar. İskeletlenmiş bir karaktere animasyon uygulamak için Animation API sayfasına bakın.

Lütfen unutmayın ki programatik iskeletleme şu anda yalnızca uzuvları ve vücut yapısı açıkça tanımlanmış standart insansı (iki ayaklı) varlıklarla iyi çalışmaktadır.

POST/openapi/v1/rigging

Rigging Görevi Oluşturma

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

Görev arka planda çalışır. Genellikle ne kadar sürdüğü hakkında bilgi için bkz. İşlem Süreleri.

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

Dokusuz ağlar
İnsan biçimli olmayan varlıklar
Kol/bacak ve vücut yapısı belirsiz insan biçimli varlıklar

input_task_id kullanırken, 300.000 yüzeyden fazla olan modeller rigging için desteklenmez. Rigging öncesinde yüzey sayısını azaltmak için lütfen Yeniden Ağ API'sini kullanın.

model_url kullanırken, karakterin yüzü +Z eksenine bakmalıdır (standart glTF ileri yönü). Başka eksenlere bakan modeller poz tahmininde başarısız olur.

Parametreler

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

Name
input_task_id
Type
string
Zorunlu
Description
Rig'lenmesi gereken girdi görevi. Şu anda dokulu insan biçimli modelleri destekliyoruz.

Name
model_url
Type
string
Zorunlu
Description
Lütfen Meshy'nin rig'lemesi için herkese açık erişilebilir bir URL veya Data URI aracılığıyla bir 3D model sağlayın. Şu anda dokulu insan biçimli GLB dosyalarını (.glb formatı) destekliyoruz.
Maksimum dosya boyutu: http veya https URL'si için 400 MB, data: URI'si için 100 MB.
10.000.000'dan fazla yüzeye sahip 100 MB'den büyük bir dosya 400 döndürür. Yüzeyler üçgen olarak sayılır ve birden fazla çizilen bir ağ, kopya başına bir kez sayılır. 100 MB'den büyük bir GLB, Draco sıkıştırması kullanmamalıdır.

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ımlı taban rengi doku görüntüsü. Herkese açık erişilebilir URL veya Data URI. Şu anda .png formatlarını destekliyoruz.
Maksimum dosya boyutu: 20 MB.

Dönüş Değerleri

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

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemedi. 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 (yalnızca .glb desteklenir).
- Ulaşılamayan URL: model_url indirilemedi.
- Model dosyası çok büyük: model_url dosyası 400 MB'yi (http veya https URL'si) veya 100 MB'yi (data: URI'si) aşıyor.
- Çok fazla yüzey: model_url dosyası 100 MB'den büyük ve 10.000.000'dan fazla yüzeye sahip. Yüzey sayısını azaltın, ardından dosyayı tekrar gönderin.
- Okunamayan model dosyası: model_url dosyası 100 MB'den büyük ve başlığı okunamıyor, örneğin Draco sıkıştırmalı bir GLB.
- Model başlığı çok karmaşık: model_url dosyası 100 MB'den büyük ve başlığında kontrol edilecek çok fazla ağ, düğüm veya kayıt var. Dosyadaki nesne sayısını azaltın, ardından tekrar gönderin.
- Görüntü çok büyük: texture_image_url görüntüsü 20 MB'yi aşıyor.
- Geçersiz girdi görevi: input_task_id, geçerli bir API görevine işaret etmiyor.
- Yüzey sayısı aşıldı: Girdi modeli 300.000'den fazla yüzeye sahip. Rigging öncesinde yüzey sayısını azaltmak için lütfen 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 biçimli 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 Rigging Görevini Getir

Bu uç nokta, geçerli bir görev id değeri verildiğinde bir rigging görevini almanızı sağlar. Hangi özelliklerin dahil edildiğini görmek için Rigging Görevi Nesnesi bölümüne bakın.

Parametreler

Name
id
Type
path
Description
Alınacak rigging görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

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

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.

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.

Son durumda olan bir görev (SUCCEEDED, FAILED veya CANCELED) iade yapılmadan silinir.

Dönüş Değerleri

Başarılı olduğunda 200 OK, görev IN_PROGRESS durumundaysa 409 Conflict 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

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

Rigging Görevlerini Listele

Çağıranın rigging görevlerinin, en yeniden en eskiye doğru sıralanmış, sayfalanmış bir listesini döndürür. page_num ve page_size üzerinden standart sayfalama uygulanı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/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 Akışa Alma

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

Parametreler

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

Dönüş Değerleri

Server-Sent Events olarak Rigging Görevi Nesnelerinin bir 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/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
}

Rigging Görevi Nesnesi

Rigging Görevi nesnesi, bir karakteri rigging işlemine tabi tutmak 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 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ü saat 12:00:00 GMT, 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.
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 dolup silinebileceği 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ı. 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 mevcuttur. FAILED görevler için 0 döndürür (başarısızlık durumunda krediler iade edilir).
Name
result
Type
object
Description
Görev SUCCEEDED durumundaysa çıktı varlık URL'lerini içerir, aksi takdirde null değerini alır.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  FBX formatında rig uygulanmış karakter için indirilebilir URL.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  GLB formatında rig uygulanmış karakter için indirilebilir URL.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Varsayılan animasyonlar için URL'leri içerir. (ör. generate_basic_animations örtük olarak true ise veya varsayılan olarak etkinleştirilmişse).
  Name
  walking_glb_url
  Type
  string
  Description
  GLB formatında (deri ile) yürüme animasyonu için indirilebilir URL.
  Name
  walking_fbx_url
  Type
  string
  Description
  FBX formatında (deri ile) yürüme animasyonu için indirilebilir URL.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  GLB formatında yürüme animasyonu iskeleti için indirilebilir URL.
  Name
  running_glb_url
  Type
  string
  Description
  GLB formatında (deri ile) koşma animasyonu için indirilebilir URL.
  Name
  running_fbx_url
  Type
  string
  Description
  FBX formatında (deri ile) koşma animasyonu için indirilebilir URL.
  Name
  running_armature_glb_url
  Type
  string
  Description
  GLB formatında koşma animasyonu iskeleti için indirilebilir URL.
Name
preceding_tasks
Type
integer
Description
Kuyruktaki önceki görevlerin sayısı. Yalnızca durum PENDING olduğunda 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
}