Rigging API

Rigging API umożliwia programowe dodawanie szkieletu (armatury) do humanoidalnych modeli 3D oraz powiązanie siatki z nim, aby były gotowe do animacji. Informacje na temat stosowania animacji do modelu z rigiem znajdziesz w Animation API.

Pamiętaj, że programowy rigging obecnie dobrze działa jedynie w przypadku standardowych humanoidalnych (dwunożnych) assetów z wyraźnie określonymi kończynami i strukturą ciała.

POST/openapi/v1/rigging

Create a Rigging Task

Ten punkt końcowy umożliwia utworzenie nowego zadania riggingu dla danego modelu 3D. Po pomyślnym zakończeniu zwraca ozriggowaną postać w standardowych formatach oraz opcjonalnie podstawowe animacje chodzenia/biegania.

Zadanie jest wykonywane w tle. Informacje o tym, ile zwykle to trwa, znajdziesz w sekcji Czasy przetwarzania.

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

Siatki bez tekstur
Zasoby nieczłekokształtne
Zasoby człekokształtne o niejasnej strukturze kończyn i ciała

Podczas korzystania z input_task_id, modele z więcej niż 300 000 wielokątów nie są obsługiwane w procesie riggingu. Skorzystaj z Remesh API, aby zmniejszyć liczbę wielokątów przed riggingiem.

Podczas korzystania z model_url, twarz postaci musi być skierowana w kierunku osi +Z (standardowy kierunek „do przodu” w glTF). Modele skierowane w stronę innych osi spowodują niepowodzenie estymacji pozy.

Parametry

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

Name
input_task_id
Type
string
Wymagane
Description
Zadanie wejściowe, które ma zostać poddane riggingowi. Obecnie obsługujemy teksturowane modele człekokształtne.

Name
model_url
Type
string
Wymagane
Description
Podaj model 3D, który ma zostać poddany riggingowi przez Meshy, za pomocą publicznie dostępnego adresu URL lub Data URI. Obecnie obsługujemy teksturowane pliki GLB postaci człekokształtnych (format .glb).
Maksymalny rozmiar pliku: 400 MB dla adresu URL http lub https, 100 MB dla URI typu data:.
Plik większy niż 100 MB z ponad 10 000 000 wielokątów zwraca błąd 400. Wielokąty liczone są jako trójkąty, a siatka narysowana więcej niż raz liczona jest raz na każdą kopię. Plik GLB większy niż 100 MB nie może korzystać z kompresji Draco.

Name
height_meters
Type
number
domyślne 1.7
Description
Przybliżona wysokość modelu postaci w metrach. Ułatwia to skalowanie i dokładność riggingu. Musi to być liczba dodatnia.
Name
texture_image_url
Type
string
Description
Obraz tekstury bazowego koloru modelu, rozwinięty w przestrzeni UV. Publicznie dostępny adres URL lub Data URI. Obecnie obsługujemy format .png.
Maksymalny rozmiar pliku: 20 MB.

Zwracane dane

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

Tryby niepowodzenia

Name
400 - Bad Request
Description
Żądanie było nieprawidłowe. 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ługiwany jest tylko .glb).
- Niedostępny adres URL: Nie udało się pobrać pliku spod model_url.
- Zbyt duży plik modelu: Plik wskazany przez model_url przekracza 400 MB (adres URL http lub https) lub 100 MB (URI data:).
- Zbyt duża liczba wielokątów: Plik wskazany przez model_url ma ponad 100 MB i więcej niż 10 000 000 wielokątów. Zmniejsz liczbę wielokątów, a następnie prześlij plik ponownie.
- Nieczytelny plik modelu: Plik wskazany przez model_url ma ponad 100 MB, a jego nagłówka nie można odczytać, na przykład w przypadku pliku GLB skompresowanego za pomocą Draco.
- Nagłówek modelu zbyt złożony: Plik wskazany przez model_url ma ponad 100 MB, a jego nagłówek zawiera zbyt wiele siatek, węzłów lub rekordów do sprawdzenia. Zmniejsz liczbę obiektów w pliku, a następnie prześlij go ponownie.
- Zbyt duży obraz: Obraz wskazany przez texture_image_url przekracza 20 MB.
- Nieprawidłowe zadanie wejściowe: input_task_id nie wskazuje na prawidłowe zadanie API.
- Przekroczona liczba wielokątów: Model wejściowy ma więcej niż 300 000 wielokątów. Skorzystaj z Remesh API, aby zmniejszyć liczbę wielokątów 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ą człekokształtną.
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 umożliwia pobranie zadania riggingu na podstawie prawidłowego id zadania. Zapoznaj się z sekcją Obiekt zadania riggingu, aby zobaczyć, jakie właściwości są uwzględnione.

