API de Animación

Endpoints para descubrir las animaciones disponibles y aplicarlas a personajes con rig.

POST/openapi/v1/animations

Crear una tarea de animación

Este endpoint le permite crear una nueva tarea para aplicar una animación a un personaje previamente riggeado — una acción predefinida de la biblioteca de animaciones (action_id), varias acciones predefinidas combinadas en un solo archivo (action_ids), o un clip de movimiento generado con la API de Text to Motion (motion_task_id). Incluye opciones de posprocesamiento.

Parámetros

Name
rig_task_id
Type
string
Requerido
Description
El id de una tarea de rigging completada exitosamente (de POST /openapi/v1/rigging). El personaje de esta tarea será animado.
Name
action_id
Type
integer
Description
El identificador de la acción de animación predefinida a aplicar. Consulte la Referencia de la biblioteca de animaciones para obtener una lista completa de las animaciones disponibles. Proporcione exactamente uno de action_id, action_ids o motion_task_id.
Name
action_ids
Type
array of integers
Description
Varias acciones de animación predefinidas para aplicar a la vez, devueltas como un único archivo que contiene un clip de animación por acción — útil para controlar un personaje desde una máquina de estados en un motor de juego. Proporcione de 1 a 10 valores de action_id de la Referencia de la biblioteca de animaciones; los ids deben ser únicos. Cuesta 3 créditos por acción. Proporcione exactamente uno de action_id, action_ids o motion_task_id.
Pasar un action_ids con un solo elemento equivale a pasar ese valor como action_id.
Name
motion_task_id
Type
string
Description
El id de una tarea de Text to Motion completada exitosamente para aplicar en lugar de una acción predefinida. El clip generado se retargetiza sobre el personaje riggeado y el clip se captura en el momento de la creación, por lo que esta tarea no se ve afectada si la tarea de origen expira o se elimina posteriormente. Los assets de la tarea de origen se conservan durante 3 días — aplique el clip antes de que expire. Requiere un rig bípedo. Proporcione exactamente uno de action_id, action_ids o motion_task_id.
Name
post_process
Type
object
Description
Posprocesamiento opcional para la salida de la animación. Omítalo para recibir los archivos de animación estándar.

Solo aplica cuando post_process is set

Name
operation_type
Type
string
Requerido
Description
El tipo de operación a realizar. Valores disponibles: change_fps, fbx2usdz, extract_armature.
Name
fps
Type
integer
predeterminado 30
Description
La tasa de fotogramas objetivo. Aplicable solo cuando operation_type es change_fps. Valores permitidos: 24, 25, 30, 60.

Con action_ids, la tarea devuelve un único archivo combinado en lugar de un archivo por acción: animation_glb_url y animation_fbx_url apuntan cada uno a un único asset que contiene cada acción solicitada como un clip independiente.

Orden de los clips: el orden del array action_ids, no el orden numérico de los ids.
Nombres de los clips: el nombre de la animación en la biblioteca, coincidiendo con los nombres que se obtienen al exportar todas las animaciones de un personaje como un único archivo desde la aplicación web de Meshy. Si dos ids solicitados resuelven al mismo nombre de clip, el posterior recibe como sufijo su action_id para mantener los nombres únicos.
Posprocesamiento: se aplica al archivo combinado, no a los clips individuales.

Con motion_task_id, el retargeting puede producir una animación solo en GLB. Si solicitó post_process y no hay FBX disponible, la tarea falla con un task_error y sus créditos se reembolsan automáticamente; sin post_process la tarea se completa correctamente y animation_fbx_url queda vacío.

Devuelve

