API Animation

Points de terminaison pour découvrir les animations disponibles et 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 afin d’appliquer une action d’animation spécifique à un personnage préalablement riggé. Inclut des options de post-traitement.

Paramètres

Name
rig_task_id
Type
string
Requis
Description
Le id d’une tâche de rigging terminée avec succès (depuis POST /openapi/v1/rigging). Le personnage issu de cette tâche sera animé.
Name
action_id
Type
integer
Requis
Description
L’identifiant de l’action d’animation à appliquer. Consultez la référence de la Bibliothèque d'animations pour obtenir la liste complète des animations disponibles.
Name
post_process
Type
object
Description
Post-traitement facultatif 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.

Retours

La propriété result de la réponse contient le id de 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 ou action_id est manquant.
- Tâche de rigging non valide : Le rig_task_id est non valide ou fait référence à une tâche échouée/inexistante.
- ID d’action non valide : Le action_id ne correspond pas à une animation valide.
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.
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
  }'

# 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 quelles propriétés sont incluses.

Paramètres

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

Renvoie

La réponse contient l’objet Tâche d’Animation. 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/:id/stream

Diffuser une tâche Animation

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

Paramètres

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

Retours

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

Pour les tâches PENDING ou IN_PROGRESS, le flux de réponse inclura uniquement 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
}

L’objet de tâche Animation

L’objet de tâche Animation représente l’unité de travail permettant d’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
Progress de la tâche (0-100).
Name
created_at
Type
timestamp
Description
Horodatage (millisecondes depuis l’époque Unix) auquel la tâche a été créée.
Un horodatage représente le nombre de millisecondes écoulées depuis le 1er janvier 1970 UTC, selon la norme RFC 3339. Par exemple, le vendredi 1er septembre 2023 à 12:00:00 PM GMT est représenté par 1693569600000. Cela s’applique à tous les horodatages dans Meshy API.
Name
started_at
Type
timestamp
Description
Horodatage (millisecondes depuis l’époque Unix) auquel la tâche a commencé le traitement. 0 si elle n’a pas commencé.
Name
finished_at
Type
timestamp
Description
Horodatage (millisecondes depuis l’époque Unix) auquel la tâche s’est terminée. 0 si elle n’est pas terminée.
Name
expires_at
Type
timestamp
Description
Horodatage (millisecondes depuis l’époque Unix) auquel les assets de résultat de la tâche expirent.
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. Renvoie 0 pour les tâches FAILED (les crédits sont remboursés en cas d’échec).
Name
result
Type
object
Description
Contient les URL d’animation de sortie si la tâche a SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL téléchargeable pour l’animation au format GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL téléchargeable pour l’animation au format FBX.
- Name
  processed_usdz_url
  Type
  string
  Description
  URL téléchargeable pour l’animation traitée au format USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL téléchargeable pour l’armature traitée au format FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL téléchargeable pour l’animation avec FPS modifié au format FBX (par ex., 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. Significatif 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
}