API do Riggingu

API do Riggingu pozwala na programatyczne dodanie szkieletu (armatury) do humanoidalnych modeli 3D, wiążąc z nim siatkę, aby były gotowe do animacji. Aby zastosować animacje do postaci z riggingiem, zobacz API Animacji.

Proszę zauważyć, że programatyczny rigging obecnie działa dobrze tylko z standardowymi humanoidalnymi (dwunożnymi) assetami z wyraźnie zdefiniowanymi kończynami i strukturą ciała.

POST/openapi/v1/rigging

Utwórz Zadanie Rigging

Ten punkt końcowy pozwala na utworzenie nowego zadania rigging dla danego modelu 3D. Po pomyślnym zakończeniu, dostarcza postać z riggingiem w standardowych formatach i opcjonalnie podstawowe animacje chodzenia/biegania.

Obecnie automatyczny rigging nie jest odpowiedni dla następujących modeli:

Siatki bez tekstur
Niehumanoidalne zasoby
Humanoidalne zasoby z niejasną strukturą kończyn i ciała

Podczas korzystania z input_task_id, modele z więcej niż 300,000 ścianami nie są obsługiwane do riggingu. Proszę użyć Remesh API w celu zmniejszenia liczby ścian przed riggingiem.

Podczas korzystania z model_url, twarz postaci musi być skierowana w stronę osi +Z (standardowy kierunek do przodu glTF). Modele skierowane w inne osie nie przejdą estymacji pozycji.

Parametry

Tylko jeden z input_task_id lub model_url jest wymagany. Jeśli oba są podane, input_task_id ma priorytet.

Name
input_task_id
Type
string
Wymagane
Description
Zadanie wejściowe, które wymaga riggingu. Obecnie obsługujemy humanoidalne modele z teksturami.

Name
model_url
Type
string
Wymagane
Description
Proszę dostarczyć model 3D do riggingu przez Meshy za pomocą publicznie dostępnego URL lub Data URI. Obecnie obsługujemy humanoidalne pliki GLB z teksturami (format .glb).

Name
height_meters
Type
number
domyślne 1.7
Description
Przybliżona wysokość modelu postaci w metrach. Pomaga w skalowaniu i dokładności riggingu. Musi być liczbą dodatnią.
Name
texture_image_url
Type
string
Description
Obraz tekstury bazowego koloru modelu z rozwinięciem UV. Publicznie dostępny URL lub Data URI. Obecnie obsługujemy formaty .png.

Zwraca

Właściwość result odpowiedzi zawiera id nowo utworzonego zadania rigging.

Tryby awarii

Name
400 - Bad Request
Description
Żądanie było nieakceptowalne. Typowe przyczyny:
- Brakujący parametr: Należy podać model_url lub input_task_id.
- Nieprawidłowy format modelu: model_url wskazuje na plik z nieobsługiwanym rozszerzeniem (obsługiwane tylko .glb).
- Nieosiągalny URL: model_url nie mógł zostać pobrany.
- Nieprawidłowe zadanie wejściowe: input_task_id nie odnosi się do prawidłowego zadania API.
- Przekroczona liczba ścian: Model wejściowy ma więcej niż 300,000 ścian. Proszę użyć Remesh API w celu zmniejszenia liczby ścian przed riggingiem.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Proszę sprawdzić swój klucz API.
Name
402 - Payment Required
Description
Niewystarczająca liczba kredytów do wykonania tego zadania.
Name
422 - Unprocessable Entity
Description
Estymacja pozycji nie powiodła się. Dostarczony model może nie być prawidłową postacią humanoidalną.
Name
429 - Too Many Requests
Description
Przekroczyłeś swój limit szybkości.

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

Pobierz zadanie riggingu

Ten punkt końcowy pozwala na pobranie zadania riggingu, podając prawidłowy id zadania. Odwołaj się do Obiektu Zadania Riggingu, aby zobaczyć, które właściwości są uwzględnione.

Parametry

Name
id
Type
path
Description
Unikalny identyfikator dla zadania riggingu do pobrania.

Zwraca

Odpowiedź zawiera obiekt Zadania Riggingu. Sprawdź sekcję Obiekt Zadania Riggingu dla szczegółów.

Żądanie

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

Odpowiedź

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

Usuń zadanie riggingu

