Animation API

Endpoints zum Auffinden verfügbarer Animationen und deren Anwendung auf Charaktere mit Rig.

POST/openapi/v1/animations

Create an Animation Task

Dieser Endpunkt ermöglicht es Ihnen, eine neue Aufgabe zu erstellen, um eine Animation auf einen zuvor mit Rigging versehenen Charakter anzuwenden — entweder eine voreingestellte Aktion aus der Animationsbibliothek (action_id) oder ein Bewegungsclip, den Sie mit der Text to Motion API erstellt haben (motion_task_id). Enthält Optionen zur Nachbearbeitung.

Parameter

Name
rig_task_id
Type
string
Erforderlich
Description
Die id einer erfolgreich abgeschlossenen Rigging-Aufgabe (aus POST /openapi/v1/rigging). Der Charakter aus dieser Aufgabe wird animiert.
Name
action_id
Type
integer
Description
Der Bezeichner der voreingestellten Animationsaktion, die angewendet werden soll. Eine vollständige Liste der verfügbaren Animationen finden Sie in der Animationsbibliothek-Referenz. Geben Sie genau eines von action_id oder motion_task_id an.
Name
motion_task_id
Type
string
Description
Die id einer erfolgreich abgeschlossenen Text-to-Motion-Aufgabe, die anstelle einer voreingestellten Aktion angewendet werden soll. Der generierte Clip wird auf den mit Rigging versehenen Charakter neu ausgerichtet (Retargeting), und der Clip wird zum Zeitpunkt der Erstellung als Snapshot gespeichert, sodass diese Aufgabe nicht betroffen ist, falls die Quellaufgabe später abläuft oder gelöscht wird. Die Assets der Quellaufgabe werden 3 Tage lang aufbewahrt — wenden Sie den Clip an, bevor er abläuft. Erfordert ein zweibeiniges Rig. Geben Sie genau eines von action_id oder motion_task_id an.
Name
post_process
Type
object
Description
Optionale Nachbearbeitung für die Animationsausgabe. Lassen Sie sie weg, um die Standard-Animationsdateien zu erhalten.

Gilt nur wenn post_process is set

Name
operation_type
Type
string
Erforderlich
Description
Der Typ der auszuführenden Operation. Verfügbare Werte: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
Standard 30
Description
Die Ziel-Framerate. Gilt nur, wenn operation_type gleich change_fps ist. Erlaubte Werte: 24, 25, 30, 60.

Bei motion_task_id kann das Retargeting zu einer nur-GLB-Animation führen. Wenn Sie post_process angefordert haben und keine FBX-Datei verfügbar ist, schlägt die Aufgabe mit einem task_error fehl und Ihre Credits werden automatisch erstattet; ohne post_process ist die Aufgabe erfolgreich und animation_fbx_url ist leer.

Rückgabewerte

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

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
- Fehlender Parameter: rig_task_id fehlt, oder es wurde weder action_id noch motion_task_id angegeben.
- Widersprüchliche Parameter: Sowohl action_id als auch motion_task_id wurden angegeben — sie schließen sich gegenseitig aus.
- Ungültige Rigging-Aufgabe: Die rig_task_id ist ungültig oder verweist auf eine fehlgeschlagene/nicht existierende Aufgabe.
- Ungültige Aktions-ID: Die action_id entspricht keiner gültigen Animation.
- Motion-Aufgabe nicht bereit: Die Aufgabe zu motion_task_id hat noch nicht den Status SUCCEEDED.
- Nicht unterstütztes Rig: motion_task_id erfordert ein zweibeiniges Rig; vierbeinige Rigs werden abgelehnt.
Name
401 - Unauthorized
Description
Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.
Name
402 - Payment Required
Description
Nicht genügend Credits, um diese Aufgabe auszuführen.
Name
404 - Not Found
Description
Die durch rig_task_id angegebene Rigging-Aufgabe wurde nicht gefunden, die durch motion_task_id angegebene Motion-Aufgabe wurde nicht gefunden, oder der Bewegungsclip ist abgelaufen (Assets der Quellaufgabe werden 3 Tage lang aufbewahrt).
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten.

Request

POST

/openapi/v1/animations

# Animate a rigged model with required params only
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92
  }'

# Apply a generated Text to Motion clip instead of a preset action
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "motion_task_id": "018c425b-b2c6-727e-d333-3c1887i9h791"
  }'

# With post-processing to change FPS
curl https://api.meshy.ai/openapi/v1/animations \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579",
    "action_id": 92,
    "post_process": {
      "operation_type": "change_fps",
      "fps": 24
    }
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

GET/openapi/v1/animations/:id

Eine Animations-Aufgabe abrufen

Dieser Endpunkt ermöglicht es Ihnen, eine Animations-Aufgabe anhand einer gültigen Aufgaben-id abzurufen. Weitere Informationen zu den enthaltenen Eigenschaften finden Sie unter Das Animation-Task-Objekt.

