Rigging API

Fügen Sie einem humanoiden 3D-Modell ein Skelett (Armature) hinzu und binden Sie das Netz daran, sodass der Charakter animationsbereit ist. Um Animationen auf einen geriggten Charakter anzuwenden, siehe die Animation API.

Rigging funktioniert nur gut mit standardmäßigen humanoiden (zweibeinigen) Charakteren, die eine klar definierte Gliedmaßen- und Körperstruktur haben.

POST/openapi/v1/rigging

Rigging-Task erstellen

Erstellt einen Rigging-Task für ein 3D-Modell. Wenn der Task erfolgreich abgeschlossen wird, liefert er einen gerigten Charakter in Standardformaten und optional grundlegende Geh- und Lauf-Animationen zurück.

Der Task läuft im Hintergrund. Wie lange ein Task üblicherweise dauert, erfahren Sie unter Verarbeitungszeiten.

Rigging ist für folgende Modelle nicht geeignet:

Netze ohne Textur
Nicht-humanoide Assets
Humanoide Assets mit unklarer Gliedmaßen- und Körperstruktur

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"
}

Parameter

Name
input_task_id
Type
string
Erforderlich
Description
Erforderlich, sofern nicht model_url gesendet wird. Die ID des Tasks, dessen Modell geriggt werden soll. Meshy unterstützt texturierte humanoide Modelle.
Das Modell darf höchstens 380.000 Dreiecke aufweisen (ein Viereck zählt als 2), bei mehr liefert die Anfrage 400 zurück. Um unter dem Limit zu bleiben, führen Sie zuerst die Remesh-API mit einem target_polycount von höchstens 300000 aus, oder höchstens 150000 mit topology: quad.

Name
model_url
Type
string
Erforderlich
Description
Erforderlich, sofern nicht input_task_id gesendet wird. Das zu riggende Modell, als öffentliche URL oder als Data URI. Wenn Sie beides senden, verwendet Meshy input_task_id.
Das Modell muss eine GLB-Datei (.glb) mit höchstens 400 MB sein, wenn es über eine http- oder https-URL bereitgestellt wird, bzw. höchstens 100 MB als Data URI. Rigging unterstützt texturierte humanoide Modelle.
Das Modell darf höchstens 380.000 Dreiecke aufweisen (ein Viereck zählt als 2), bei mehr liefert die Anfrage 400 zurück. Um unter dem Limit zu bleiben, führen Sie zuerst die Remesh-API mit einem target_polycount von höchstens 300000 aus, oder höchstens 150000 mit topology: quad.
Das Gesicht des Charakters muss zur +Z-Achse zeigen, der standardmäßigen Vorwärtsrichtung in glTF. Bei einem Modell, das in eine andere Richtung blickt, schlägt die Posenschätzung fehl.
Für eine Datei über 100 MB gelten zusätzlich folgende Regeln:
- Sie darf höchstens 10.000.000 Flächen aufweisen. Bei mehr liefert die Anfrage 400 zurück. Meshy zählt Flächen als Dreiecke, und ein mehrfach gezeichnetes Netz wird pro Kopie einmal gezählt.
- Sie darf keine Draco-Kompression verwenden.

Name
height_meters
Type
number
Standard 1.7
Description
Die ungefähre Körpergröße des Charakters in Metern. Meshy nutzt diesen Wert, um das Modell präziser zu skalieren und zu riggen. Ein negativer Wert liefert 400 zurück.
Name
texture_image_url
Type
string
⚠ veraltet
Description
Lassen Sie diesen Parameter weg, wenn das Modell über eigene Texturen verfügt. Ohne ihn verwendet Meshy die in der model_url-Datei eingebetteten Texturen bzw. die Texturen des Eingabe-Tasks. Wenn Sie ihn senden, wird dieses Bild zur einzigen Textur des gerigten Modells, und das Modell verliert seine PBR-Texturen.
Die UV-entfaltete Grundfarbtextur des Modells, als öffentliche URL oder als Data URI. Das Bild muss eine PNG-Datei mit höchstens 20 MB sein. Ein anderes Bildformat liefert 400 zurück.

Rückgabewerte

Das Feld result der Antwort enthält die ID des neuen Rigging-Tasks.

