Animations-API

Endpoints zum Entdecken verfügbarer Animationen und Anwenden dieser auf Charaktere mit Rig.

POST/openapi/v1/animations

Animationsaufgabe erstellen

Dieser endpoint ermöglicht es Ihnen, eine neue Aufgabe zu erstellen, um eine bestimmte Animationsaktion auf einen zuvor mit rigging versehenen Charakter anzuwenden. Enthält Optionen für die Nachbearbeitung.

Parameter

Name
rig_task_id
Type
string
Erforderlich
Description
Die id einer erfolgreich abgeschlossenen rigging-Aufgabe (von POST /openapi/v1/rigging). Der Charakter aus dieser Aufgabe wird animiert.
Name
action_id
Type
integer
Erforderlich
Description
Die Kennung der anzuwendenden Animationsaktion. Eine vollständige Liste der verfügbaren Animationen finden Sie in der Animationsbibliothek-Referenz.
Name
post_process
Type
object
Description
Optionale Nachbearbeitung für die Animationsausgabe. Lassen Sie dies weg, um die standardmäßigen Animationsdateien zu erhalten.

Gilt nur wenn post_process is set

Name
operation_type
Type
string
Erforderlich
Description
Der auszuführende Operationstyp. Verfügbare Werte: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
Standard 30
Description
Die Ziel-Bildrate. Gilt nur, wenn operation_type change_fps ist. Zulässige Werte: 24, 25, 30, 60.

Rückgabe

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 oder action_id fehlt.
- Ungültige rigging-Aufgabe: Die rig_task_id ist ungültig oder verweist auf eine fehlgeschlagene/nicht vorhandene Aufgabe.
- Ungültige Action-ID: Die action_id entspricht keiner gültigen Animation.
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
404 - Not Found
Description
Die durch rig_task_id angegebene rigging-Aufgabe wurde nicht gefunden.
Name
429 - Too Many Requests
Description
Sie haben Ihr Ratenlimit ü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
  }'

# 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 Animationsaufgabe abrufen

Dieser endpoint ermöglicht es dir, eine Animationsaufgabe anhand einer gültigen Aufgaben-id abzurufen. Siehe Das Animationsaufgaben-Objekt, um zu sehen, welche Eigenschaften enthalten sind.

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der abzurufenden Animationsaufgabe.

Rückgabewerte

Die Antwort enthält das Animationsaufgaben-Objekt. Details findest du im Abschnitt Das Animationsaufgaben-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 endpoint löscht eine Animationsaufgabe 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 Animationsaufgabe.

Rückgabe

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/:id/stream

Eine Animationsaufgabe streamen

Dieser API-Endpunkt streamt Echtzeitaktualisierungen für eine Animationsaufgabe mithilfe von Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der zu streamenden Animationsaufgabe.

Rückgabe

Gibt einen Stream von Animationsaufgaben-Objekten als Server-Sent Events zurück.

Bei PENDING- oder IN_PROGRESS-Aufgaben enthält der Antwortstream nur die erforderlichen 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
}

Das Animation-Task-Objekt

Das Animation-Task-Objekt stellt die Arbeitseinheit zum Anwenden einer Animation auf einen Charakter mit Rig dar.

Eigenschaften

Name
id
Type
string
Description
Eindeutiger Bezeichner für die Aufgabe.
Name
type
Type
string
Description
Typ der Animationsaufgabe. Der Wert ist animate.
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).
Name
created_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), zu dem die Aufgabe erstellt wurde.
Ein Zeitstempel stellt die Anzahl der seit dem 1. Januar 1970 UTC vergangenen Millisekunden dar, gemäß dem RFC 3339-Standard. Zum Beispiel 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 begann. 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.
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 durch diese Aufgabe verbrauchten Credits. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt 0 für FAILED-Aufgaben zurück (Credits werden bei einem Fehler erstattet).
Name
result
Type
object
Description
Enthält die URLs der ausgegebenen Animation, wenn die Aufgabe SUCCEEDED ist.
- Name
  animation_glb_url
  Type
  string
  Description
  Herunterladbare URL für die Animation im GLB-Format.
- Name
  animation_fbx_url
  Type
  string
  Description
  Herunterladbare URL für die Animation im FBX-Format.
- Name
  processed_usdz_url
  Type
  string
  Description
  Herunterladbare URL für die verarbeitete Animation im USDZ-Format.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  Herunterladbare URL für das verarbeitete Armature im FBX-Format.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  Herunterladbare URL für die Animation mit geänderter FPS im FBX-Format (z. B., wenn die Operation change_fps verwendet wurde).
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorhergehenden Aufgaben in der Warteschlange. Nur aussagekräftig, 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
}