Rigging API

İnsansı bir 3D modele iskelet ekleyin ve ağı bu iskelete bağlayın, böylece karakter animasyona hazır hale gelir. Riglenmiş bir karaktere animasyon uygulamak için Animation API bölümüne bakın.

Rigging, yalnızca net bir şekilde tanımlanmış uzuv ve vücut yapısına sahip standart insansı (iki ayaklı) karakterlerle iyi çalışır.

POST/openapi/v1/rigging

Rigging görevi oluştur

Bir 3D model için Rigging görevi oluşturur. Görev başarılı olduğunda, standart formatlarda rig'lenmiş bir karakter ve isteğe bağlı olarak temel yürüme ve koşma animasyonları döndürür.

Görev arka planda çalışır. Bir görevin genellikle ne kadar sürdüğü için bkz. İşleme süreleri.

Rigging şu modeller için uygun değildir:

Dokusuz ağlar
İnsan biçimli olmayan assetler
Kol, bacak ve gövde yapısı net olmayan insan biçimli assetler

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

Parametreler

Name
input_task_id
Type
string
Zorunlu
Description
model_url göndermediğiniz sürece zorunludur. Modelini rig'lemek istediğiniz görevin ID'si. Meshy, dokulu insan biçimli modelleri destekler.
Model en fazla 380.000 üçgene sahip olabilir (bir dörtgen 2 olarak sayılır); daha fazlasına sahip bir model 400 döndürür. Bu sınırın altında kalmak için önce üzerinde target_polycount değeri 300000 veya daha az, ya da topology: quad ile 150000 veya daha az olacak şekilde Remesh API'ini çalıştırın.

Name
model_url
Type
string
Zorunlu
Description
input_task_id göndermediğiniz sürece zorunludur. Rig'lenecek model; genel bir URL veya bir data URI olarak. İkisini de gönderirseniz, Meshy input_task_id'yi kullanır.
Model, http veya https URL'sinden en fazla 400 MB, ya da data URI olarak en fazla 100 MB büyüklüğünde bir GLB (.glb) dosyası olmalıdır. Rigging, dokulu insan biçimli modelleri destekler.
Model en fazla 380.000 üçgene sahip olabilir (bir dörtgen 2 olarak sayılır); daha fazlasına sahip bir model 400 döndürür. Bu sınırın altında kalmak için önce üzerinde target_polycount değeri 300000 veya daha az, ya da topology: quad ile 150000 veya daha az olacak şekilde Remesh API'ini çalıştırın.
Karakterin yüzü, standart glTF ileri yönü olan +Z eksenine bakmalıdır. Başka bir eksene bakan bir model için poz tahmini başarısız olur.
100 MB'ı aşan bir dosya ayrıca şu kurallara da uymalıdır:
- En fazla 10.000.000 yüzeye sahip olabilir. Daha fazlasına sahip bir dosya 400 döndürür. Meshy yüzeyleri üçgen olarak sayar ve birden fazla kez çizilen bir ağ, her kopya için bir kez sayılır.
- Draco sıkıştırması kullanmamalıdır.

Name
height_meters
Type
number
varsayılan 1.7
Description
Karakterin yaklaşık boyu, metre cinsinden. Meshy, modeli daha doğru ölçeklendirmek ve rig'lemek için bunu kullanır. Negatif bir değer 400 döndürür.
Name
texture_image_url
Type
string
⚠ kullanımdan kaldırıldı
Description
Modelin kendi dokuları varsa bunu dahil etmeyin. Bu olmadan, Meshy model_url dosyasına gömülü dokuları veya girdi görevinin dokularını kullanır. Bunu gönderirseniz, bu görsel rig'lenmiş modelin tek dokusu olur ve model PBR haritalarını kaybeder.
Modelin UV açılımlı taban rengi dokusu, genel bir URL veya bir data URI olarak. Görsel en fazla 20 MB büyüklüğünde bir PNG dosyası olmalıdır. Başka bir görsel formatı 400 döndürür.

Dönüş değerleri

Yanıtın result alanı, yeni Rigging görevinin ID'sini tutar.

