API de Animación

Aplica animaciones a personajes con rig, y lista las animaciones que puedes aplicar.

POST/openapi/v1/animations

Crear una tarea de Animación

Crea una tarea de Animación, que aplica una animación a un personaje que ya tiene rigging. La animación puede ser una de las siguientes:

Una acción preestablecida de la biblioteca de animaciones (action_id)
Varias acciones preestablecidas combinadas en un solo archivo (action_ids)
Un clip de movimiento que generaste con la API de Text to Motion (motion_task_id)

También puedes posprocesar la salida. La tarea se ejecuta en segundo plano. Para saber cuánto suele tardar una tarea, consulta Tiempos de procesamiento.

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"
}

Parámetros

Name
rig_task_id
Type
string
Requerido
Description
El ID de la tarea de Rigging cuyo personaje se va a animar, obtenido de POST /openapi/v1/rigging. La tarea debe tener el estado SUCCEEDED.

Envía exactamente uno de action_id, action_ids y motion_task_id.

Name
action_id
Type
integer
Requerido
Description
Obligatorio a menos que envíes action_ids o motion_task_id. El ID de la animación preestablecida que se aplicará. Para ver la lista completa de animaciones, consulta la referencia de la Biblioteca de animaciones o Listar animaciones.

Name
action_ids
Type
array of integers
Requerido
Description
Obligatorio a menos que envíes action_id o motion_task_id. Los IDs de entre 1 y 10 animaciones preestablecidas que se aplicarán a la vez, sin repeticiones. Más de 10 IDs, o un ID repetido, devuelve 400. Para ver los IDs, consulta la referencia de la Biblioteca de animaciones.
Meshy devuelve un archivo con un clip de animación por acción, lo que resulta adecuado para una máquina de estados en un motor de juego. Meshy cobra por cada acción de la lista. Consulta Precios.
Una lista con un solo ID funciona igual que enviar ese ID como action_id.

Name
motion_task_id
Type
string
Requerido
Description
Obligatorio a menos que envíes action_id o action_ids. El ID de una tarea de Text to Motion cuyo clip se aplicará en lugar de una acción preestablecida. La tarea debe tener el estado SUCCEEDED, y el rig debe ser bípedo.
Meshy reorienta el clip sobre el personaje con rigging. Copia el clip al crear esta tarea, por lo que esta tarea no se ve afectada si la tarea de Text to Motion caduca más tarde o la eliminas. Meshy conserva los archivos de la tarea de Text to Motion durante 3 días, así que aplica el clip antes de que pase ese tiempo.

Name
post_process
Type
object
Description
Posprocesamiento para la salida de la animación. Omítelo para obtener los archivos de animación estándar.
Con motion_task_id, el reorientado puede producir una animación solo en GLB. Si envías post_process y no hay ningún archivo FBX disponible, la tarea falla con un task_error, y Meshy reembolsa tus créditos. Sin post_process, la tarea se completa correctamente, y animation_fbx_url queda vacío.

Solo aplica cuando post_process is set

Name
operation_type
Type
string
Description
La operación que se ejecutará. Sin ella, Meshy no genera ningún archivo adicional. Un valor que no esté en la siguiente lista devuelve 400.
Valores disponibles:
- change_fps: cambia la velocidad de fotogramas a fps
- fbx2usdz: convierte la animación a USDZ
- extract_armature: extrae el esqueleto como archivo FBX
Name
fps
Type
integer
predeterminado 30
Description
La velocidad de fotogramas a la que cambiar, uno de 24, 25, 30 o 60. Se aplica solo cuando operation_type es change_fps. Cualquier otro valor devuelve 400.

Con action_ids, la tarea devuelve un archivo combinado en lugar de un archivo por acción. animation_glb_url y animation_fbx_url apuntan cada uno a un único archivo que contiene todas las acciones solicitadas como clips independientes. En ese archivo:

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. Coinciden con los nombres que obtienes al exportar todas las animaciones de un personaje como un solo archivo desde la aplicación web de Meshy. Si dos IDs solicitados tienen el mismo nombre de clip, Meshy añade el action_id al más reciente para mantener los nombres únicos.
Posprocesamiento: Meshy lo aplica al archivo combinado, no a cada clip por separado.

Devuelve

