API riggingu

API riggingu pozwala programowo dodać szkielet (armaturę) 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.

Pamiętaj, że programowy rigging obecnie działa dobrze tylko ze standardowymi humanoidalnymi (dwunożnymi) assetami z wyraźnie zdefiniowanymi kończynami i strukturą ciała.

POST/openapi/v1/rigging

Utwórz zadanie riggingu

Ten punkt końcowy pozwala utworzyć nowe zadanie riggingu dla danego modelu 3D. Po pomyślnym ukończeniu udostępnia postać z riggingiem w standardowych formatach oraz opcjonalnie podstawowe animacje chodzenia/biegania.

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

Siatki bez tekstur
Assety niehumanoidalne
Assety humanoidalne z niejasną strukturą kończyn i ciała

Podczas używania input_task_id modele z ponad 300 000 ścian nie są obsługiwane w przypadku riggingu. Użyj Remesh API, aby zmniejszyć liczbę ścian przed riggingiem.

Podczas używania model_url twarz postaci musi być skierowana w stronę osi +Z (standardowy kierunek do przodu w glTF). Modele zwrócone w stronę innych osi nie przejdą estymacji pozy.

Parametry

Wymagany jest tylko jeden z input_task_id lub model_url. Jeśli podano oba, input_task_id ma priorytet.

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

Name
model_url
Type
string
Wymagane
Description
Podaj model 3D dla Meshy do riggingu za pomocą publicznie dostępnego adresu URL lub Data URI. Obecnie obsługujemy teksturowane pliki humanoidalne GLB (format .glb).

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

Zwraca

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

Tryby awarii

Name
400 - Bad Request
Description
Żądanie było nieakceptowalne. Typowe przyczyny:
- Brakujący parametr: Należy podać model_url albo input_task_id.
- Nieprawidłowy format modelu: model_url wskazuje plik z nieobsługiwanym rozszerzeniem (obsługiwane tylko .glb).
- Nieosiągalny URL: Nie można było pobrać model_url.
- 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. Użyj Remesh API, aby zmniejszyć liczbę ścian przed riggingiem.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.
Name
402 - Payment Required
Description
Niewystarczająca liczba kredytów do wykonania tego zadania.
Name
422 - Unprocessable Entity
Description
Estymacja pozy nie powiodła się. Podany model może nie być prawidłową postacią humanoidalną.
Name
429 - Too Many Requests
Description
Przekroczono 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 pobrać zadanie riggingu na podstawie prawidłowego id zadania. Zobacz Obiekt zadania riggingu, aby sprawdzić, które właściwości są uwzględnione.

Parametry

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

Zwraca

Odpowiedź zawiera obiekt zadania riggingu. Szczegóły znajdziesz w sekcji Obiekt zadania riggingu.

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

Usuń zadanie riggingu

Ten punkt końcowy trwale usuwa zadanie riggingu, w tym wszystkie powiązane modele i dane. Tej akcji nie można cofnąć.

Parametry ścieżki

Name
id
Type
path
Description
Identyfikator 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/:id/stream

Strumieniuj zadanie riggingu

Ten punkt końcowy strumieniuje aktualizacje w czasie rzeczywistym dla zadania riggingu przy użyciu Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania riggingu do strumieniowania.

Zwraca

Zwraca strumień obiektów zadania riggingu jako Server-Sent Events.

W przypadku 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 służącą do 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 powodzeniem.
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 PM 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 się zakończyło. 0, jeśli nie zakończono.
Name
expires_at
Type
timestamp
Description
Znacznik czasu (milisekundy od epoki), kiedy assety wyniku zadania wygasają i mogą zostać usunięte.
Name
task_error
Type
object
Description
Szczegóły błędu dla zadań zakończonych niepowodzeniem. Zobacz Błędy, aby uzyskać pełną referencję 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 adresy URL wyjściowych assetów, jeśli zadanie ma status SUCCEEDED, w przeciwnym razie null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Adres URL do pobrania postaci po riggingu w formacie FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Adres URL do pobrania postaci po riggingu w formacie GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Zawiera adresy URL domyślnych animacji. (np. jeśli generate_basic_animations było niejawnie true lub domyślnie włączone).
  Name
  walking_glb_url
  Type
  string
  Description
  Adres URL do pobrania animacji chodzenia w formacie GLB (ze skórą).
  Name
  walking_fbx_url
  Type
  string
  Description
  Adres URL do pobrania animacji chodzenia w formacie FBX (ze skórą).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Adres URL do pobrania armatury animacji chodzenia w formacie GLB.
  Name
  running_glb_url
  Type
  string
  Description
  Adres URL do pobrania animacji biegania w formacie GLB (ze skórą).
  Name
  running_fbx_url
  Type
  string
  Description
  Adres URL do pobrania animacji biegania w formacie FBX (ze skórą).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Adres URL do pobrania armatury animacji biegania w formacie GLB.
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań w kolejce. Ma znaczenie tylko wtedy, gdy 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
}