Hata modları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Hata mesajı hangi sorunun bulunduğunu belirtir. Örneğin:
- Eksik parametre: Ne model_url ne de input_task_id gönderildi.
- Geçersiz model formatı: model_url dosyasının desteklenmeyen bir uzantısı var. Yalnızca .glb desteklenir.
- Erişilemeyen URL: Meshy, model_url dosyasını indiremiyor.
- Model dosyası çok büyük: model_url dosyası, http veya https URL'sinden 400 MB'ın üzerinde, ya da data URI olarak 100 MB'ın üzerinde.
- Çok fazla yüzey: model_url dosyası 100 MB'ın üzerinde ve 10.000.000'dan fazla yüzeye sahip. Yüzey sayısını azaltıp dosyayı tekrar gönderin.
- Okunamayan model dosyası: model_url dosyası 100 MB'ın üzerinde ve Meshy başlığını okuyamıyor. Örneğin, Draco ile sıkıştırılmış bir GLB.
- Model başlığı çok karmaşık: model_url dosyası 100 MB'ın üzerinde ve başlığı kontrol edilemeyecek kadar çok sayıda ağ, düğüm veya kayıt içeriyor. Dosyadaki nesne sayısını azaltıp tekrar gönderin.
- Görsel çok büyük: texture_image_url görseli 20 MB'ın üzerinde.
- Geçersiz doku formatı: texture_image_url görseli bir PNG dosyası değil.
- Geçersiz boy: height_meters negatif.
- Geçersiz girdi görevi: input_task_id, geçerli bir API görevine işaret etmiyor.
- Girdi görevi hazır değil: input_task_id görevi SUCCEEDED durumuna ulaşmadı. Başarılı olana kadar bekleyip tekrar deneyin.
- Yüzey sayısı aşıldı: Girdi modeli 380.000'den fazla üçgene sahip (bir dörtgen 2 olarak sayılır). Modeli rig'lemeden önce üzerinde target_polycount değeri 300000 veya daha az, ya da topology: quad ile 150000 veya daha az olacak şekilde Remesh API'ini çalıştırın.
İsteği düzeltip tekrar gönderin. Bkz. Hatalar.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Örneğin:
- Yetersiz kredi: Hesapta bu görev için yeterli kredi yok, veya hesap bir kredi limitine ulaştı. Kredi bakiyenizi kontrol edip tekrar deneyin.
- Ücretsiz plan: Görev oluşturmak için ücretli bir plan gereklidir. Abonelik ayarlarınızdan planınızı yükseltip tekrar deneyin.
Name
403 - Forbidden
Description
input_task_id, bu uç noktanın rig'leyemediği bir kabartma (bas-relief) modeldir. Mesaj This model type does not support this operation şeklindedir. Farklı bir model gönderin.
Name
404 - Not Found
Description
Meshy, input_task_id görevinin dosyalarını bulamıyor. Bunlardan biri geçerlidir:
- Meshy, expires_at sonrasında görevin dosyalarını sildi. Görevi tekrar oluşturup o görevin ID'sini gönderin.
- Görev, rigging'in ihtiyaç duyduğu dosyaların hiçbirine sahip değil, örneğin bir önizleme görseline; örneğin bir Convert görevi. Geldiği görevi rig'leyin veya modeli model_url olarak gönderin.
Name
422 - Unprocessable Entity
Description
Poz tahmini başarısız oldu. Model geçerli bir insan biçimli karakter olmayabilir. İnsan biçimli bir karakter modeli gönderin. model_url için ayrıca karakterin +Z eksenine baktığını kontrol edin.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız. Bekleyip tekrar deneyin. Bkz. Hız sınırları.

GET/openapi/v1/rigging/:id

Rigging görevi al

ID'sine göre bir Rigging görevini döndürür.

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": null,
  "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=..."
    }
  }
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev ID'si.

Dönen Değerler

Rigging görevi nesnesi.

DELETE/openapi/v1/rigging/:id

Rigging görevini sil

Bir Rigging görevini, modelleri ve verileri dahil olmak üzere kalıcı olarak siler. Bir silme işlemini geri alamazsınız.

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

Yol parametreleri

Name
id
Type
path
Description
Silinecek görevin kimliği.

Görev durumu

PENDING durumundaki bir görevi silmek, görevi oluştururken kullanılan kredileri iade eder.

IN_PROGRESS durumundaki bir görev silinemez. İstek 409 Conflict döner ve görev çalışmaya devam eder. Meshy, başlamış olan bir görev için iade yapmaz, bu yüzden onu silmek hem kredilerinizi hem de sonucu kaybetmenize neden olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Nihai bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görevi silmek kredilerini iade etmez.

Dönüş değerleri