El campo result de la respuesta contiene el ID de la nueva tarea de Animación.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no se puede ejecutar. El mensaje de error indica qué problema se encontró. Por ejemplo:
- Parámetro faltante: falta rig_task_id, o no se envió ninguno de action_id, action_ids y motion_task_id.
- Parámetros en conflicto: la solicitud tiene más de uno de action_id, action_ids y motion_task_id. Envía solo uno.
- Tarea de rig no válida: rig_task_id no es un ID de tarea válido, no es una tarea de Rigging, o apunta a una tarea que no se completó correctamente.
- ID de acción no válido: un action_id, o una entrada de action_ids, no es una animación válida.
- Demasiadas acciones: action_ids tiene más de 10 IDs.
- Acciones duplicadas: action_ids tiene el mismo ID más de una vez.
- Tarea de movimiento no lista: la tarea de motion_task_id aún no ha llegado a SUCCEEDED.
- Rig no compatible: motion_task_id necesita un rig bípedo, y Meshy rechaza un rig cuadrúpedo.
Corrige la solicitud y vuelve a enviarla. Consulta Errores.
Name
401 - Unauthorized
Description
Falta la clave de API o no es válida. Revisa el encabezado Authorization.
Name
402 - Payment Required
Description
Por ejemplo:
- Créditos insuficientes: la cuenta no tiene créditos suficientes para esta tarea, o la cuenta alcanzó un límite de créditos. Revisa tu saldo de créditos y vuelve a intentarlo.
- Plan gratuito: crear una tarea requiere un plan de pago. Mejora tu plan en la configuración de tu suscripción y vuelve a intentarlo.
Name
403 - Forbidden
Description
La tarea de rig_task_id es un modelo de bajorrelieve, que este endpoint no puede animar. El mensaje es This model type does not support this operation. Haz rigging a un modelo diferente.
Name
404 - Not Found
Description
Meshy no puede encontrar una tarea o archivo que la solicitud necesita. Se aplica uno de los siguientes casos:
- Meshy no puede encontrar la tarea de rig_task_id entre tus tareas. Revisa el ID.
- Meshy eliminó los archivos de la tarea de rig_task_id después de su expires_at. Vuelve a hacer rigging del personaje.
- Meshy no puede encontrar la tarea de motion_task_id. Revisa el ID.
- El clip de movimiento caducó, porque Meshy conserva los archivos de una tarea de Text to Motion durante 3 días. Crea otra tarea de Text to Motion.
Name
429 - Too Many Requests
Description
Superaste tu límite de tasa. Espera y vuelve a intentarlo. Consulta Límites de tasa.

GET/openapi/v1/animations/:id

Obtener una tarea de Animación

Devuelve una tarea de Animación por su ID.

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
}

Parámetros

Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.

Devuelve

El objeto de tarea de Animación.

DELETE/openapi/v1/animations/:id

Eliminar una tarea de Animación

Elimina permanentemente una tarea de Animación, incluidos sus modelos y datos. No puedes deshacer una eliminación.

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 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."
}

Parámetros de ruta

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

Estado de la tarea

Eliminar una tarea PENDING reembolsa los créditos que usó cuando la creaste.

Una tarea IN_PROGRESS no se puede eliminar. La solicitud devuelve 409 Conflict, y la tarea sigue ejecutándose. Meshy no reembolsa una tarea que ya ha comenzado, así que eliminarla te costaría tanto los créditos como el resultado. Espera a que llegue a SUCCEEDED, FAILED o CANCELED, y luego elimínala.

Eliminar una tarea en un estado final (SUCCEEDED, FAILED o CANCELED) no reembolsa sus créditos.

Devuelve

200 OK cuando la tarea se elimina, o 409 Conflict cuando la tarea está IN_PROGRESS.

GET/openapi/v1/animations

Listar tareas de Animación

Devuelve una lista paginada de tus tareas de Animación, empezando por las más recientes. Para recorrer la lista, usa page_num y page_size.

Las tareas que creas a través de la API no aparecen en My Assets en la aplicación web, por lo que debes gestionarlas a través de la API. Para encontrar una tarea cuyo ID ya no tengas, usa este endpoint.

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 como stream

Transmite las actualizaciones de una tarea de Animación como Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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, 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
}

Parámetros

Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.

Devuelve

Un stream de objetos de tarea de Animación como Server-Sent Events.

Cada evento contiene el objeto de tarea completo, con la misma estructura que devuelve el endpoint Get. Mientras la tarea esté en PENDING o IN_PROGRESS, sus campos de resultado aún no tienen valores.

El objeto de tarea de Animación

Un objeto de tarea de Animación describe una animación aplicada a un personaje con rig. Contiene el estado, el progress y los archivos de animación cuando la tarea tiene éxito.

Propiedades

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
}