Fehlerarten

Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung gibt an, welches Problem gefunden wurde. Zum Beispiel:
- Fehlender Parameter: Weder model_url noch input_task_id wurde gesendet.
- Ungültiges Modellformat: Die model_url-Datei hat eine nicht unterstützte Dateiendung. Nur .glb wird unterstützt.
- Nicht erreichbare URL: Meshy kann die model_url-Datei nicht herunterladen.
- Modelldatei zu groß: Die model_url-Datei ist größer als 400 MB bei einer http- oder https-URL, bzw. größer als 100 MB als Data URI.
- Zu viele Flächen: Die model_url-Datei ist größer als 100 MB und hat mehr als 10.000.000 Flächen. Reduzieren Sie die Flächenanzahl und senden Sie die Datei erneut.
- Modelldatei nicht lesbar: Die model_url-Datei ist größer als 100 MB, und Meshy kann deren Header nicht lesen. Beispielsweise handelt es sich um eine Draco-komprimierte GLB-Datei.
- Modell-Header zu komplex: Die model_url-Datei ist größer als 100 MB, und ihr Header enthält zu viele Netze, Knoten oder Einträge, um sie zu prüfen. Reduzieren Sie die Anzahl der Objekte in der Datei und senden Sie sie erneut.
- Bild zu groß: Das Bild unter texture_image_url ist größer als 20 MB.
- Ungültiges Texturformat: Das Bild unter texture_image_url ist keine PNG-Datei.
- Ungültige Höhe: height_meters ist negativ.
- Ungültiger Eingabe-Task: input_task_id verweist nicht auf einen gültigen API-Task.
- Flächenanzahl überschritten: Das Eingabemodell hat mehr als 380.000 Dreiecke (ein Viereck zählt als 2). Führen Sie zuerst die Remesh-API mit einem target_polycount von höchstens 300000 aus, oder höchstens 150000 mit topology: quad, bevor Sie das Modell riggen.
Beheben Sie das Problem in der Anfrage und senden Sie sie erneut. Siehe Fehler.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.
Name
402 - Payment Required
Description
Zum Beispiel:
- Unzureichende Credits: Das Konto verfügt nicht über genügend Credits für diesen Task, oder das Konto hat ein Credit-Limit erreicht. Prüfen Sie Ihr Credit-Guthaben und versuchen Sie es erneut.
- Kostenloser Plan: Das Erstellen eines Tasks erfordert einen kostenpflichtigen Plan. Führen Sie ein Upgrade Ihres Plans in Ihren Abonnement-Einstellungen durch und versuchen Sie es erneut.
Name
403 - Forbidden
Description
input_task_id ist ein Halbrelief-Modell, das dieser Endpunkt nicht riggen kann. Die Meldung lautet This model type does not support this operation. Senden Sie ein anderes Modell.
Name
422 - Unprocessable Entity
Description
Die Posenschätzung ist fehlgeschlagen. Das Modell ist möglicherweise kein gültiger humanoider Charakter. Senden Sie ein Modell eines humanoiden Charakters. Prüfen Sie bei model_url außerdem, ob der Charakter zur +Z-Achse ausgerichtet ist.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie und versuchen Sie es erneut. Siehe Ratenbegrenzungen.

GET/openapi/v1/rigging/:id

Einen Rigging-Task abrufen

Gibt einen Rigging-Task anhand seiner ID zurück.

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
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Antwort der Erstellung.

Rückgabe

Das Rigging-Task-Objekt.

DELETE/openapi/v1/rigging/:id

Rigging-Task löschen

Löscht einen Rigging-Task dauerhaft, einschließlich seiner Modelle und Daten. Das Löschen kann nicht rückgängig gemacht werden.

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 keeps 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."
}

Pfadparameter

Name
id
Type
path
Description
Die ID des zu löschenden Tasks.

Task-Status

Das Löschen eines PENDING-Tasks erstattet die Credits, die bei seiner Erstellung verwendet wurden.

Ein IN_PROGRESS-Task kann nicht gelöscht werden. Die Anfrage liefert 409 Conflict, und der Task läuft weiter. Meshy erstattet keine Credits für einen bereits gestarteten Task, weshalb ein Löschen Sie sowohl die Credits als auch das Ergebnis kosten würde. Warten Sie, bis er den Status SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie ihn dann.

