lowpoly sera retiré le 30 oct. 2026. meshy-7 sera retiré en tant que modèle de génération 3D le 31 déc. 2026 ; il reste disponible en tant que modèle de texture. Changez de modèle avant ces dates pour éviter les erreurs de requête. Voir toutes les dépréciations
API Animation
Appliquez des Animations à des personnages riggés, et listez les Animations que vous pouvez appliquer.
Crée une tâche d'Animation, qui applique une animation à un personnage que vous avez riggé précédemment. L'animation peut être l'une des suivantes :
Une action prédéfinie de la bibliothèque d'animations (action_id)
Plusieurs actions prédéfinies fusionnées en un seul fichier (action_ids)
Un clip de mouvement que vous avez généré avec l'API Text to Motion (motion_task_id)
Vous pouvez aussi post-traiter la sortie. La tâche s'exécute en arrière-plan. Pour connaître la durée habituelle d'une tâche, consultez Temps de traitement.
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"}
Paramètres
Name
rig_task_id
Type
string
Requis
Description
L'ID de la tâche de Rigging dont le personnage doit être animé, provenant de POST /openapi/v1/rigging. La tâche doit avoir le statut SUCCEEDED.
Envoyez exactement l'un des paramètres action_id, action_ids ou motion_task_id.
Le rig_type de l'animation doit correspondre au rig, sinon la requête renvoie 400. Toute animation quadruped fonctionne sur n'importe quel rig quadrupède, quel que soit l'animal nommé par sa category.
Name
action_ids
Type
array of integers
Requis
Description
Requis sauf si vous envoyez action_id ou motion_task_id. Les ID de 1 à 10 animations prédéfinies à appliquer en même temps, sans répétition. Plus de 10 ID, ou un ID répété, renvoie 400. Pour les ID, consultez la référence de la Bibliothèque d'animations.
Meshy renvoie un fichier contenant un clip d'animation par action, ce qui convient à une machine à états dans un moteur de jeu. Meshy facture chaque action de la liste. Consultez Tarification.
Une liste avec un seul ID fonctionne de la même manière que l'envoi de cet ID en tant qu'action_id.
Une animation dont le rig_type ne correspond pas au rig renvoie 400.
Name
motion_task_id
Type
string
Requis
Description
Requis sauf si vous envoyez action_id ou action_ids. L'ID d'une tâche Text to Motion dont le clip doit être appliqué à la place d'une action prédéfinie. La tâche doit avoir le statut SUCCEEDED, et le rig doit être un bipède.
Meshy reciblage (retarget) le clip sur le personnage riggé. Il copie le clip au moment de la création de cette tâche, donc cette tâche n'est pas affectée si la tâche Text to Motion expire plus tard ou si vous la supprimez. Meshy conserve les fichiers d'une tâche Text to Motion pendant 3 jours, donc appliquez le clip avant cette échéance.
Dans les fichiers GLB et FBX, le clip est nommé retarget_clip.
Name
post_process
Type
object
Description
Post-traitement pour la sortie d'animation. Omettez-le pour obtenir les fichiers d'animation standard.
Avec motion_task_id, le reciblage peut produire une animation uniquement en GLB. Si vous envoyez post_process et qu'aucun fichier FBX n'est disponible, la tâche échoue avec une task_error, et Meshy rembourse vos crédits. Sans post_process, la tâche réussit, et animation_fbx_url est vide.
S'applique uniquement quand post_process is set
Name
operation_type
Type
string
Description
L'opération à exécuter. Sans elle, Meshy ne crée pas de fichier supplémentaire. Une valeur absente de la liste suivante renvoie 400.
Valeurs disponibles :
change_fps : change le taux d'images (frame rate) en fps
fbx2usdz : convertit l'animation en USDZ
extract_armature : extrait l'armature sous forme de fichier FBX
Name
fps
Type
integer
défaut 30
Description
Le taux d'images vers lequel changer, l'une des valeurs 24, 25, 30 ou 60. S'applique uniquement lorsque operation_type vaut change_fps. Toute autre valeur renvoie 400.
Avec action_ids, la tâche renvoie un seul fichier fusionné au lieu d'un fichier par action. animation_glb_url et animation_fbx_url pointent chacun vers un fichier qui contient chaque action demandée sous forme de clip distinct. Dans ce fichier :
Ordre des clips : l'ordre du tableau action_ids, et non l'ordre numérique des ID.
Noms des clips : le nom de l'animation dans la bibliothèque. Ils correspondent aux noms obtenus lorsque vous exportez toutes les animations d'un personnage en un seul fichier depuis l'application web Meshy. Si deux ID demandés ont le même nom de clip, Meshy ajoute l'action_id au second pour garder des noms uniques.
Post-traitement : Meshy l'applique au fichier fusionné, et non à chaque clip.
Retours
Le champ result de la réponse contient l'ID de la nouvelle tâche d'Animation.
Modes d'échec
Name
400 - Bad Request
Description
La requête ne peut pas s'exécuter. Le message d'erreur indique le problème détecté. Par exemple :
Paramètre manquant : rig_task_id est absent, ou aucun des paramètres action_id, action_ids et motion_task_id n'a été envoyé.
Paramètres en conflit : la requête contient plus d'un paramètre parmi action_id, action_ids et motion_task_id. N'en envoyez qu'un seul.
Tâche de rig invalide : rig_task_id n'est pas un ID de tâche valide, n'est pas une tâche de Rigging, ou pointe vers une tâche qui n'a pas réussi.
ID d'action invalide : un action_id, ou une entrée de action_ids, n'est pas une animation valide.
Trop d'actions : action_ids contient plus de 10 ID.
Actions dupliquées : action_ids contient le même ID plus d'une fois.
Tâche de mouvement non prête : la tâche motion_task_id n'a pas encore atteint le statut SUCCEEDED.
Rig non pris en charge : motion_task_id nécessite un rig bipède, et Meshy rejette un rig quadrupède.
Incompatibilité de type de rig : le rig_type d'une animation ne correspond pas au rig.
Corrigez la requête, puis renvoyez-la. Consultez Erreurs.
Name
401 - Unauthorized
Description
La clé API est absente ou invalide. Vérifiez l'en-tête Authorization.
Name
402 - Payment Required
Description
Par exemple :
Crédits insuffisants : le compte n'a pas assez de crédits pour cette tâche, ou le compte a atteint une limite de crédits. Vérifiez votre solde de crédits, puis réessayez.
Plan gratuit : la création d'une tâche nécessite un plan payant. Mettez à niveau votre plan dans vos paramètres d'abonnement, puis réessayez.
Name
403 - Forbidden
Description
La tâche rig_task_id correspond à un modèle en bas-relief, que ce point de terminaison ne peut pas animer. Le message est This model type does not support this operation. Riggez un autre modèle.
Name
404 - Not Found
Description
Meshy ne trouve pas une tâche ou un fichier dont la requête a besoin. L'un des cas suivants s'applique :
Meshy ne trouve pas la tâche rig_task_id parmi vos tâches. Vérifiez l'ID.
Meshy a supprimé les fichiers de la tâche rig_task_id après son expires_at. Riggez à nouveau le personnage.
Meshy ne trouve pas la tâche motion_task_id. Vérifiez l'ID.
Le clip de mouvement a expiré, car Meshy conserve les fichiers d'une tâche Text to Motion pendant 3 jours. Créez une autre tâche Text to Motion.
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit. Attendez, puis réessayez. Consultez Limites de débit.
// 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."}
Paramètres de chemin
Name
id
Type
path
Description
L'ID de la tâche à supprimer.
Statut de la tâche
Supprimer une tâche PENDING rembourse les crédits utilisés lors de sa création.
Une tâche IN_PROGRESS ne peut pas être supprimée. La requête renvoie 409 Conflict,
et la tâche continue de s'exécuter. Meshy ne rembourse pas une tâche qui a démarré,
donc la supprimer vous ferait perdre à la fois les crédits et le résultat. Attendez
qu'elle atteigne le statut SUCCEEDED, FAILED ou CANCELED, puis supprimez-la.
Supprimer une tâche dans un statut final (SUCCEEDED, FAILED ou CANCELED)
ne rembourse pas ses crédits.
Retours
200 OK lorsque la tâche est supprimée, ou 409 Conflict lorsque la tâche est
IN_PROGRESS.
Renvoie une liste paginée de vos tâches d'Animation, les plus récentes en premier. Pour parcourir la liste, utilisez page_num et page_size.
Les tâches que vous créez via l'API n'apparaissent pas dans My Assets dans l'application web, vous les gérez donc via l'API. Pour retrouver une tâche dont vous n'avez plus l'ID, utilisez ce point de terminaison.
// 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?..." }}
Paramètres
Name
id
Type
path
Description
L'ID de la tâche provenant de la réponse de création.
Chaque événement contient l'objet de tâche complet, avec la même structure que celle renvoyée par le point de terminaison Get. Tant que la tâche est PENDING ou IN_PROGRESS, ses champs de résultat n'ont pas encore de valeurs.
Un objet de tâche Animation décrit une animation appliquée à un personnage riggé. Il contient le statut, la progression et les fichiers d'animation lorsque la tâche réussit.
L'ID de la tâche. Traitez-le comme une chaîne opaque et ne vous fiez pas à son format.
Name
type
Type
string
Description
Le type de tâche, toujours animate.
Name
status
Type
string
Description
Le statut de la tâche, l'un des suivants : PENDING, IN_PROGRESS, SUCCEEDED, FAILED, ou CANCELED.
Name
progress
Type
integer
Description
L'avancement de la tâche, en pourcentage. Il est à 0 tant que la tâche n'a pas démarré et à 100 quand elle réussit.
Name
created_at
Type
timestamp
Description
Horodatage de création de la tâche, en millisecondes Unix.
Name
started_at
Type
timestamp
Description
Horodatage de démarrage de la tâche, en millisecondes Unix. Il est à 0 tant que la tâche n'a pas démarré.
Name
finished_at
Type
timestamp
Description
Horodatage de fin de la tâche, en millisecondes Unix. Il est à 0 tant que la tâche n'est pas terminée.
Name
expires_at
Type
timestamp
Description
Horodatage d'expiration des fichiers de résultat de la tâche, en millisecondes Unix.
Name
task_error
Type
object
Description
Les détails de l'erreur en cas d'échec de la tâche. Il est à null sauf si le statut est FAILED. Voir Erreurs.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits consommés par la tâche. Présent quand le statut est PENDING, IN_PROGRESS, ou SUCCEEDED. Il est à 0 pour une tâche FAILED, car Meshy rembourse les crédits lorsqu'une tâche échoue.
Name
result
Type
object
Description
Les URL de téléchargement des fichiers d'animation, lorsque la tâche a le statut SUCCEEDED.
Name
animation_glb_url
Type
string
Description
L'animation sous forme de fichier GLB. Pour une tâche créée avec action_ids, ce fichier unique contient chaque action demandée sous forme de clip séparé.
Name
animation_fbx_url
Type
string
Description
L'animation sous forme de fichier FBX. Pour une tâche créée avec action_ids, ce fichier unique contient chaque action demandée sous forme de clip séparé.
Name
processed_usdz_url
Type
string
Description
L'animation traitée sous forme de fichier USDZ.
Name
processed_armature_fbx_url
Type
string
Description
L'armature traitée sous forme de fichier FBX.
Name
processed_animation_fps_fbx_url
Type
string
Description
L'animation à la fréquence d'images modifiée, sous forme de fichier FBX, par exemple lorsque vous avez utilisé l'opération change_fps.
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches qui précèdent celle-ci dans la file d'attente. Cette valeur n'a de sens que tant que la tâche est PENDING. Ce champ est omis quand la valeur est 0.
Renvoie chaque animation de la bibliothèque, classée par action_id. La réponse est la liste complète, sans pagination, de sorte qu'un seul appel peut remplir un sélecteur d'actions. Les filtres réduisent le résultat. Pour obtenir toutes les animations, omettez-les tous.
Texte à rechercher. Meshy renvoie les animations dont le name ou le key contient ce texte, sans tenir compte de la casse. Meshy fait correspondre le texte littéralement, donc % et _ ne sont pas des caractères génériques.
Name
category
Type
string
Description
La catégorie à lister, en correspondance exacte. Une catégorie inconnue renvoie une liste vide.
Les catégories des animations biped :
WalkAndRun
BodyMovements
DailyActions
Fighting
Dancing
La catégorie d'une animation quadruped est un animal, par exemple dog ou horse.
Name
sub_category
Type
string
Description
La sous-catégorie à lister, en correspondance exacte. Vous pouvez l'envoyer sans category. Les noms de sous-catégories ne sont pas uniques entre les catégories. Par exemple, Transitioning existe à la fois sous Fighting et DailyActions. Donc sans category, le filtre correspond à la sous-catégorie dans chaque catégorie.
Name
action_ids
Type
string
Description
Les animations à renvoyer, sous forme d'au maximum 200 valeurs action_id séparées par des virgules. Utilisez-le pour rechercher des ID spécifiques plutôt que de parcourir la liste. Plus de 200 ID renvoie 400.
La réponse omet un ID qu'aucune animation ne possède. Vous pouvez donc aussi utiliser ce filtre pour vérifier si les ID que vous avez stockés sont toujours disponibles.
Combinaison des filtres
Meshy applique les filtres ensemble. Chacun réduit le résultat, de sorte que Meshy ne renvoie une animation que si elle correspond à tous les filtres. Au sein d'un même filtre, n'importe laquelle de ses valeurs peut correspondre. Par exemple, search correspond à name ou key, et action_ids correspond à n'importe quel ID de la liste.
Ainsi, une combinaison sans chevauchement renvoie un tableau vide, et non une erreur. L'action 92 est « Double Combo Attack », une animation Fighting. Par exemple :
Créer une tâche d'Animation accepte chaque action_id que ce point de terminaison renvoie, et ce point de terminaison renvoie chaque ID que la création accepte. Aucun des deux n'inclut les animations retirées. Si vous mettez la bibliothèque en cache, actualisez-la de temps en temps, afin qu'un ID retiré ne reste pas dans votre sélecteur.
La valeur à envoyer en tant que action_id lorsque vous créez une tâche d'Animation. Elle est unique et stable, mais non contiguë. Les animations retirées laissent des trous dans la numérotation, ne supposez donc pas que chaque identifiant d'une plage est valide.
Name
name
Type
string
Description
Le nom d'affichage de l'animation. Il n'est pas unique, car certaines animations partagent un nom avec une autre variante. Pour identifier une animation, utilisez action_id ou key.
Name
key
Type
string
Description
Un slug unique et stable pour l'animation. Utilisez-le lorsque vous avez besoin d'un identifiant non numérique pour indexer votre propre stockage.
Name
category
Type
string
Description
Le groupe de premier niveau, par exemple Fighting. Pour une animation quadruped, il s'agit d'un animal, par exemple dog ou horse.
Name
sub_category
Type
string
Description
Le groupe au sein de la catégorie, par exemple AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL d'un aperçu GIF animé de l'action. Vous pouvez l'afficher directement dans votre propre sélecteur.
Name
rig_type
Type
string
Description
Le type de rig sur lequel l'animation est jouée, biped ou quadruped. Il correspond à animation_type de la tâche de Rigging. Un rig n'accepte que les animations de son propre type.