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 gerigd personage, zie de Animatie API.

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

POST/openapi/v1/rigging

Een Rigging-taak aanmaken

Deze endpoint stelt u in staat om een nieuwe rigging-taak aan te maken voor een gegeven 3D-model. Na succesvolle voltooiing levert het een gerigd personage in standaardformaten en optioneel basis loop-/rennanimaties.

De taak wordt op de achtergrond uitgevoerd. Voor hoe lang dit meestal duurt, zie Verwerkingstijden.

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

Niet-getextureerde 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 polygonen niet ondersteund voor rigging. Gebruik de Remesh API om het aantal polygonen te verminderen voordat u rigt.

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

Parameters

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

Name
input_task_id
Type
string
Verplicht
Description
De invoertaak die gerigd moet worden. We ondersteunen momenteel getextureerde humanoïde modellen.

Name
model_url
Type
string
Verplicht
Description
Geef een 3D-model op dat Meshy kan riggen via een publiek toegankelijke URL of Data URI. We ondersteunen momenteel getextureerde humanoïde GLB-bestanden (.glb-formaat).
Maximale bestandsgrootte: 400 MB voor een http- of https-URL, 100 MB voor een data:-URI.
Een bestand groter dan 100 MB met meer dan 10.000.000 polygonen retourneert 400. Polygonen worden geteld als driehoeken, en een mesh die meerdere keren wordt getekend, telt één keer per kopie. Een GLB groter dan 100 MB mag geen Draco-compressie gebruiken.

Name
height_meters
Type
number
standaard 1.7
Description
De geschatte hoogte van het personagemodel in meters. Dit helpt bij de nauwkeurigheid van schaling en rigging. Het moet een positief getal zijn.
Name
texture_image_url
Type
string
Description
De UV-ontvouwen basiskleurtextuur van het model. Publiek toegankelijke URL of Data URI. We ondersteunen momenteel .png-formaten.
Maximale bestandsgrootte: 20 MB.

Resultaten

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 onaanvaardbaar. Veelvoorkomende oorzaken:
- Ontbrekende parameter: Ofwel model_url ofwel 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.
- Modelbestand te groot: Het model_url-bestand overschrijdt 400 MB (http- of https-URL) of 100 MB (data:-URI).
- Te veel polygonen: Het model_url-bestand is groter dan 100 MB en heeft meer dan 10.000.000 polygonen. Verminder het aantal polygonen en stuur het bestand opnieuw.
- Onleesbaar modelbestand: Het model_url-bestand is groter dan 100 MB en de header kan niet worden gelezen, bijvoorbeeld een met Draco gecomprimeerde GLB.
- Modelheader te complex: Het model_url-bestand is groter dan 100 MB en de header heeft te veel meshes, nodes of records om te controleren. Verminder het aantal objecten in het bestand en stuur het opnieuw.
- Afbeelding te groot: De texture_image_url-afbeelding overschrijdt 20 MB.
- Ongeldige invoertaak: De input_task_id verwijst niet naar een geldige API-taak.
- Aantal polygonen overschreden: Het invoermodel heeft meer dan 300.000 polygonen. Gebruik de Remesh API om het aantal polygonen te verminderen voordat u rigt.
Name
401 - Unauthorized
Description
Authenticatie mislukt. Controleer uw API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
422 - Unprocessable Entity
Description
Poseschatting mislukt. Het opgegeven model is mogelijk geen geldig humanoïde personage.
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

Een rigging-taak ophalen

Dit endpoint stelt u in staat om een rigging-taak op te halen aan de hand van een geldig taak-id. Raadpleeg Het Rigging Task-object om te zien welke eigenschappen zijn opgenomen.

Parameters

Name
id
Type
path
Description
Unieke identifier voor de op te halen rigging-taak.

Returns

Het antwoord bevat het Rigging Task-object. Raadpleeg de sectie Het Rigging Task-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

Een Rigging-taak verwijderen

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

Padparameters

Name
id
Type
path
Description
De ID van de te verwijderen rigging-taak.

Taakstatus

Een taak die nog PENDING is, wordt verwijderd en de credits die bij het aanmaken zijn verbruikt, worden terugbetaald.

Een taak die al IN_PROGRESS is, kan niet worden verwijderd: het verzoek wordt afgewezen met 409 Conflict en de taak blijft doorlopen. Credits voor een taak die de worker al is gestart, zijn niet terugbetaalbaar, dus het verwijderen ervan tijdens het uitvoeren zou je zowel de credits als het resultaat kosten. Wacht tot de taak de status SUCCEEDED, FAILED of CANCELED bereikt, en verwijder deze dan.

Een taak in een eindstatus (SUCCEEDED, FAILED of CANCELED) wordt verwijderd zonder terugbetaling.

Retourwaarden

Retourneert 200 OK bij succes, of 409 Conflict wanneer de taak IN_PROGRESS is.

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

Riggingtaken opvragen

Geeft een gepagineerde lijst met riggingtaken van de aanroeper terug, nieuwste eerst. Standaard paginering via page_num en page_size.

Houd er rekening mee dat taken die via de API zijn aangemaakt, ook via de API worden beheerd — ze verschijnen niet in Mijn assets van de web-app. Gebruik dit endpoint om een taak te vinden waarvan u de ID niet meer heeft.

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

Dit endpoint streamt realtime updates voor een Rigging-taak via Server-Sent Events (SSE).

Parameters

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

Retourneert

Retourneert een stream van The Rigging Task Objects als Server-Sent Events.

Voor taken met status PENDING of IN_PROGRESS 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 Rigging Task-object

Het Rigging Task-object 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
Voortgang van de taak (0-100). 0 als nog niet gestart, 100 als geslaagd.
Name
created_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak werd aangemaakt.
Een tijdstempel vertegenwoordigt het aantal milliseconden dat is verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339-standaard. Vrijdag 1 september 2023 12:00:00 PM GMT wordt bijvoorbeeld weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in de Meshy API.
Name
started_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak begon te verwerken. 0 als nog niet gestart.
Name
finished_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de taak werd voltooid. 0 als nog niet voltooid.
Name
expires_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de resultaat-assets van de taak verlopen en mogelijk worden verwijderd.
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.
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. Geeft 0 terug voor FAILED-taken (credits worden terugbetaald bij een fout).
Name
result
Type
object
Description
Bevat de output-asset-URL's als de taak SUCCEEDED is, anders null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Downloadbare URL voor het gerigde personage in FBX-formaat.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Downloadbare URL voor het gerigde personage in GLB-formaat.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Bevat URL's voor standaardanimaties. (bijv. als generate_basic_animations impliciet waar 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 de armature van de loopanimatie in GLB-formaat.
  Name
  running_glb_url
  Type
  string
  Description
  Downloadbare URL voor rennanimatie in GLB-formaat (met skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Downloadbare URL voor rennanimatie in FBX-formaat (met skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Downloadbare URL voor de armature van de rennanimatie in GLB-formaat.
Name
preceding_tasks
Type
integer
Description
Het aantal voorafgaande taken in de wachtrij. Alleen relevant 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
}