La propiedad result de la respuesta contiene el id de tarea de la nueva tarea de animación creada.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud fue inaceptable. Causas comunes:
- Falta un parámetro: falta rig_task_id, o no se proporcionó ninguno de action_id, action_ids y motion_task_id.
- Parámetros en conflicto: se proporcionó más de uno de action_id, action_ids y motion_task_id — son mutuamente excluyentes.
- Tarea de rig inválida: rig_task_id es inválido o hace referencia a una tarea fallida/inexistente.
- ID de acción inválido: un action_id — o una entrada de action_ids — no corresponde a una animación válida.
- Demasiadas acciones: action_ids contiene más de 10 ids.
- Acciones duplicadas: action_ids contiene el mismo id más de una vez.
- Tarea de movimiento no lista: la tarea motion_task_id aún no ha alcanzado SUCCEEDED.
- Rig no compatible: motion_task_id requiere un rig bípedo; los rigs cuadrúpedos son rechazados.
Name
401 - Unauthorized
Description
Falló la autenticación. Verifique su clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
404 - Not Found
Description
No se encontró la tarea de rigging especificada por rig_task_id, no se encontró la tarea de movimiento especificada por motion_task_id, o el clip de movimiento ha expirado (los assets de la tarea de origen se conservan durante 3 días).
Name
429 - Too Many Requests
Description
Ha excedido su límite de tasa.

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 several preset actions and get one file with one clip per 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",
    "action_ids": [10, 25, 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

Recuperar una tarea de animación

Este endpoint le permite recuperar una tarea de animación dado un id de tarea válido. Consulte El objeto de tarea de animación para ver qué propiedades se incluyen.

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de animación que se desea recuperar.

Devuelve

La respuesta contiene el objeto de tarea de Animación. Consulte la sección El objeto de tarea de animación para más detalles.

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

Eliminar una tarea de Animación

Este endpoint elimina permanentemente una tarea de animación, incluyendo todos los modelos y datos asociados. Esta acción es irreversible.

Parámetros de ruta

Name
id
Type
path
Description
El ID de la tarea de animación a eliminar.

Estado de la tarea

Una tarea que todavía está en PENDING se elimina y los créditos consumidos en el momento de la creación son reembolsados.

Una tarea que ya está IN_PROGRESS no se puede eliminar: la solicitud es rechazada con 409 Conflict y la tarea sigue ejecutándose. Los créditos de una tarea que el worker ya ha comenzado no son reembolsables, por lo que eliminarla a mitad de ejecución te haría perder tanto los créditos como el resultado. Espera a que llegue a SUCCEEDED, FAILED o CANCELED, y luego elimínala.

Una tarea en un estado terminal (SUCCEEDED, FAILED o CANCELED) se elimina sin reembolso.

Devuelve

Devuelve 200 OK en caso de éxito, o 409 Conflict cuando la tarea está IN_PROGRESS.

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

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left 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."
}

GET/openapi/v1/animations

Listar tareas de Animación

Devuelve una lista paginada de las tareas de Animación del solicitante, empezando por las más recientes. Paginación estándar mediante page_num y page_size.

Tenga en cuenta que las tareas creadas a través de la API se gestionan a través de la API — no aparecen en Mis Assets de la aplicación web. Use este endpoint para encontrar una tarea cuyo ID ya no tenga.

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

Transmitir una tarea de Animación

Este endpoint transmite actualizaciones en tiempo real para una tarea de Animación mediante Server-Sent Events (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de Animación que se va a transmitir.

Devuelve

Devuelve un flujo de The Animation Task Objects como Server-Sent Events.

Para tareas PENDING o IN_PROGRESS, el flujo de respuesta solo incluirá los campos necesarios progress y status.

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
}

El objeto Animation Task

El objeto Animation Task representa la unidad de trabajo para aplicar una animación a un personaje con esqueleto.

Propiedades

Name
id
Type
string
Description
Identificador único de la tarea.
Name
type
Type
string
Description
Tipo de la tarea de Animación. El valor es animate.
Name
status
Type
string
Description
Estado de la tarea. Valores posibles: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progreso de la tarea (0-100).
Name
created_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde epoch) de cuando se creó la tarea.
Una marca de tiempo representa el número de milisegundos transcurridos desde el 1 de enero de 1970 UTC, siguiendo el estándar RFC 3339. Por ejemplo, el viernes 1 de septiembre de 2023 a las 12:00:00 PM GMT se representa como 1693569600000. Esto aplica a todas las marcas de tiempo en Meshy API.
Name
started_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde epoch) de cuando la tarea comenzó a procesarse. 0 si no ha comenzado.
Name
finished_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde epoch) de cuando la tarea finalizó. 0 si no ha finalizado.
Name
expires_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde epoch) de cuando expiran los assets resultantes de la tarea.
Name
task_error
Type
object
Description
Detalles del error para tareas fallidas. Consulta Errores para la referencia completa del objeto task_error.
Name
consumed_credits
Type
integer
Description
El número de créditos consumidos por esta tarea. Presente cuando el estado de la tarea es PENDING, IN_PROGRESS o SUCCEEDED. Devuelve 0 para tareas FAILED (los créditos se reembolsan en caso de fallo).
Name
result
Type
object
Description
Contiene las URLs de animación de salida si la tarea SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL descargable para la animación en formato GLB. Para una tarea creada con action_ids, este archivo único contiene cada acción solicitada como un clip independiente.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL descargable para la animación en formato FBX. Para una tarea creada con action_ids, este archivo único contiene cada acción solicitada como un clip independiente.
- Name
  processed_usdz_url
  Type
  string
  Description
  URL descargable para la animación procesada en formato USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL descargable para el esqueleto procesado en formato FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL descargable para la animación con FPS modificados en formato FBX (por ejemplo, si se utilizó la operación change_fps).