Görev silindiğinde 200 OK, görev IN_PROGRESS durumundayken 409 Conflict döner.

GET/openapi/v1/rigging

Rigging görevlerini listele

En yeniden en eskiye doğru sıralanmış Rigging görevlerinizin sayfalanmış bir listesini döndürür. Liste içinde sayfalar arasında gezinmek için page_num ve page_size kullanın.

API ile oluşturduğunuz görevler API içinde kalır ve web uygulamasındaki My Assets 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.

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

Rigging görevini akışa aktar (stream)

Bir Rigging görevinin güncellemelerini Server-Sent Events (SSE) olarak akışa aktarır.

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.
// These examples are shortened. Each event holds the full task object.
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 event, with the same fields as the 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": null,
  "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?..."
    }
  }
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev kimliği.

Dönüş Değerleri

Rigging görevi nesnelerinin Server-Sent Events olarak akışı.

Her olay, Get uç noktasının döndürdüğü ile aynı biçimde, tam görev nesnesini içerir. Görev PENDING veya IN_PROGRESS durumundayken, sonuç alanlarının henüz değeri yoktur.

Rigging görev nesnesi

Bir Rigging görev nesnesi, bir karakterin rigging işlemini tanımlar. Görev başarılı olduğunda durumu, progress bilgisini ve çıktı dosyalarını tutar.

Özellikler

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": null,
  "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=..."
    }
  }
}

Name
id
Type
string
Description
Görev kimliği. Bunu opak bir dize olarak değerlendirin ve biçimine güvenmeyin.
Name
type
Type
string
Description
Görev türü, her zaman rig.
Name
status
Type
string
Description
Görev durumu; PENDING, IN_PROGRESS, SUCCEEDED, FAILED veya CANCELED değerlerinden biridir.
Name
progress
Type
integer
Description
Görevin ne kadarının tamamlandığı, yüzde olarak. Görev başlayana kadar 0, başarılı olduğunda 100 değerindedir.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman, Unix milisaniye cinsinden.
Name
started_at
Type
timestamp
Description
Görevin başladığı zaman, Unix milisaniye cinsinden. Görev başlayana kadar 0 değerindedir.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman, Unix milisaniye cinsinden. Görev tamamlanana kadar 0 değerindedir.
Name
expires_at
Type
timestamp
Description
Görevin sonuç dosyalarının süresinin dolacağı zaman, Unix milisaniye cinsinden. Bu zamandan sonra Meshy dosyaları silebilir.
Name
task_error
Type
object
Description
Görev başarısız olduğunda hata ayrıntıları. Durum FAILED olmadığı sürece null değerindedir. Bkz. Hatalar.
Name
consumed_credits
Type
integer
Description
Görevin kullandığı kredi sayısı. Durum PENDING, IN_PROGRESS veya SUCCEEDED olduğunda mevcuttur. FAILED bir görev için 0 değerindedir, çünkü Meshy bir görev başarısız olduğunda kredileri iade eder.
Name
result
Type
object
Description
Çıktı dosyası URL'leri. Görev başarılı olana kadar her URL boş bir dizedir ve basic_animations değeri null'dır.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Rig uygulanmış karakterin FBX dosyası olarak indirme URL'si.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Rig uygulanmış karakterin GLB dosyası olarak indirme URL'si.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Varsayılan yürüme ve koşma animasyonları için indirme URL'leri.
  Name
  walking_glb_url
  Type
  string
  Description
  Deri (skin) ile birlikte yürüme animasyonu, GLB dosyası olarak.
  Name
  walking_fbx_url
  Type
  string
  Description
  Deri (skin) ile birlikte yürüme animasyonu, FBX dosyası olarak.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Yürüme animasyonunun iskeleti, GLB dosyası olarak.
  Name
  running_glb_url
  Type
  string
  Description
  Deri (skin) ile birlikte koşma animasyonu, GLB dosyası olarak.
  Name
  running_fbx_url
  Type
  string
  Description
  Deri (skin) ile birlikte koşma animasyonu, FBX dosyası olarak.
  Name
  running_armature_glb_url
  Type
  string
  Description
  Koşma animasyonunun iskeleti, GLB dosyası olarak.
Name
preceding_tasks
Type
integer
Description
Kuyrukta bu görevden önce gelen görev sayısı. Bu değer yalnızca görev PENDING durumundayken anlamlıdır. Değer 0 olduğunda bu alan dahil edilmez.