Rigging API

Met de Rigging API kun je programmatisch een skelet (armature) toevoegen aan 3D-humanoïde modellen, waarbij de mesh eraan wordt gebonden zodat ze klaar zijn voor animatie. Zie de Animatie API voor het toepassen van animaties op een gerigd personage.

Let op: programmatische rigging werkt momenteel alleen goed met standaard humanoïde (tweebenige) assets met duidelijk gedefinieerde ledematen en lichaamsstructuur.

POST/openapi/v1/rigging

Een riggingtaak maken

Met dit endpoint kun je een nieuwe riggingtaak maken voor een gegeven 3D-model. Na succesvolle voltooiing levert het een personage met rigging in standaardformaten en optioneel basisanimaties voor lopen/rennen.

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

Meshes zonder textuur
Niet-humanoïde assets
Humanoïde assets met onduidelijke ledemaat- en lichaamsstructuur

Bij gebruik van input_task_id worden modellen met meer dan 300.000 faces niet ondersteund voor rigging. Gebruik de Remesh API om het aantal faces te verminderen vóór rigging.

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

Parameters

Slechts één van input_task_id of model_url is vereist. Als beide worden opgegeven, krijgt input_task_id prioriteit.

Name
input_task_id
Type
string
Verplicht
Description
De invoertaak die van rigging moet worden voorzien. We ondersteunen momenteel humanoïde modellen met textuur.

Name
model_url
Type
string
Verplicht
Description
Geef een 3D-model op dat Meshy kan riggen via een openbaar toegankelijke URL of Data URI. We ondersteunen momenteel humanoïde GLB-bestanden met textuur (.glb-formaat).

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

Retourneert

De eigenschap result van de response bevat de taak-id van de nieuw aangemaakte riggingtaak.

Faalmodi

Name
400 - Bad Request
Description
De aanvraag was niet acceptabel. Veelvoorkomende oorzaken:
- Ontbrekende parameter: Ofwel model_url of input_task_id moet worden opgegeven.
- Ongeldig modelformaat: De model_url verwijst naar een bestand met een niet-ondersteunde extensie (alleen .glb wordt ondersteund).
- Onbereikbare URL: De model_url kon niet worden gedownload.
- Ongeldige invoertaak: De input_task_id verwijst niet naar een geldige API-taak.
- Aantal faces overschreden: Het invoermodel heeft meer dan 300.000 faces. Gebruik de Remesh API om het aantal faces te verminderen vóór rigging.
Name
401 - Unauthorized
Description
Authenticatie mislukt. Controleer je API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
422 - Unprocessable Entity
Description
Pose-inschatting mislukt. Het opgegeven model is mogelijk geen geldig humanoïde personage.
Name
429 - Too Many Requests
Description
Je hebt je 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

Een riggingtaak ophalen

Met dit endpoint kun je een riggingtaak ophalen met een geldige taak-id. Raadpleeg Het Rigging-taakobject om te zien welke eigenschappen zijn opgenomen.

Parameters

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

Retourneert

De response bevat het Rigging-taakobject. Bekijk de sectie Het Rigging-taakobject 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

Een riggingtaak verwijderen

Deze endpoint verwijdert een riggingtaak permanent, inclusief alle bijbehorende modellen en gegevens. Deze actie kan niet ongedaan worden gemaakt.

Padparameters

Name
id
Type
path
Description
De ID van de riggingtaak 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/:id/stream

Stream een rigging-taak

Deze endpoint streamt realtime-updates voor een rigging-taak met Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unieke identifier voor de rigging-taak die moet worden gestreamd.

Retourneert

Retourneert een stream van De rigging-taakobjecten als Server-Sent Events.

Voor PENDING- of IN_PROGRESS-taken bevat de responsstream alleen de noodzakelijke velden progress en 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
}

Het riggingtaakobject

Het riggingtaakobject vertegenwoordigt de werkeenheid voor het riggen van een personage.

Eigenschappen

Name
id
Type
string
Description
Unieke identifier 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
Progress van de taak (0-100). 0 als deze niet is gestart, 100 als deze is geslaagd.
Name
created_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak is aangemaakt.
Een tijdstempel vertegenwoordigt het aantal milliseconden dat is 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) waarop de taak is begonnen met verwerken. 0 als deze niet is gestart.
Name
finished_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak is voltooid. 0 als deze niet is voltooid.
Name
expires_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de resultaat-assets van de taak verlopen en kunnen 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 dat door deze taak is verbruikt. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS of SUCCEEDED is. Retourneert 0 voor FAILED-taken (credits worden terugbetaald bij mislukking).
Name
result
Type
object
Description
Bevat de URL's van de output-assets als de taak SUCCEEDED is, anders null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Downloadbare URL voor het geriggde personage in FBX-formaat.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Downloadbare URL voor het geriggde personage in GLB-formaat.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Bevat URL's voor standaardanimaties. (bijv. als generate_basic_animations impliciet true was of standaard was ingeschakeld).
  Name
  walking_glb_url
  Type
  string
  Description
  Downloadbare URL voor loopanimatie in GLB-formaat (met skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  Downloadbare URL voor loopanimatie in FBX-formaat (met skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Downloadbare URL voor loopanimatie-armature in GLB-formaat.
  Name
  running_glb_url
  Type
  string
  Description
  Downloadbare URL voor renanimatie in GLB-formaat (met skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Downloadbare URL voor renanimatie in FBX-formaat (met skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Downloadbare URL voor renanimatie-armature in GLB-formaat.
Name
preceding_tasks
Type
integer
Description
Het aantal voorafgaande taken in de wachtrij. Alleen betekenisvol als de status PENDING is.

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
}