Parameter

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

Rückgabewerte

Die Antwort enthält das Animation-Task-Objekt. Details finden Sie im Abschnitt Das Animation-Task-Objekt.

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791 
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.glb?Expires=...",
    "animation_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/Animation_Reaping_Swing_withSkin.fbx?Expires=...",
    "processed_usdz_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed.usdz?Expires=...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_armature.fbx?Expires=...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/processed_60fps.fbx?Expires=..."
  },
  "preceding_tasks": 0
}

DELETE/openapi/v1/animations/:id

Eine Animationsaufgabe löschen

Dieser Endpunkt löscht eine Animationsaufgabe endgültig, einschließlich aller zugehörigen Modelle und Daten. Diese Aktion ist unwiderruflich.

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden Animationsaufgabe.

Rückgabewerte

Gibt bei Erfolg 200 OK zurück.

Request

DELETE

/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/animations/018b314a-a1b5-716d-c222-2f1776f7f579 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/animations

Liste der Animation-Aufgaben

Gibt eine paginierte Liste der Animation-Aufgaben des Aufrufers zurück, neueste zuerst. 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 „Meine Assets“ der Web-App. Verwenden Sie diesen Endpunkt, um eine Aufgabe zu finden, deren ID Sie nicht mehr haben.

Request

GET

/openapi/v1/animations

curl "https://api.meshy.ai/openapi/v1/animations?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

GET/openapi/v1/animations/:id/stream

Streamen einer Animation-Aufgabe

Dieser Endpunkt streamt Echtzeit-Updates für eine Animation-Aufgabe über Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der Animation-Aufgabe, die gestreamt werden soll.

Rückgabewerte

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

Bei Aufgaben mit dem Status PENDING oder IN_PROGRESS enthält der Antwort-Stream nur die notwendigen Felder progress und status.

Request

GET

/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/animations/018c425b-b2c6-727e-d333-3c1887i9h791/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": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: { // Example of a SUCCEEDED task stream item, mirroring The Animation Task Object structure
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}

The Animation Task Object

Das Animation-Task-Objekt repräsentiert die Arbeitseinheit für das Anwenden einer Animation auf einen mit einem Rig versehenen Charakter.

Eigenschaften

Name
id
Type
string
Description
Eindeutiger Bezeichner für den Task.
Name
type
Type
string
Description
Typ des Animation-Tasks. Der Wert ist animate.
Name
status
Type
string
Description
Status des Tasks. Mögliche Werte: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Fortschritt des Tasks (0-100).
Name
created_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), wann der Task erstellt wurde.
Ein Zeitstempel repräsentiert die Anzahl der Millisekunden, die seit dem 1. Januar 1970 UTC vergangen sind, gemäß dem Standard RFC 3339. 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 der Epoche), wann der Task mit der Verarbeitung begonnen hat. 0, falls noch nicht gestartet.
Name
finished_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), wann der Task abgeschlossen wurde. 0, falls noch nicht abgeschlossen.
Name
expires_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), wann die Ergebnis-Assets des Tasks ablaufen.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Tasks. Siehe Fehler für die vollständige Referenz des task_error-Objekts.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von diesem Task verbrauchten Credits. Vorhanden, wenn der Task-Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Tasks zurück (Credits werden bei einem Fehlschlag zurückerstattet).
Name
result
Type
object
Description
Enthält die Ausgabe-Animations-URLs, falls der Task SUCCEEDED ist.
- Name
  animation_glb_url
  Type
  string
  Description
  Downloadbare URL für die Animation im GLB-Format.
- Name
  animation_fbx_url
  Type
  string
  Description
  Downloadbare URL für die Animation im FBX-Format.
- Name
  processed_usdz_url
  Type
  string
  Description
  Downloadbare URL für die verarbeitete Animation im USDZ-Format.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Downloadbare URL für die verarbeitete Armature im FBX-Format.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Downloadbare URL für die Animation mit geänderter FPS im FBX-Format (z. B. falls die Operation change_fps verwendet wurde).
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorausgehenden Tasks in der Warteschlange. Nur relevant, wenn der Status PENDING ist.

Example Animation Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "animate",
  "status": "SUCCEEDED",
  "created_at": 1747032440896,
  "progress": 100,
  "started_at": 1747032441210,
  "finished_at": 1747032457530,
  "expires_at": 1747291657530,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 3,
  "result": {
    "animation_glb_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.glb?...",
    "animation_fbx_url": "https://assets.meshy.ai/.../Animation_Reaping_Swing_withSkin.fbx?...",
    "processed_usdz_url": "https://assets.meshy.ai/.../processed.usdz?...",
    "processed_armature_fbx_url": "https://assets.meshy.ai/.../processed_armature.fbx?...",
    "processed_animation_fps_fbx_url": "https://assets.meshy.ai/.../processed_60fps.fbx?..."
  },
  "preceding_tasks": 0
}