Rigging-API

Die Rigging-API ermöglicht es Ihnen, programmatisch ein Skelett (Armature) zu 3D-Humanoidmodellen hinzuzufügen und das Netz daran zu binden, sodass sie bereit für die Animation sind. Um Animationen auf einen geriggten Charakter anzuwenden, siehe die Animations-API.

Bitte beachten Sie, dass das programmatische Rigging derzeit nur gut mit standardmäßigen humanoiden (zweibeinigen) Assets funktioniert, die klar definierte Gliedmaßen und eine Körperstruktur aufweisen.

POST/openapi/v1/rigging

Rigging-Task erstellen

Dieser Endpunkt ermöglicht es Ihnen, einen neuen Rigging-Task für ein gegebenes 3D-Modell zu erstellen. Nach erfolgreichem Abschluss liefert er einen geriggten Charakter in Standardformaten und optional einfache Geh-/Lauf-Animationen.

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

Derzeit eignet sich das automatische Rigging nicht für folgende Modelle:

Untexturierte Meshes
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 Faces für das Rigging nicht unterstützt. Bitte verwenden Sie die Remesh-API, um die Face-Anzahl vor dem Rigging zu reduzieren.

Bei Verwendung von model_url muss das Gesicht des Charakters in Richtung der +Z-Achse zeigen (die standardmäßige glTF-Vorwärtsrichtung). Modelle, die in andere Achsen ausgerichtet sind, führen zu einem Fehler bei der Posenschätzung.

Parameter

Nur eines von input_task_id oder model_url ist erforderlich. Werden beide angegeben, hat input_task_id Priorität.

Name
input_task_id
Type
string
Erforderlich
Description
Der Input-Task, der gerigged werden soll. Wir unterstützen derzeit texturierte humanoide Modelle.

Name
model_url
Type
string
Erforderlich
Description
Bitte stellen Sie Meshy ein 3D-Modell für das Rigging über eine öffentlich zugängliche URL oder Data URI zur Verfügung. Wir unterstützen derzeit texturierte humanoide GLB-Dateien (Format .glb).
Maximale Dateigröße: 100 MB.

Name
height_meters
Type
number
Standard 1.7
Description
Die ungefähre Höhe des Charaktermodells in Metern. Dies unterstützt die Genauigkeit von Skalierung und Rigging. Der Wert muss eine positive Zahl sein.
Name
texture_image_url
Type
string
Description
Die UV-entfaltete Basisfarb-Textur des Modells. Öffentlich zugängliche URL oder Data URI. Wir unterstützen derzeit das Format .png.
Maximale Dateigröße: 20 MB.

Rückgabewerte

Die Eigenschaft result der Antwort enthält die Task-id des neu erstellten Rigging-Tasks.

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 nicht unterstützter Dateiendung (nur .glb wird unterstützt).
- Nicht erreichbare URL: Die model_url konnte nicht heruntergeladen werden.
- Modelldatei zu groß: Die Datei unter model_url überschreitet 100 MB.
- Bild zu groß: Das Bild unter texture_image_url überschreitet 20 MB.
- Ungültiger Input-Task: input_task_id verweist nicht auf einen gültigen API-Task.
- Face-Anzahl überschritten: Das Eingabemodell hat mehr als 300.000 Faces. Bitte verwenden Sie die Remesh-API, um die Face-Anzahl vor dem Rigging zu reduzieren.
Name
401 - Unauthorized
Description
Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.
Name
402 - Payment Required
Description
Unzureichende Credits, um diesen Task auszuführen.
Name
422 - Unprocessable Entity
Description
Die Posenschätzung ist fehlgeschlagen. Das bereitgestellte Modell ist möglicherweise kein gültiger humanoider Charakter.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung ü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

Abrufen einer Rigging-Aufgabe

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

Parameter

Name
id
Type
path
Description
Eindeutiger Bezeichner für die abzurufende Rigging-Aufgabe.

Rückgabe

Die Antwort enthält das Rigging-Aufgabenobjekt. Überprüfen Sie den Abschnitt Das Rigging-Aufgabenobjekt für Details.

Anfrage

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

Antwort

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

Rigging-Task löschen

Dieser Endpunkt löscht einen Rigging-Task dauerhaft, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion ist unumkehrbar.

