Rigging-API

Die Rigging-API ermöglicht es Ihnen, programmgesteuert ein Skelett (Armature) zu 3D-Humanoid-Modellen hinzuzufügen und das Mesh daran zu binden, sodass sie für Animationen bereit sind. Informationen zum Anwenden von Animationen auf einen geriggten Charakter finden Sie in der Animation API.

Bitte beachten Sie, dass programmgesteuertes Rigging derzeit nur mit standardmäßigen humanoiden (zweibeinigen) Assets mit klar definierten Gliedmaßen und klarer Körperstruktur gut funktioniert.

POST/openapi/v1/rigging

Eine Rigging-Aufgabe erstellen

Dieser endpoint ermöglicht es Ihnen, eine neue Rigging-Aufgabe für ein bestimmtes 3D-Modell zu erstellen. Nach erfolgreichem Abschluss wird ein geriggter Charakter in Standardformaten und optional mit grundlegenden Geh-/Laufanimationen bereitgestellt.

Derzeit ist Auto-Rigging für die folgenden Modelle nicht geeignet:

Meshes ohne Texturen
Nicht-humanoide Assets
Humanoide Assets mit unklarer Gliedmaßen- und Körperstruktur

Bei Verwendung von input_task_id werden Modelle mit mehr als 300.000 Flächen für Rigging nicht unterstützt. Bitte verwenden Sie die Remesh API, um die Flächenanzahl vor dem Rigging zu reduzieren.

Bei Verwendung von model_url muss das Gesicht des Charakters zur +Z-Achse zeigen (die standardmäßige Vorwärtsrichtung von glTF). Bei Modellen, die auf andere Achsen ausgerichtet sind, schlägt die Posenschätzung fehl.

Parameter

Nur eines von input_task_id oder model_url ist erforderlich. Wenn beide angegeben werden, hat input_task_id Vorrang.

Name
input_task_id
Type
string
Erforderlich
Description
Die Eingabeaufgabe, die geriggt werden muss. Wir unterstützen derzeit texturierte humanoide Modelle.

Name
model_url
Type
string
Erforderlich
Description
Bitte stellen Sie ein 3D-Modell bereit, damit Meshy es über eine öffentlich zugängliche URL oder Data URI riggen kann. Wir unterstützen derzeit texturierte humanoide GLB-Dateien (.glb-Format).

Name
height_meters
Type
number
Standard 1.7
Description
Die ungefähre Höhe des Charaktermodells in Metern. Dies unterstützt die Genauigkeit bei Skalierung und Rigging. Sie muss eine positive Zahl sein.
Name
texture_image_url
Type
string
Description
Das UV-entfaltete Base-Color-Texturbild des Modells. Öffentlich zugängliche URL oder Data URI. Wir unterstützen derzeit .png-Formate.

Rückgabe

Die Eigenschaft result der Antwort enthält die Aufgaben-id der neu erstellten Rigging-Aufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
- Fehlender Parameter: Entweder model_url oder input_task_id muss angegeben werden.
- Ungültiges Modellformat: model_url verweist auf eine Datei mit einer nicht unterstützten Erweiterung (nur .glb wird unterstützt).
- Nicht erreichbare URL: model_url konnte nicht heruntergeladen werden.
- Ungültige Eingabeaufgabe: input_task_id verweist nicht auf eine gültige API-Aufgabe.
- Flächenanzahl überschritten: Das Eingabemodell hat mehr als 300.000 Flächen. Bitte verwenden Sie die Remesh API, um die Flächenanzahl vor dem Rigging zu reduzieren.
Name
401 - Unauthorized
Description
Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihren API key.
Name
402 - Payment Required
Description
Nicht genügend Credits, um diese Aufgabe auszuführen.
Name
422 - Unprocessable Entity
Description
Posenschätzung fehlgeschlagen. Das bereitgestellte Modell ist möglicherweise kein gültiger humanoider Charakter.
Name
429 - Too Many Requests
Description
Sie haben Ihr Ratenlimit überschritten.

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

Rigging-Aufgabe abrufen