Name
preceding_tasks
Type
integer
Description
El número de tareas precedentes en la cola. Solo tiene sentido si el estado es 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
}

GET/openapi/v1/animations/library

Listar animaciones

Devuelve todas las animaciones de la biblioteca, ordenadas por action_id. La respuesta es una lista completa en lugar de una página, por lo que una sola llamada es suficiente para poblar un selector de acciones. Los filtros acotan el resultado; omítalos todos para obtener todo el contenido.

Para explorar visualmente el mismo catálogo, con una vista previa animada de cada acción, consulte la referencia de la Biblioteca de animaciones.

Este endpoint es gratuito: no consume créditos.

Parámetros

Name
search
Type
string
Description
Coincidencia de subcadena sin distinción entre mayúsculas y minúsculas en name o key. Se compara de forma literal, por lo que % y _ son caracteres normales y no comodines.
Name
category
Type
string
Description
Coincidencia exacta en category.
Valores disponibles:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
Coincidencia exacta en sub_category. Se acepta por sí solo: los nombres de subcategoría no son únicos entre categorías (Transitioning aparece tanto en Fighting como en DailyActions), por lo que sin un category el filtro coincide con esa subcategoría dondequiera que aparezca.
Name
action_ids
Type
string
Description
Lista de valores action_id separados por comas para devolver, útil para resolver ids específicos en lugar de explorar. Acepta como máximo 200 ids. Los ids que ninguna animación posee simplemente están ausentes de la respuesta, por lo que también puede usarlo para verificar si los ids que tiene almacenados siguen disponibles.

Combinación de filtros

Los filtros se aplican en conjunto: cada uno acota más el resultado, por lo que una animación solo se devuelve si satisface todos ellos. Dentro de un mismo filtro, varios valores coinciden con cualquiera de ellos: search coincide con name o key, y action_ids coincide con cualquier id de la lista.

Esto significa que una combinación sin coincidencias devuelve un array vacío en lugar de un error. La acción 92 es "Double Combo Attack", una animación de Fighting:

?action_ids=92&category=Fighting devuelve la acción 92.
?action_ids=92&category=Dancing devuelve []: no es una animación de Dancing.
?action_ids=92&search=walk devuelve []: su nombre no coincide con walk.

Para obtener animaciones específicas independientemente de su categoría, pase action_ids por sí solo.

Devuelve

Devuelve una lista de Los objetos de animación.

Todo action_id devuelto aquí es aceptado por Crear una tarea de animación más arriba, y todo id que esta acepta se devuelve aquí. Las animaciones retiradas están ausentes de ambos. Si almacena en caché la biblioteca, actualícela periódicamente para que un id retirado no permanezca en su selector.

Request

GET

/openapi/v1/animations/library

curl "https://api.meshy.ai/openapi/v1/animations/library?category=Fighting" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "action_id": 4,
    "name": "Attack",
    "key": "Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Attack.gif"
  },
  {
    "action_id": 92,
    "name": "Double Combo Attack",
    "key": "Double_Combo_Attack",
    "category": "Fighting",
    "sub_category": "AttackingwithWeapon",
    "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
  }
]

El objeto Animación

Name
action_id
Type
integer
Description
El valor que se pasa como action_id al crear una tarea de animación. Único y estable, pero no contiguo: las animaciones retiradas dejan huecos en la numeración, por lo que nunca debe suponerse que un rango de ids es válido.
Name
name
Type
string
Description
Etiqueta legible para humanos, para mostrar. No es única: algunas animaciones comparten un nombre con una variante diferente, así que use action_id o key como identidad.
Name
key
Type
string
Description
Slug único y estable para la animación. Úselo cuando necesite un identificador no numérico para indexar su propio almacenamiento.
Name
category
Type
string
Description
Agrupación de nivel superior, por ejemplo, Fighting.
Name
sub_category
Type
string
Description
Agrupación dentro de la categoría, por ejemplo, AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL de un GIF animado que previsualiza la acción, adecuado para renderizar directamente en su propio selector.

Example Animation Object

{
  "action_id": 92,
  "name": "Double Combo Attack",
  "key": "Double_Combo_Attack",
  "category": "Fighting",
  "sub_category": "AttackingwithWeapon",
  "preview_url": "https://cdn.meshy.ai/webapp-assets/feature-demo/animation/preview/biped/Double_Combo_Attack.gif"
}