Rigging API

De Rigging API stelt je in staat om programmatisch een skelet (armature) toe te voegen aan 3D humanoïde modellen, waarbij de mesh eraan wordt gebonden zodat ze klaar zijn voor animatie. Voor het toepassen van animaties op een rigged karakter, zie de Animatie API.

Houd er rekening mee dat programmatisch rigging momenteel alleen goed werkt met standaard humanoïde (tweevoetige) assets met duidelijk gedefinieerde ledematen en lichaamsstructuur op dit moment.

POST/openapi/v1/rigging

Maak een Rigging Taak

Deze endpoint stelt je in staat om een nieuwe rigging taak te creëren voor een gegeven 3D-model. Bij succesvolle voltooiing levert het een gerigged karakter in standaardformaten en optioneel basis loop-/renanimaties.

Momenteel is auto-rigging niet geschikt voor de volgende modellen:

Ongestructureerde meshes
Niet-humanoïde assets
Humanoïde assets met onduidelijke ledematen- en lichaamsstructuur

Bij gebruik van input_task_id worden modellen met meer dan 300.000 vlakken niet ondersteund voor rigging. Gebruik alstublieft de Remesh API om het aantal vlakken te verminderen voordat u rigging uitvoert.

Bij gebruik van model_url moet het gezicht van het karakter naar de +Z-as wijzen (de standaard glTF voorwaartse richting). Modellen die naar andere assen wijzen, zullen falen bij pose schatting.

Parameters

Slechts één van input_task_id of model_url is vereist. Als beide worden verstrekt, heeft input_task_id prioriteit.

Name
input_task_id
Type
string
Verplicht
Description
De input taak die moet worden gerigged. We ondersteunen momenteel gestructureerde humanoïde modellen.

Name
model_url
Type
string
Verplicht
Description
Geef alstublieft een 3D-model voor Meshy om te riggen via een openbaar toegankelijke URL of Data URI. We ondersteunen momenteel gestructureerde humanoïde GLB-bestanden (.glb formaat).

Name
height_meters
Type
number
standaard 1.7
Description
De geschatte hoogte van het karaktermodel in meters. Dit helpt bij het schalen en de nauwkeurigheid van rigging. Het moet een positief getal zijn.
Name
texture_image_url
Type
string
Description
De UV-uitgeklapte basiskleur textuurafbeelding van het model. Openbaar toegankelijke URL of Data URI. We ondersteunen momenteel .png formaten.

Retourneert

De result eigenschap van de respons bevat de taak id van de nieuw aangemaakte rigging taak.

Foutmodi

Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
- Ontbrekende parameter: Ofwel model_url of input_task_id moet worden verstrekt.
- Ongeldig modelformaat: De model_url wijst naar een bestand met een niet-ondersteunde extensie (alleen .glb ondersteund).
- Onbereikbare URL: De model_url kon niet worden gedownload.
- Ongeldige input taak: De input_task_id verwijst niet naar een geldige API-taak.
- Vlakkenaantal overschreden: Het invoermodel heeft meer dan 300.000 vlakken. Gebruik alstublieft de Remesh API om het aantal vlakken te verminderen voordat u rigging uitvoert.
Name
401 - Unauthorized
Description
Authenticatie mislukt. Controleer alstublieft uw API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
422 - Unprocessable Entity
Description
Pose schatting mislukt. Het verstrekte model is mogelijk geen geldig humanoïde karakter.
Name
429 - Too Many Requests
Description
U heeft uw rate limit overschreden.

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

Haal een Rigging Taak op

Deze endpoint stelt je in staat om een rigging taak op te halen met een geldig taak id. Raadpleeg Het Rigging Taak Object om te zien welke eigenschappen zijn inbegrepen.

Parameters

Name
id
Type
path
Description
Unieke identificatie voor de rigging taak die moet worden opgehaald.

Retourneert

De respons bevat het Rigging Taak object. Bekijk de sectie Het Rigging Taak Object voor details.

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

Verwijder een Rigging Taak

Deze endpoint verwijdert permanent een rigging taak, inclusief alle bijbehorende modellen en gegevens. Deze actie is onomkeerbaar.

Padparameters

Name
id
Type
path
Description
De ID van de rigging taak die moet worden verwijderd.

Retourneert

Retourneert 200 OK bij succes.

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

Lijst Rigging Taken

Geeft een gepagineerde lijst terug van de rigging taken van de beller, nieuwste eerst. Standaard paginering via page_num en page_size.

Merk op dat taken die via de API zijn aangemaakt, via de API worden beheerd — ze verschijnen niet in de web-app's Mijn Assets. Gebruik deze endpoint om een taak te vinden waarvan je het ID niet meer hebt.

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

Stream een Rigging Taak

Deze endpoint streamt real-time updates voor een Rigging taak met behulp van Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unieke identificatie voor de Rigging taak om te streamen.

Retourneert

Retourneert een stream van De Rigging Taak Objecten als Server-Sent Events.

Voor PENDING of IN_PROGRESS taken zal de responsstream alleen de noodzakelijke progress en status velden bevatten.

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
}

Het Rigging Taak Object

Het Rigging Taak object vertegenwoordigt de werkeenheid voor het riggen van een karakter.

Eigenschappen

Name
id
Type
string
Description
Unieke identificatie voor de taak.
Name
type
Type
string
Description
Type van de Rigging taak. De waarde is rig.
Name
status
Type
string
Description
Status van de taak. Mogelijke waarden: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Voortgang van de taak (0-100). 0 als niet gestart, 100 als geslaagd.
Name
created_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) wanneer de taak is aangemaakt.
Een tijdstempel vertegenwoordigt het aantal milliseconden verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339 standaard. Bijvoorbeeld, vrijdag 1 september 2023 12:00:00 PM GMT wordt weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in Meshy API.
Name
started_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) wanneer de taak begon te verwerken. 0 als niet gestart.
Name
finished_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) wanneer de taak is voltooid. 0 als niet voltooid.
Name
expires_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) wanneer de taakresultaat assets verlopen en mogelijk worden verwijderd.
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken. Zie Fouten voor de volledige task_error objectreferentie.
Name
consumed_credits
Type
integer
Description
Het aantal credits verbruikt door deze taak. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS, of SUCCEEDED is. Geeft 0 terug voor FAILED taken (credits worden terugbetaald bij mislukking).
Name
result
Type
object
Description
Bevat de output asset URLs als de taak SUCCEEDED is, null anders.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Downloadbare URL voor het gerigde karakter in FBX-formaat.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Downloadbare URL voor het gerigde karakter in GLB-formaat.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Bevat URLs voor standaard animaties. (bijv. als generate_basic_animations impliciet waar was of standaard ingeschakeld).
  Name
  walking_glb_url
  Type
  string
  Description
  Downloadbare URL voor wandelanimatie in GLB-formaat (met huid).
  Name
  walking_fbx_url
  Type
  string
  Description
  Downloadbare URL voor wandelanimatie in FBX-formaat (met huid).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Downloadbare URL voor wandelanimatie armature in GLB-formaat.
  Name
  running_glb_url
  Type
  string
  Description
  Downloadbare URL voor renanimatie in GLB-formaat (met huid).
  Name
  running_fbx_url
  Type
  string
  Description
  Downloadbare URL voor renanimatie in FBX-formaat (met huid).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Downloadbare URL voor renanimatie armature in GLB-formaat.
Name
preceding_tasks
Type
integer
Description
Het aantal voorgaande taken in de wachtrij. Betekenisvol alleen als status PENDING is.

Voorbeeld Rigging Taak 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
}