Dieser endpoint ermöglicht es Ihnen, eine Rigging-Aufgabe anhand einer gültigen Aufgaben-id abzurufen. Siehe Das Rigging-Aufgabenobjekt, um zu sehen, welche Eigenschaften enthalten sind.

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der abzurufenden Rigging-Aufgabe.

Rückgabe

Die Antwort enthält das Rigging-Aufgabenobjekt. Weitere Details finden Sie im Abschnitt Das Rigging-Aufgabenobjekt.

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

Eine Rigging-Aufgabe löschen

Dieser endpoint löscht eine Rigging-Aufgabe dauerhaft, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion ist unumkehrbar.

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden Rigging-Aufgabe.

Rückgabe

Gibt bei Erfolg 200 OK zurück.

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

Eine Rigging-Aufgabe streamen

Dieser endpoint streamt Echtzeit-Updates für eine Rigging-Aufgabe mithilfe von Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der zu streamenden Rigging-Aufgabe.

Rückgabe

Gibt einen Stream von The Rigging Task Objects als Server-Sent Events zurück.

Für Aufgaben mit PENDING oder IN_PROGRESS enthält der Antwort-Stream nur die erforderlichen Felder progress und 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
}

Das Rigging-Aufgabenobjekt

Das Rigging-Aufgabenobjekt stellt die Arbeitseinheit für das Rigging eines Charakters dar.

Eigenschaften

Name
id
Type
string
Description
Eindeutige Kennung für die Aufgabe.
Name
type
Type
string
Description
Typ der Rigging-Aufgabe. Der Wert ist rig.
Name
status
Type
string
Description
Status der Aufgabe. Mögliche Werte: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Fortschritt der Aufgabe (0-100). 0, wenn nicht gestartet, 100, wenn erfolgreich abgeschlossen.
Name
created_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), zu dem die Aufgabe erstellt wurde.
Ein Zeitstempel stellt die Anzahl der Millisekunden dar, die seit dem 1. Januar 1970 UTC gemäß dem RFC 3339-Standard vergangen sind. Beispielsweise wird Freitag, 1. September 2023, 12:00:00 PM GMT als 1693569600000 dargestellt. Dies gilt für alle Zeitstempel in der Meshy API.
Name
started_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), zu dem die Verarbeitung der Aufgabe begonnen hat. 0, wenn nicht gestartet.
Name
finished_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), zu dem die Aufgabe abgeschlossen wurde. 0, wenn nicht abgeschlossen.
Name
expires_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), zu dem die Ergebnis-Assets der Aufgabe ablaufen und gelöscht werden können.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige task_error-Objektreferenz.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von dieser Aufgabe verbrauchten Credits. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Aufgaben zurück (Credits werden bei Fehlern erstattet).
Name
result
Type
object
Description
Enthält die URLs der Ausgabe-Assets, wenn die Aufgabe SUCCEEDED ist, andernfalls null.
- Name
  rigged_character_fbx_url
  Type
  string
  Description
  Herunterladbare URL für den geriggten Charakter im FBX-Format.
- Name
  rigged_character_glb_url
  Type
  string
  Description
  Herunterladbare URL für den geriggten Charakter im GLB-Format.
- Name
  basic_animations
  Type
  object (optional)
  Description
  Enthält URLs für Standardanimationen. (z. B. wenn generate_basic_animations implizit wahr war oder standardmäßig aktiviert wurde).
  Name
  walking_glb_url
  Type
  string
  Description
  Herunterladbare URL für die Gehen-Animation im GLB-Format (mit Skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  Herunterladbare URL für die Gehen-Animation im FBX-Format (mit Skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Herunterladbare URL für das Armature der Gehen-Animation im GLB-Format.
  Name
  running_glb_url
  Type
  string
  Description
  Herunterladbare URL für die Laufen-Animation im GLB-Format (mit Skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Herunterladbare URL für die Laufen-Animation im FBX-Format (mit Skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Herunterladbare URL für das Armature der Laufen-Animation im GLB-Format.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorangehenden Aufgaben in der Warteschlange. Nur aussagekräftig, wenn der Status PENDING ist.

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
}