Ten punkt końcowy trwale usuwa zadanie riggingu, w tym wszystkie powiązane modele i dane. Ta akcja jest nieodwracalna.

Parametry ścieżki

Name
id
Type
path
Description
ID zadania riggingu do usunięcia.

Zwraca

Zwraca 200 OK w przypadku powodzenia.

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

Lista zadań riggingowych

Zwraca stronicowaną listę zadań riggingowych użytkownika, od najnowszych. Standardowe stronicowanie za pomocą page_num i page_size.

Należy pamiętać, że zadania utworzone za pośrednictwem API są zarządzane przez API — nie pojawiają się w sekcji Moje zasoby aplikacji webowej. Użyj tego punktu końcowego, aby znaleźć zadanie, którego ID już nie posiadasz.

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

Streamowanie zadania Rigging

Ten punkt końcowy przesyła w czasie rzeczywistym aktualizacje dla zadania Rigging przy użyciu Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator dla zadania Rigging do streamowania.

Zwraca

Zwraca strumień Obiektów zadania Rigging jako Server-Sent Events.

Dla zadań PENDING lub IN_PROGRESS, strumień odpowiedzi będzie zawierał tylko niezbędne pola progress i status.

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
}

Obiekt Zadania Riggingu

Obiekt Zadania Riggingu reprezentuje jednostkę pracy dla riggingu postaci.

Właściwości

Name
id
Type
string
Description
Unikalny identyfikator zadania.
Name
type
Type
string
Description
Typ zadania Riggingu. Wartość to rig.
Name
status
Type
string
Description
Status zadania. Możliwe wartości: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress zadania (0-100). 0 jeśli nie rozpoczęto, 100 jeśli zakończono sukcesem.
Name
created_at
Type
timestamp
Description
Znacznik czasu (milisekundy od epoki) kiedy zadanie zostało utworzone.
Znacznik czasu reprezentuje liczbę milisekund, które upłynęły od 1 stycznia 1970 UTC, zgodnie ze standardem RFC 3339. Na przykład, piątek, 1 września 2023 12:00:00 GMT jest reprezentowany jako 1693569600000. Dotyczy to wszystkich znaczników czasu w Meshy API.
Name
started_at
Type
timestamp
Description
Znacznik czasu (milisekundy od epoki) kiedy zadanie rozpoczęło przetwarzanie. 0 jeśli nie rozpoczęto.
Name
finished_at
Type
timestamp
Description
Znacznik czasu (milisekundy od epoki) kiedy zadanie zakończyło się. 0 jeśli nie zakończono.
Name
expires_at
Type
timestamp
Description
Znacznik czasu (milisekundy od epoki) kiedy wynikowe zasoby zadania wygasają i mogą zostać usunięte.
Name
task_error
Type
object
Description
Szczegóły błędu dla nieudanych zadań. Zobacz Błędy dla pełnej referencji obiektu task_error.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. Obecne, gdy status zadania to PENDING, IN_PROGRESS lub SUCCEEDED. Zwraca 0 dla zadań FAILED (kredyty są zwracane w przypadku niepowodzenia).
Name
result
Type
object
Description
Zawiera URL-e zasobów wyjściowych, jeśli zadanie zakończyło się SUCCEEDED, null w przeciwnym razie.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  URL do pobrania postaci z riggingiem w formacie FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  URL do pobrania postaci z riggingiem w formacie GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Zawiera URL-e dla domyślnych animacji. (np. jeśli generate_basic_animations było domyślnie włączone lub aktywowane).
  Name
  walking_glb_url
  Type
  string
  Description
  URL do pobrania animacji chodzenia w formacie GLB (ze skórą).
  Name
  walking_fbx_url
  Type
  string
  Description
  URL do pobrania animacji chodzenia w formacie FBX (ze skórą).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  URL do pobrania armatury animacji chodzenia w formacie GLB.
  Name
  running_glb_url
  Type
  string
  Description
  URL do pobrania animacji biegania w formacie GLB (ze skórą).
  Name
  running_fbx_url
  Type
  string
  Description
  URL do pobrania animacji biegania w formacie FBX (ze skórą).
  Name
  running_armature_glb_url
  Type
  string
  Description
  URL do pobrania armatury animacji biegania w formacie GLB.
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań w kolejce. Znaczące tylko, jeśli status to PENDING.

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
}