Pfadparameter

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

Task-Status

Ein Task, der sich noch im Status PENDING befindet, wird gelöscht, und die beim Erstellen verbrauchten Credits werden erstattet.

Ein Task, der sich bereits IN_PROGRESS befindet, kann nicht gelöscht werden: Die Anfrage wird mit 409 Conflict abgelehnt, und der Task läuft weiter. Credits für einen Task, den der Worker bereits gestartet hat, sind nicht erstattungsfähig. Ein Löschen währenddessen würde Sie sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis der Status SUCCEEDED, FAILED oder CANCELED erreicht ist, und löschen Sie ihn dann.

Ein Task in einem Endzustand (SUCCEEDED, FAILED oder CANCELED) wird ohne Erstattung gelöscht.

Rückgabewerte

Gibt bei Erfolg 200 OK zurück, oder 409 Conflict, wenn der Task IN_PROGRESS ist.

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

Liste der Rigging-Aufgaben

Gibt eine paginierte Liste der Rigging-Aufgaben des Anrufers zurück, beginnend mit den neuesten. Standard-Paginierung über page_num und page_size.

Beachten Sie, dass Aufgaben, die über die API erstellt wurden, auch über die API verwaltet werden – sie erscheinen nicht in der Web-App unter Meine Assets. Verwenden Sie diesen Endpunkt, um eine Aufgabe zu finden, deren ID Sie nicht mehr haben.

Anfrage

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

Streamen einer Rigging-Aufgabe

Dieser Endpunkt streamt Echtzeit-Updates für eine Rigging-Aufgabe unter Verwendung von Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutiger Bezeichner für die zu streamende Rigging-Aufgabe.

Rückgaben

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

Für PENDING oder IN_PROGRESS Aufgaben enthält der Antwortstream nur die notwendigen 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-Task-Objekt

Das Rigging-Task-Objekt repräsentiert die Arbeitseinheit für das Rigging eines Charakters.

Eigenschaften

Name
id
Type
string
Description
Eindeutiger Bezeichner 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.
Name
created_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit dem Epoch) wann die Aufgabe erstellt wurde.
Ein Zeitstempel repräsentiert die Anzahl der Millisekunden, die seit dem 1. Januar 1970 UTC vergangen sind, gemäß dem RFC 3339 Standard. Zum Beispiel wird Freitag, der 1. September 2023, 12:00:00 Uhr GMT als 1693569600000 dargestellt. Dies gilt für alle Zeitstempel in der Meshy API.
Name
started_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit dem Epoch) wann die Aufgabe mit der Verarbeitung begann. 0 wenn nicht gestartet.
Name
finished_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit dem Epoch) wann die Aufgabe beendet wurde. 0 wenn nicht beendet.
Name
expires_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit dem Epoch) wann die Ergebnis-Assets der Aufgabe ablaufen und möglicherweise gelöscht werden.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige task_error Objekt-Referenz.
Name
consumed_credits
Type
integer
Description
Die Anzahl der Credits, die von dieser Aufgabe verbraucht wurden. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED Aufgaben zurück (Credits werden bei Fehlern zurückerstattet).
Name
result
Type
object
Description
Enthält die URLs der Ausgabe-Assets, wenn die Aufgabe SUCCEEDED, 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 oder standardmäßig aktiviert war).
  Name
  walking_glb_url
  Type
  string
  Description
  Herunterladbare URL für die Geh-Animation im GLB-Format (mit Skin).
  Name
  walking_fbx_url
  Type
  string
  Description
  Herunterladbare URL für die Geh-Animation im FBX-Format (mit Skin).
  Name
  walking_armature_glb_url
  Type
  string
  Description
  Herunterladbare URL für die Geh-Animation-Armatur im GLB-Format.
  Name
  running_glb_url
  Type
  string
  Description
  Herunterladbare URL für die Lauf-Animation im GLB-Format (mit Skin).
  Name
  running_fbx_url
  Type
  string
  Description
  Herunterladbare URL für die Lauf-Animation im FBX-Format (mit Skin).
  Name
  running_armature_glb_url
  Type
  string
  Description
  Herunterladbare URL für die Lauf-Animation-Armatur im GLB-Format.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorhergehenden Aufgaben in der Warteschlange. Bedeutend nur, 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
}