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 issue 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 un seul des paramètres action_id, action_ids et motion_task_id.
Requis sauf si vous envoyez action_id ou motion_task_id. Les ID de 1 à 10 animations prédéfinies à appliquer en une seule fois, 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 avec 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 que action_id.
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 retargete 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 par la suite ou si vous la supprimez. Meshy conserve les fichiers d'une tâche Text to Motion pendant 3 jours, veillez donc à appliquer le clip avant cette échéance.
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 retargeting peut produire une animation disponible uniquement en GLB. Si vous envoyez post_process et qu'aucun fichier FBX n'est disponible, la tâche échoue avec un 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 ce paramètre, Meshy ne crée aucun fichier supplémentaire. Une valeur absente de la liste suivante renvoie 400.
Valeurs disponibles :
change_fps : change la fréquence d'images 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
La fréquence d'images vers laquelle changer, l'une des valeurs 24, 25, 30 ou 60. S'applique uniquement lorsque operation_type est 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 seul 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. Ces noms correspondent à ceux que vous obtenez 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 individuellement.
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 manquant, 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 des paramètres 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 dans action_ids, n'est pas une animation valide.
Trop d'actions : action_ids contient plus de 10 ID.
Actions en double : action_ids contient plusieurs fois le même ID.
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.
Corrigez la requête, puis renvoyez-la. Consultez Erreurs.
Name
401 - Unauthorized
Description
La clé API est manquante 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 est 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 modèle différent.
Name
404 - Not Found
Description
Meshy ne trouve pas une tâche ou un fichier requis par la requête. 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": {"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}
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, selon 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'une des valeurs PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.
Name
progress
Type
integer
Description
La part de la tâche déjà effectuée, en pourcentage. Elle vaut 0 jusqu'à ce que la tâche démarre et 100 lorsqu'elle réussit.
Name
created_at
Type
timestamp
Description
Heure de création de la tâche, en millisecondes Unix.
Name
started_at
Type
timestamp
Description
Heure de démarrage de la tâche, en millisecondes Unix. Elle vaut 0 jusqu'à ce que la tâche démarre.
Name
finished_at
Type
timestamp
Description
Heure de fin de la tâche, en millisecondes Unix. Elle vaut 0 jusqu'à ce que la tâche se termine.
Name
expires_at
Type
timestamp
Description
Heure à laquelle les fichiers résultants de la tâche expirent, en millisecondes Unix.
Name
task_error
Type
object
Description
Les détails de l'erreur lorsque la tâche échoue. Voir Erreurs.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits utilisés par la tâche. Présent lorsque le statut est PENDING, IN_PROGRESS ou SUCCEEDED. Il vaut 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 distinct.
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 distinct.
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 devançant celle-ci dans la file d'attente. Cette valeur n'a de sens que tant que la tâche est PENDING.
Retourne chaque animation de la bibliothèque, trié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 restreignent le résultat. Pour obtenir toutes les animations, omettez-les tous.
Pour parcourir la même liste avec un aperçu animé de chaque action, consultez la référence de la Bibliothèque d'animations.
Texte à rechercher. Meshy retourne 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 retourne une liste vide.
Valeurs disponibles :
WalkAndRun
BodyMovements
DailyActions
Fighting
Dancing
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 se trouve à la fois sous Fighting et sous DailyActions. Ainsi, sans category, le filtre correspond à la sous-catégorie dans toutes les catégories.
Name
action_ids
Type
string
Description
Les animations à retourner, sous forme de jusqu'à 200 valeurs action_id séparées par des virgules. Utilisez-le pour rechercher des IDs spécifiques plutôt que de parcourir la liste. Plus de 200 IDs retourne 400.
La réponse omet un ID qu'aucune animation ne possède. Vous pouvez donc aussi utiliser ce filtre pour vérifier si des IDs que vous avez stockés sont toujours disponibles.
Combinaison des filtres
Meshy applique les filtres ensemble. Chacun restreint le résultat, de sorte que Meshy ne retourne 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 retourne un tableau vide, pas 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 retourne, et ce point de terminaison retourne chaque ID que la création accepte. Aucun des deux n'inclut les animations retirées. Si vous mettez en cache la bibliothèque, actualisez-la de temps en temps, afin qu'un ID retiré ne reste pas dans votre sélecteur.
La valeur à envoyer comme action_id lorsque vous créez une tâche Animation. Elle est unique et stable, mais pas contiguë. Les animations retirées laissent des trous dans la numérotation, donc ne présumez 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 identifiant 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.
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.