Name
id
Type
string
Description
El ID de la tarea. Trátelo como una cadena opaca y no dependa de su formato.
Name
type
Type
string
Description
El tipo de tarea, siempre animate.
Name
status
Type
string
Description
El estado de la tarea, uno de PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
progress
Type
integer
Description
Cuánto se ha completado la tarea, como porcentaje. Es 0 hasta que la tarea comienza y 100 cuando tiene éxito.
Name
created_at
Type
timestamp
Description
Momento en que se creó la tarea, en milisegundos Unix.
Name
started_at
Type
timestamp
Description
Momento en que la tarea comenzó, en milisegundos Unix. Es 0 hasta que la tarea comienza.
Name
finished_at
Type
timestamp
Description
Momento en que la tarea finalizó, en milisegundos Unix. Es 0 hasta que la tarea finaliza.
Name
expires_at
Type
timestamp
Description
Momento en que expiran los archivos de resultado de la tarea, en milisegundos Unix.
Name
task_error
Type
object
Description
Los detalles del error cuando la tarea falla. Consulte Errores.
Name
consumed_credits
Type
integer
Description
El número de créditos que usó la tarea. Presente cuando el estado es PENDING, IN_PROGRESS o SUCCEEDED. Es 0 para una tarea FAILED, porque Meshy reembolsa los créditos cuando una tarea falla.
Name
result
Type
object
Description
URLs de descarga para los archivos de animación, cuando la tarea tiene el estado SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  La animación como archivo 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
  La animación como archivo 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
  La animación procesada como archivo USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  El esqueleto procesado como archivo FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  La animación con la tasa de fotogramas modificada, como archivo FBX, por ejemplo cuando se usó la operación change_fps.
Name
preceding_tasks
Type
integer
Description
El número de tareas por delante de esta en la cola. El valor solo tiene sentido mientras la tarea está PENDING.

GET/openapi/v1/animations/library

Listar animaciones

Devuelve todas las animaciones de la biblioteca, ordenadas por action_id. La respuesta es la lista completa, sin paginación, de modo que una sola llamada puede llenar un selector de acciones. Los filtros reducen el resultado. Para obtener todas las animaciones, omítalos todos.

Para explorar la misma lista con una vista previa animada de cada acción, consulte la referencia de la Biblioteca de animaciones.

Esta solicitud no cuesta créditos.

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"
  }
]

Parámetros

Name
search
Type
string
Description
Texto a buscar. Meshy devuelve las animaciones cuyo name o key contiene este texto, sin distinguir mayúsculas de minúsculas. Meshy compara el texto de forma literal, por lo que % y _ no son comodines.
Name
category
Type
string
Description
La categoría a listar, como coincidencia exacta. Una categoría desconocida devuelve una lista vacía.
Valores disponibles:
- WalkAndRun
- BodyMovements
- DailyActions
- Fighting
- Dancing
Name
sub_category
Type
string
Description
La subcategoría a listar, como coincidencia exacta. Puede enviarla sin category. Los nombres de subcategoría no son únicos entre categorías. Por ejemplo, Transitioning está tanto en Fighting como en DailyActions. Así que, sin category, el filtro coincide con la subcategoría en todas las categorías.
Name
action_ids
Type
string
Description
Las animaciones a devolver, como hasta 200 valores de action_id separados por comas. Úselo para buscar IDs específicos en lugar de explorar. Más de 200 IDs devuelve 400.
La respuesta omite cualquier ID que no corresponda a ninguna animación. Por lo que también puede usar este filtro para comprobar si los IDs que ha almacenado siguen disponibles.

Combinación de filtros

Meshy aplica los filtros en conjunto. Cada uno reduce el resultado, de modo que Meshy solo devuelve una animación si coincide con todos ellos. Dentro de un mismo filtro, cualquiera de sus valores puede coincidir. Por ejemplo, search coincide con name o key, y action_ids coincide con cualquier ID de la lista.

Así que una combinación sin coincidencias devuelve un array vacío, no un error. La acción 92 es "Double Combo Attack", una animación de Fighting. Por ejemplo:

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

Para obtener animaciones específicas de cualquier categoría, envíe action_ids por sí solo.

Devuelve

Una lista de objetos de animación.

Crear una tarea de Animación acepta todos los action_id que devuelve este endpoint, y este endpoint devuelve todos los IDs que acepta la creación. Ninguno incluye animaciones retiradas. Si almacena en caché la biblioteca, actualícela de vez en cuando, para que un ID retirado no permanezca en su selector.

The animation object

Un objeto de animación describe una animación en la biblioteca.

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"
}

Name
action_id
Type
integer
Description
El valor que se envía como action_id al crear una tarea de Animación. Es único y estable, pero no contiguo. Las animaciones retiradas dejan huecos en la numeración, así que no asumas que todos los ID dentro de un rango son válidos.
Name
name
Type
string
Description
El nombre para mostrar de la animación. No es único, porque algunas animaciones comparten nombre con otra variante. Para identificar una animación, usa action_id o key.
Name
key
Type
string
Description
Un slug único y estable para la animación. Úsalo cuando necesites un ID no numérico con el que indexar tu propio almacenamiento.
Name
category
Type
string
Description
El grupo de nivel superior, por ejemplo Fighting.
Name
sub_category
Type
string
Description
El grupo dentro de la categoría, por ejemplo AttackingwithWeapon.
Name
preview_url
Type
string
Description
URL de una vista previa en GIF animado de la acción. Puedes mostrarla directamente en tu propio selector.