lowpoly wird am 30.10.2026 abgeschaltet. meshy-7 wird als 3D-Generierungsmodell am 31.12.2026 abgeschaltet; als Texturmodell bleibt es verfügbar. Wechseln Sie vor diesen Terminen das Modell, um Fehler bei Anfragen zu vermeiden. Alle Abkündigungen ansehen
Animation API
Wende Animationen auf geriggte Charaktere an und liste die Animationen auf, die du anwenden kannst.
Erstellt eine Animations-Aufgabe, die eine Animation auf einen zuvor von Ihnen gerigten Charakter anwendet. Die Animation kann eine der folgenden sein:
Eine voreingestellte Aktion aus der Animationsbibliothek (action_id)
Mehrere voreingestellte Aktionen, zusammengeführt in einer Datei (action_ids)
Ein Bewegungsclip, den Sie mit der Text-to-Motion-API erzeugt haben (motion_task_id)
Sie können die Ausgabe auch nachbearbeiten. Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe üblicherweise dauert, erfahren Sie unter Verarbeitungszeiten.
Request
POST
/openapi/v1/animations
# Animate a rigged model with required params onlycurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579", "action_id": 92 }'# Apply several preset actions and get one file with one clip per actioncurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "rig_task_id": "018b314a-a1b5-716d-c222-2f1776f7f579", "action_ids": [10, 25, 92] }'# Apply a generated Text to Motion clip instead of a preset actioncurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-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 FPScurlhttps://api.meshy.ai/openapi/v1/animations \-XPOST \-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"}
Parameter
Name
rig_task_id
Type
string
Erforderlich
Description
Die ID der Rigging-Aufgabe, deren Charakter animiert werden soll, aus POST /openapi/v1/rigging. Die Aufgabe muss den Status SUCCEEDED haben.
Senden Sie genau einen der Parameter action_id, action_ids oder motion_task_id.
Name
action_id
Type
integer
Erforderlich
Description
Erforderlich, sofern Sie nicht action_ids oder motion_task_id senden. Die ID der anzuwendenden voreingestellten Animation. Die vollständige Liste der Animationen finden Sie in der Referenz zur Animationsbibliothek oder unter Animationen auflisten.
Der rig_type der Animation muss zum Rig passen, sonst gibt die Anfrage 400 zurück. Jede quadruped-Animation funktioniert mit jedem Vierbeiner-Rig, unabhängig davon, welches Tier in dessen category genannt wird.
Name
action_ids
Type
array of integers
Erforderlich
Description
Erforderlich, sofern Sie nicht action_id oder motion_task_id senden. Die IDs von 1 bis 10 voreingestellten Animationen, die gleichzeitig angewendet werden sollen, ohne Wiederholungen. Mehr als 10 IDs oder eine wiederholte ID führen zu 400. Die IDs finden Sie in der Referenz zur Animationsbibliothek.
Meshy gibt eine Datei mit einem Animationsclip pro Aktion zurück, was sich für eine Zustandsmaschine in einer Game Engine eignet. Meshy berechnet für jede Aktion in der Liste. Siehe Preise.
Eine Liste mit einer einzelnen ID funktioniert genauso, als würden Sie diese ID als action_id senden.
Eine Animation, deren rig_type nicht zum Rig passt, führt zu 400.
Name
motion_task_id
Type
string
Erforderlich
Description
Erforderlich, sofern Sie nicht action_id oder action_ids senden. Die ID einer Text-to-Motion-Aufgabe, deren Clip anstelle einer voreingestellten Aktion angewendet werden soll. Die Aufgabe muss den Status SUCCEEDED haben, und das Rig muss ein Biped sein.
Meshy überträgt den Clip auf den gerigten Charakter (Retargeting). Der Clip wird beim Erstellen dieser Aufgabe kopiert, sodass diese Aufgabe nicht betroffen ist, wenn die Text-to-Motion-Aufgabe später abläuft oder Sie sie löschen. Meshy bewahrt die Dateien der Text-to-Motion-Aufgabe 3 Tage lang auf, wenden Sie den Clip also vorher an.
In den GLB- und FBX-Dateien heißt der Clip retarget_clip.
Name
post_process
Type
object
Description
Nachbearbeitung für die Animationsausgabe. Lassen Sie den Parameter weg, um die Standard-Animationsdateien zu erhalten.
Mit motion_task_id kann das Retargeting eine ausschließlich GLB-basierte Animation erzeugen. Wenn Sie post_process senden und keine FBX-Datei verfügbar ist, schlägt die Aufgabe mit einem task_error fehl, und Meshy erstattet Ihre Credits zurück. Ohne post_process ist die Aufgabe erfolgreich, und animation_fbx_url ist leer.
Gilt nur wenn post_process is set
Name
operation_type
Type
string
Description
Die auszuführende Operation. Ohne diesen Parameter erstellt Meshy keine zusätzliche Datei. Ein Wert, der nicht in der folgenden Liste steht, führt zu 400.
Verfügbare Werte:
change_fps: ändert die Bildrate auf fps
fbx2usdz: konvertiert die Animation in USDZ
extract_armature: extrahiert die Armature als FBX-Datei
Name
fps
Type
integer
Standard 30
Description
Die Bildrate, auf die geändert werden soll, eine von 24, 25, 30 oder 60. Gilt nur, wenn operation_type den Wert change_fps hat. Jeder andere Wert führt zu 400.
Bei action_ids gibt die Aufgabe eine zusammengeführte Datei zurück anstelle einer Datei pro Aktion. animation_glb_url und animation_fbx_url verweisen jeweils auf eine Datei, die jede angeforderte Aktion als separaten Clip enthält. In dieser Datei:
Clip-Reihenfolge: die Reihenfolge des Arrays action_ids, nicht die numerische Reihenfolge der IDs.
Clip-Namen: der Name der Animation in der Bibliothek. Diese stimmen mit den Namen überein, die Sie erhalten, wenn Sie alle Animationen eines Charakters als eine Datei aus der Meshy-Web-App exportieren. Wenn zwei angeforderte IDs denselben Clip-Namen haben, fügt Meshy die action_id zum späteren hinzu, um eindeutige Namen zu gewährleisten.
Nachbearbeitung: Meshy wendet sie auf die zusammengeführte Datei an, nicht auf jeden einzelnen Clip.
Rückgabewerte
Das Feld result der Antwort enthält die ID der neuen Animations-Aufgabe.
Fehlermodi
Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung nennt das gefundene Problem. Zum Beispiel:
Fehlender Parameter: rig_task_id fehlt, oder keiner von action_id, action_ids und motion_task_id wurde gesendet.
Widersprüchliche Parameter: Die Anfrage enthält mehr als einen von action_id, action_ids und motion_task_id. Senden Sie nur einen.
Ungültige Rig-Aufgabe: rig_task_id ist keine gültige Aufgaben-ID, ist keine Rigging-Aufgabe oder verweist auf eine Aufgabe, die nicht erfolgreich war.
Ungültige Aktions-ID: Eine action_id oder ein Eintrag in action_ids ist keine gültige Animation.
Zu viele Aktionen: action_ids enthält mehr als 10 IDs.
Doppelte Aktionen: action_ids enthält dieselbe ID mehrfach.
Motion-Aufgabe nicht bereit: Die motion_task_id-Aufgabe hat den Status SUCCEEDED noch nicht erreicht.
Nicht unterstütztes Rig: motion_task_id benötigt ein Biped-Rig, und Meshy lehnt ein Vierbeiner-Rig ab.
Rig-Typ-Abweichung: Der rig_type einer Animation passt nicht zum Rig.
Korrigieren Sie die 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 hat nicht genügend Credits für diese Aufgabe, oder das Konto hat ein Credit-Limit erreicht. Prüfen Sie Ihr Credit-Guthaben und versuchen Sie es erneut.
Kostenloser Plan: Das Erstellen einer Aufgabe erfordert einen kostenpflichtigen Plan. Aktualisieren Sie Ihren Plan in Ihren Abonnement-Einstellungen und versuchen Sie es erneut.
Name
403 - Forbidden
Description
Die Aufgabe rig_task_id ist ein Flachrelief-Modell, das dieser Endpunkt nicht animieren kann. Die Meldung lautet This model type does not support this operation. Riggen Sie ein anderes Modell.
Name
404 - Not Found
Description
Meshy kann eine Aufgabe oder Datei, die die Anfrage benötigt, nicht finden. Einer der folgenden Fälle trifft zu:
Meshy kann die Aufgabe rig_task_id nicht unter Ihren Aufgaben finden. Überprüfen Sie die ID.
Meshy hat die Dateien der Aufgabe rig_task_id nach ihrem expires_at gelöscht. Riggen Sie den Charakter erneut.
Meshy kann die Aufgabe motion_task_id nicht finden. Überprüfen Sie die ID.
Der Bewegungsclip ist abgelaufen, da Meshy die Dateien einer Text-to-Motion-Aufgabe 3 Tage lang aufbewahrt. Erstellen Sie eine weitere Text-to-Motion-Aufgabe.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie und versuchen Sie es dann erneut. Siehe Ratenbegrenzungen.
// 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 der zu löschenden Aufgabe.
Aufgabenstatus
Das Löschen einer PENDING-Aufgabe erstattet die Credits, die bei ihrer Erstellung verwendet wurden.
Eine IN_PROGRESS-Aufgabe kann nicht gelöscht werden. Die Anfrage gibt 409 Conflict zurück,
und die Aufgabe läuft weiter. Meshy erstattet keine Aufgabe, die bereits gestartet wurde,
sodass das Löschen Sie sowohl die Credits als auch das Ergebnis kosten würde. Warten Sie,
bis sie den Status SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie sie dann.
Das Löschen einer Aufgabe in einem Endstatus (SUCCEEDED, FAILED oder CANCELED)
erstattet ihre Credits nicht.
Rückgabewerte
200 OK, wenn die Aufgabe gelöscht wurde, oder 409 Conflict, wenn die Aufgabe
IN_PROGRESS ist.
Gibt eine paginierte Liste Ihrer Animation-Tasks zurück, neueste zuerst. Um durch die Liste zu blättern, verwenden Sie page_num und page_size.
Tasks, die Sie über die API erstellen, erscheinen nicht unter Meine Assets in der Web-App, daher verwalten Sie sie über die API. Um einen Task zu finden, dessen ID Sie nicht mehr haben, verwenden Sie diesen Endpunkt.
// Error event exampleevent: errordata: {"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: messagedata: {"id": "018c425b-b2c6-727e-d333-3c1887i9h791","progress": 0,"status": "PENDING"}event: messagedata: {"id": "018c425b-b2c6-727e-d333-3c1887i9h791","progress": 50,"status": "IN_PROGRESS"}event: messagedata: { // Example of a SUCCEEDED task stream item, with the same structure as the 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": null,"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?..." }}
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.
Ein Animation-Task-Objekt beschreibt eine Animation, die auf einen geriggten Charakter angewendet wird. Es enthält den Status, den progress und die Animationsdateien, wenn der Task erfolgreich war.
Die Task-ID. Behandeln Sie sie als eine undurchsichtige Zeichenkette und verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer animate.
Name
status
Type
string
Description
Der Task-Status, entweder PENDING, IN_PROGRESS, SUCCEEDED, FAILED oder CANCELED.
Name
progress
Type
integer
Description
Wie viel des Tasks erledigt ist, in Prozent. Der Wert ist 0, bis der Task startet, und 100, wenn er erfolgreich ist.
Name
created_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task erstellt wurde, in Unix-Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task gestartet wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task startet.
Name
finished_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task abgeschlossen wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task abgeschlossen ist.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, zu dem die Ergebnisdateien des Tasks ablaufen, in Unix-Millisekunden.
Name
task_error
Type
object
Description
Die Fehlerdetails, wenn der Task fehlschlägt. Der Wert ist null, außer wenn der Status FAILED ist. Siehe Fehler.
Name
consumed_credits
Type
integer
Description
Die Anzahl der vom Task verbrauchten Credits. Vorhanden, wenn der Status PENDING, IN_PROGRESS oder SUCCEEDED ist. Bei einem FAILED-Task ist der Wert 0, da Meshy die Credits erstattet, wenn ein Task fehlschlägt.
Name
result
Type
object
Description
Download-URLs für die Animationsdateien, wenn der Task den Status SUCCEEDED hat.
Name
animation_glb_url
Type
string
Description
Die Animation als GLB-Datei. Bei einem mit action_ids erstellten Task enthält diese eine Datei jede angeforderte Aktion als separaten Clip.
Name
animation_fbx_url
Type
string
Description
Die Animation als FBX-Datei. Bei einem mit action_ids erstellten Task enthält diese eine Datei jede angeforderte Aktion als separaten Clip.
Name
processed_usdz_url
Type
string
Description
Die verarbeitete Animation als USDZ-Datei.
Name
processed_armature_fbx_url
Type
string
Description
Die verarbeitete Armature als FBX-Datei.
Name
processed_animation_fps_fbx_url
Type
string
Description
Die Animation mit der geänderten Bildrate, als FBX-Datei, zum Beispiel wenn Sie die Operation change_fps verwendet haben.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der Tasks, die in der Warteschlange vor diesem liegen. Der Wert ist nur aussagekräftig, solange der Task PENDING ist. Das Feld wird weggelassen, wenn der Wert 0 ist.
Gibt jede Animation in der Bibliothek zurück, sortiert nach action_id. Die Antwort ist die vollständige Liste, ohne Seitenaufteilung, sodass ein einziger Aufruf genügt, um einen Aktionsauswähler zu füllen. Filter schränken das Ergebnis ein. Um alle Animationen zu erhalten, lassen Sie sie einfach alle weg.
Um dieselbe Liste mit einer animierten Vorschau jeder Aktion zu durchsuchen, siehe die Animationsbibliothek-Referenz.
Zu suchender Text. Meshy gibt die Animationen zurück, deren name oder key diesen Text enthält, ohne Berücksichtigung der Groß-/Kleinschreibung. Meshy vergleicht den Text wörtlich, sodass % und _ keine Platzhalter sind.
Name
category
Type
string
Description
Die aufzulistende Kategorie, als exakte Übereinstimmung. Eine unbekannte Kategorie gibt eine leere Liste zurück.
Die Kategorien von biped-Animationen:
WalkAndRun
BodyMovements
DailyActions
Fighting
Dancing
Die Kategorie einer quadruped-Animation ist ein Tier, zum Beispiel dog oder horse.
Name
sub_category
Type
string
Description
Die aufzulistende Unterkategorie, als exakte Übereinstimmung. Sie können sie ohne category senden. Namen von Unterkategorien sind nicht eindeutig über Kategorien hinweg. Zum Beispiel ist Transitioning sowohl unter Fighting als auch unter DailyActions zu finden. Ohne category erfasst der Filter daher die Unterkategorie in jeder Kategorie.
Name
action_ids
Type
string
Description
Die zurückzugebenden Animationen, als bis zu 200 kommagetrennte action_id-Werte. Verwenden Sie dies, um bestimmte IDs nachzuschlagen, anstatt zu durchsuchen. Mehr als 200 IDs führen zu 400.
Die Antwort lässt eine ID aus, die keiner Animation entspricht. Sie können diesen Filter also auch nutzen, um zu prüfen, ob von Ihnen gespeicherte IDs noch verfügbar sind.
Filter kombinieren
Meshy wendet die Filter gemeinsam an. Jeder schränkt das Ergebnis weiter ein, sodass Meshy eine Animation nur zurückgibt, wenn sie allen entspricht. Innerhalb eines Filters kann jeder seiner Werte übereinstimmen. Zum Beispiel erfasst searchname oder key, und action_ids erfasst jede ID in der Liste.
Eine Kombination ohne Überschneidung gibt daher ein leeres Array zurück, keinen Fehler. Aktion 92 ist „Double Combo Attack“, eine Fighting-Animation. Zum Beispiel:
?action_ids=92&category=Fighting gibt Aktion 92 zurück.
?action_ids=92&category=Dancing gibt [] zurück, da sie keine Dancing-Animation ist.
?action_ids=92&search=walk gibt [] zurück, da ihr Name nicht walk entspricht.
Um bestimmte Animationen in beliebiger Kategorie zu erhalten, senden Sie action_ids allein.
Eine Animationsaufgabe erstellen akzeptiert jede action_id, die dieser Endpunkt zurückgibt, und dieser Endpunkt gibt jede ID zurück, die bei der Erstellung akzeptiert wird. Keiner der beiden enthält zurückgezogene Animationen. Wenn Sie die Bibliothek zwischenspeichern, aktualisieren Sie sie von Zeit zu Zeit, damit keine zurückgezogene ID in Ihrem Auswähler verbleibt.
Der Wert, der als action_id gesendet wird, wenn Sie eine Animation-Aufgabe erstellen. Er ist eindeutig und stabil, aber nicht fortlaufend. Ausrangierte Animationen hinterlassen Lücken in der Nummerierung, gehen Sie also nicht davon aus, dass jede ID in einem Bereich gültig ist.
Name
name
Type
string
Description
Der Anzeigename der Animation. Er ist nicht eindeutig, da sich manche Animationen den Namen mit einer anderen Variante teilen. Um eine Animation zu identifizieren, verwenden Sie action_id oder key.
Name
key
Type
string
Description
Ein eindeutiger, stabiler Slug für die Animation. Verwenden Sie ihn, wenn Sie eine nicht-numerische ID benötigen, um Ihren eigenen Speicher zu indizieren.
Name
category
Type
string
Description
Die übergeordnete Gruppe, zum Beispiel Fighting. Bei einer quadruped-Animation ist es ein Tier, zum Beispiel dog oder horse.
Name
sub_category
Type
string
Description
Die Gruppe innerhalb der Kategorie, zum Beispiel AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL einer animierten GIF-Vorschau der Aktion. Sie können sie direkt in Ihrer eigenen Auswahl anzeigen.
Name
rig_type
Type
string
Description
Die Art des Rigs, auf dem die Animation abgespielt wird, biped oder quadruped. Sie entspricht dem animation_type der Rigging-Aufgabe. Ein Rig akzeptiert nur Animationen des eigenen Typs.