API Animation

Endpoints permettant de découvrir les animations disponibles et de les appliquer à des personnages dotés d'un rig.

POST/openapi/v1/animations

Créer une tâche d'animation

Ce point de terminaison vous permet de créer une nouvelle tâche pour appliquer une animation à un personnage préalablement rigged — soit une action prédéfinie de la bibliothèque d'animations (action_id), soit un clip de mouvement que vous avez généré avec l'API Text to Motion (motion_task_id). Comprend des options de post-traitement.

Paramètres

Name
rig_task_id
Type
string
Requis
Description
L'id d'une tâche de rigging terminée avec succès (issue de POST /openapi/v1/rigging). Le personnage de cette tâche sera animé.
Name
action_id
Type
integer
Description
L'identifiant de l'action d'animation prédéfinie à appliquer. Consultez la référence de la bibliothèque d'animations pour une liste complète des animations disponibles. Fournissez exactement un seul des deux paramètres action_id ou motion_task_id.
Name
motion_task_id
Type
string
Description
L'id d'une tâche Text to Motion terminée avec succès à appliquer à la place d'une action prédéfinie. Le clip généré est reciblé sur le personnage rigged, et le clip est capturé au moment de la création, de sorte que cette tâche n'est pas affectée si la tâche source expire ou est supprimée par la suite. Les assets de la tâche source sont conservés pendant 3 jours — appliquez le clip avant son expiration. Nécessite un rig bipède. Fournissez exactement un seul des deux paramètres action_id ou motion_task_id.
Name
post_process
Type
object
Description
Post-traitement optionnel pour la sortie d'animation. Omettez-le pour recevoir les fichiers d'animation standard.

S'applique uniquement quand post_process is set

Name
operation_type
Type
string
Requis
Description
Le type d'opération à effectuer. Valeurs disponibles : change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
défaut 30
Description
La fréquence d'images cible. Applicable uniquement lorsque operation_type est change_fps. Valeurs autorisées : 24, 25, 30, 60.

Avec motion_task_id, le recalage peut produire une animation disponible uniquement en GLB. Si vous avez demandé post_process et qu'aucun FBX n'est disponible, la tâche échoue avec une task_error et vos crédits sont remboursés automatiquement ; sans post_process, la tâche réussit et animation_fbx_url est vide.

Retours

La propriété result de la réponse contient l'id de la tâche de la nouvelle tâche d'animation créée.

Modes d'échec

Name
400 - Bad Request
Description
La requête était inacceptable. Causes courantes :
- Paramètre manquant : rig_task_id est manquant, ou ni action_id ni motion_task_id n'ont été fournis.
- Paramètres en conflit : à la fois action_id et motion_task_id ont été fournis — ils s'excluent mutuellement.
- Tâche de rigging invalide : rig_task_id est invalide ou fait référence à une tâche ayant échoué ou inexistante.
- ID d'action invalide : action_id ne correspond à aucune animation valide.
- 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 ; les rigs quadrupèdes sont rejetés.
Name
401 - Unauthorized
Description
L'authentification a échoué. Veuillez vérifier votre clé API.
Name
402 - Payment Required
Description
Crédits insuffisants pour effectuer cette tâche.
Name
404 - Not Found
Description
La tâche de rigging spécifiée par rig_task_id est introuvable, la tâche de mouvement spécifiée par motion_task_id est introuvable, ou le clip de mouvement a expiré (les assets de la tâche source sont conservés pendant 3 jours).
Name
429 - Too Many Requests
Description
Vous avez dépassé votre limite de débit.

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

Récupérer une tâche d'Animation

Ce point de terminaison vous permet de récupérer une tâche d'animation à partir d'un id de tâche valide. Consultez L'objet tâche d'animation pour voir les propriétés incluses.

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche d'animation à récupérer.

Retours

La réponse contient l'objet Animation Task. Consultez la section L'objet tâche d'animation pour plus de détails.

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

Supprimer une tâche d'Animation

Ce point de terminaison supprime définitivement une tâche d'animation, y compris tous les modèles et données associés. Cette action est irréversible.

Paramètres de chemin

Name
id
Type
path
Description
L'ID de la tâche d'animation à supprimer.

Retours

Retourne 200 OK en cas de succès.

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

List Animation Tasks

Retourne une liste paginée des tâches d'Animation de l'appelant, les plus récentes en premier. Pagination standard via page_num et page_size.

Notez que les tâches créées via l'API sont gérées via l'API — elles n'apparaissent pas dans « Mes Assets » de l'application web. Utilisez ce point de terminaison pour retrouver une tâche dont vous n'avez plus l'ID.

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

Diffuser en continu une tâche d'Animation

Ce point de terminaison diffuse en continu les mises à jour en temps réel d'une tâche d'Animation à l'aide de Server-Sent Events (SSE).

Paramètres

Name
id
Type
path
Description
Identifiant unique de la tâche d'Animation à diffuser en continu.

Retourne

Retourne un flux d'objets de tâche d'Animation sous forme de Server-Sent Events.

Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse n'inclura que les champs progress et status nécessaires.

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

L'objet Animation Task représente l'unité de travail pour appliquer une animation à un personnage doté d'un rig.

Propriétés

Name
id
Type
string
Description
Identifiant unique de la tâche.
Name
type
Type
string
Description
Type de la tâche Animation. La valeur est animate.
Name
status
Type
string
Description
Statut de la tâche. Valeurs possibles : PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progression de la tâche (0-100).
Name
created_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'epoch) de la création de la tâche.
Un horodatage représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC, conformément à la norme RFC 3339. Par exemple, le vendredi 1er septembre 2023 à 12h00:00 GMT est représenté par 1693569600000. Cela s'applique à tous les horodatages de Meshy API.
Name
started_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'epoch) du début du traitement de la tâche. 0 si elle n'a pas encore commencé.
Name
finished_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'epoch) de la fin de la tâche. 0 si elle n'est pas terminée.
Name
expires_at
Type
timestamp
Description
Horodatage (en millisecondes depuis l'epoch) de l'expiration des assets résultants de la tâche.
Name
task_error
Type
object
Description
Détails de l'erreur pour les tâches échouées. Consultez Erreurs pour la référence complète de l'objet task_error.
Name
consumed_credits
Type
integer
Description
Le nombre de crédits consommés par cette tâche. Présent lorsque le statut de la tâche est PENDING, IN_PROGRESS ou SUCCEEDED. Retourne 0 pour les tâches FAILED (les crédits sont remboursés en cas d'échec).
Name
result
Type
object
Description
Contient les URL des animations générées si la tâche a réussi (SUCCEEDED).
- Name
  animation_glb_url
  Type
  string
  Description
  URL de téléchargement de l'animation au format GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL de téléchargement de l'animation au format FBX.
- Name
  processed_usdz_url
  Type
  string
  Description
  URL de téléchargement de l'animation traitée au format USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL de téléchargement de l'armature traitée au format FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL de téléchargement de l'animation avec un FPS modifié au format FBX (par exemple, si l'opération change_fps a été utilisée).
Name
preceding_tasks
Type
integer
Description
Le nombre de tâches précédentes dans la file d'attente. Pertinent uniquement si le statut est PENDING.

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
}