Das Löschen eines Tasks in einem finalen Status (SUCCEEDED, FAILED oder CANCELED) erstattet dessen Credits nicht.

Rückgabe

200 OK, wenn der Task gelöscht wurde, oder 409 Conflict, wenn der Task IN_PROGRESS ist.

GET/openapi/v1/rigging

Rigging-Aufgaben auflisten

Gibt eine paginierte Liste deiner Rigging-Aufgaben zurück, die neuesten zuerst. Um durch die Liste zu blättern, verwende page_num und page_size.

Aufgaben, die du über die API erstellst, bleiben in der API und erscheinen nicht unter My Assets in der Web-App. Um eine Aufgabe zu finden, deren ID dir nicht mehr vorliegt, verwende diesen Endpunkt.

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

Einen Rigging-Task streamen

Streamt die Updates eines Rigging-Tasks als Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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 event, with the same fields as the 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/.../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
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Antwort beim Erstellen.

Rückgabe

Ein Stream von Rigging-Task-Objekten als Server-Sent Events.

Jedes Event enthält das vollständige Task-Objekt, in derselben Struktur, die der Get-Endpunkt zurückgibt. Solange der Task PENDING oder IN_PROGRESS ist, haben seine Ergebnisfelder noch keine Werte.

Das Rigging-Task-Objekt

Ein Rigging-Task-Objekt beschreibt das Rigging eines Charakters. Es enthält den Status, den progress und die Ausgabedateien, wenn die Aufgabe erfolgreich abgeschlossen wird.

Eigenschaften

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
}

Name
id
Type
string
Description
Die Task-ID. Behandeln Sie sie als eine undurchsichtige Zeichenfolge und verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer rig.
Name
status
Type
string
Description
Der Task-Status, einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED oder CANCELED.
Name
progress
Type
integer
Description
Wie viel von der Aufgabe erledigt ist, in Prozent. Der Wert ist 0, bis die Aufgabe beginnt, und 100, wenn sie erfolgreich abgeschlossen wird.
Name
created_at
Type
timestamp
Description
Zeitpunkt der Erstellung der Aufgabe, in Unix-Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitpunkt des Starts der Aufgabe, in Unix-Millisekunden. Der Wert ist 0, bis die Aufgabe startet.
Name
finished_at
Type
timestamp
Description
Zeitpunkt des Abschlusses der Aufgabe, in Unix-Millisekunden. Der Wert ist 0, bis die Aufgabe abgeschlossen ist.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, zu dem die Ergebnisdateien der Aufgabe ablaufen, in Unix-Millisekunden. Nach diesem Zeitpunkt kann Meshy die Dateien löschen.
Name
task_error
Type
object
Description
Die Fehlerdetails, wenn die Aufgabe fehlschlägt. Siehe Fehler.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von der Aufgabe verbrauchten Credits. Vorhanden, wenn der Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Bei einer Aufgabe mit Status FAILED ist der Wert 0, da Meshy die Credits erstattet, wenn eine Aufgabe fehlschlägt.
Name
result
Type
object
Description
Die URLs der Ausgabedateien. Bis die Aufgabe erfolgreich abgeschlossen ist, ist jede URL eine leere Zeichenfolge und basic_animations ist null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Download-URL für den geriggten Charakter als FBX-Datei.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Download-URL für den geriggten Charakter als GLB-Datei.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Download-URLs für die standardmäßigen Geh- und Lauf-Animationen.
  Name
  walking_glb_url
  Type
  string
  Description
  Die Geh-Animation mit Skin, als GLB-Datei.
  Name
  walking_fbx_url
  Type
  string
  Description
  Die Geh-Animation mit Skin, als FBX-Datei.
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Die Armature der Geh-Animation, als GLB-Datei.
  Name
  running_glb_url
  Type
  string
  Description
  Die Lauf-Animation mit Skin, als GLB-Datei.
  Name
  running_fbx_url
  Type
  string
  Description
  Die Lauf-Animation mit Skin, als FBX-Datei.
  Name
  running_armature_glb_url
  Type
  string
  Description
  Die Armature der Lauf-Animation, als GLB-Datei.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der Aufgaben, die in der Warteschlange vor dieser Aufgabe stehen. Der Wert ist nur relevant, solange die Aufgabe PENDING ist.