Parametry

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

Zwracane wartości

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

Usuwanie zadania riggingu

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

Parametry ścieżki

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

Status zadania

Zadanie, które wciąż ma status PENDING, zostaje usunięte, a kredyty zużyte przy jego tworzeniu są zwracane.

Zadanie, które jest już IN_PROGRESS, nie może zostać usunięte: żądanie zostaje odrzucone z kodem 409 Conflict, a zadanie nadal działa. Kredyty za zadanie, które worker już zaczął przetwarzać, nie podlegają zwrotowi, więc usunięcie go w trakcie działania kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Zadanie w stanie końcowym (SUCCEEDED, FAILED lub CANCELED) zostaje usunięte bez zwrotu kredytów.

Zwraca

Zwraca 200 OK w przypadku powodzenia lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

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

List Rigging Tasks

Zwraca stronicowaną listę zadań riggingu wywołującego, od najnowszych. Standardowe stronicowanie za pomocą page_num i page_size.

Należy pamiętać, że zadania utworzone za pomocą API są zarządzane poprzez API — nie pojawiają się w sekcji Moje zasoby aplikacji webowej. Użyj tego punktu końcowego, aby znaleźć zadanie, którego identyfikator nie jest już dostępny.

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

Przesyłaj strumieniowo zadanie Rigging

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

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania Rigging do przesyłania strumieniowego.

Zwraca

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

W przypadku zadań o statusie 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 Rigging

Obiekt zadania Rigging reprezentuje jednostkę pracy związaną z riggingiem postaci.

Właściwości

Name
id
Type
string
Description
Unikalny identyfikator zadania.
Name
type
Type
string
Description
Typ zadania Rigging. 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
Postęp zadania (0-100). 0, jeśli nie rozpoczęto, 100, jeśli zakończono sukcesem.
Name
created_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) utworzenia zadania.
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 czasu GMT jest reprezentowany jako 1693569600000. Dotyczy to wszystkich znaczników czasu w Meshy API.
Name
started_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) rozpoczęcia przetwarzania zadania. 0, jeśli nie rozpoczęto.
Name
finished_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) zakończenia zadania. 0, jeśli nie zakończono.
Name
expires_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) wygaśnięcia zasobów wynikowych zadania, po którym mogą zostać usunięte.
Name
task_error
Type
object
Description
Szczegóły błędu dla nieudanych zadań. Pełny opis obiektu task_error znajdziesz w sekcji Błędy.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. Dostępne, 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 zasobów wyjściowych, jeśli zadanie zakończyło się SUCCEEDED, w przeciwnym razie null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Adres URL do pobrania postaci z riggingiem w formacie FBX.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Adres URL do pobrania postaci z riggingiem w formacie GLB.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Zawiera adresy URL dla domyślnych animacji. (np. jeśli generate_basic_animations było niejawnie ustawione na true lub włączone domyślnie).
  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 biegu w formacie GLB (ze skórą).
  Name
  running_fbx_url
  Type
  string
  Description
  Adres URL do pobrania animacji biegu w formacie FBX (ze skórą).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Adres URL do pobrania armatury animacji biegu 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
}