lowpoly se retira el 30 oct 2026. meshy-7 se retira como modelo de generación 3D el 31 dic 2026; como modelo de texturas sigue disponible. Cambia de modelo antes de estas fechas para evitar errores en las solicitudes. Ver todas las obsolescencias
API de Animación
Aplica animaciones a personajes con rig, y lista las animaciones que puedes aplicar.
También puede posprocesar la salida. La tarea se ejecuta en segundo plano. Para saber cuánto suele tardar una tarea, consulte Tiempos de procesamiento.
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"}
Parámetros
Name
rig_task_id
Type
string
Requerido
Description
El ID de la tarea de Rigging cuyo personaje se animará, obtenido de POST /openapi/v1/rigging. La tarea debe tener el estado SUCCEEDED.
Envíe exactamente uno de action_id, action_ids y motion_task_id.
El rig_type de la animación debe coincidir con el del rig, o la solicitud devuelve 400. Cualquier animación quadruped funciona con cualquier rig cuadrúpedo, sin importar qué animal nombre su category.
Name
action_ids
Type
array of integers
Requerido
Description
Obligatorio a menos que envíe action_id o motion_task_id. Los IDs de entre 1 y 10 animaciones predefinidas para aplicar a la vez, sin repeticiones. Más de 10 IDs, o un ID repetido, devuelve 400. Para ver los IDs, consulte la referencia de la Biblioteca de animaciones.
Meshy devuelve un archivo con un clip de animación por cada acción, lo cual es adecuado para una máquina de estados en un motor de juego. Meshy cobra por cada acción de la lista. Consulte Precios.
Una lista con un solo ID funciona igual que enviar ese ID como action_id.
Una animación cuyo rig_type no coincida con el rig devuelve 400.
Name
motion_task_id
Type
string
Requerido
Description
Obligatorio a menos que envíe action_id o action_ids. El ID de una tarea de Text to Motion cuyo clip se aplicará en lugar de una acción predefinida. La tarea debe tener el estado SUCCEEDED, y el rig debe ser bípedo.
Meshy reorienta (retarget) el clip sobre el personaje rigueado. Copia el clip al crear esta tarea, por lo que esta tarea no se ve afectada si la tarea de Text to Motion posteriormente expira o la elimina. Meshy conserva los archivos de la tarea de Text to Motion durante 3 días, así que aplique el clip antes de ese plazo.
En los archivos GLB y FBX, el clip se llama retarget_clip.
Name
post_process
Type
object
Description
Posprocesamiento para la salida de la animación. Omítalo para obtener los archivos de animación estándar.
Con motion_task_id, el retargeting puede producir una animación disponible solo en GLB. Si envía post_process y no hay un archivo FBX disponible, la tarea falla con un task_error, y Meshy reembolsa sus 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 un archivo FBX
Name
fps
Type
integer
predeterminado 30
Description
La velocidad de fotogramas a la que cambiar, una de 24, 25, 30 o 60. Solo se aplica 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 archivo que contiene todas las acciones solicitadas como clips separados. 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 obtiene 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.
Resultados
El campo result de la respuesta contiene el ID de la nueva tarea de Animación.
Modos de error
Name
400 - Bad Request
Description
La solicitud no se puede ejecutar. El mensaje de error indica qué problema 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íe solo uno.
Tarea de rig invá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ó con éxito.
ID de acción inválido: un action_id, o una entrada en 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 motion_task_id aún no ha alcanzado el estado SUCCEEDED.
Rig no compatible: motion_task_id requiere un rig bípedo, y Meshy rechaza un rig cuadrúpedo.
Discrepancia de tipo de rig: el rig_type de una animación no coincide con el del rig.
Corrija la solicitud y vuelva a enviarla. Consulte Errores.
Name
401 - Unauthorized
Description
La clave de API falta o no es válida. Verifique el encabezado Authorization.
Name
402 - Payment Required
Description
Por ejemplo:
Créditos insuficientes: la cuenta no tiene suficientes créditos para esta tarea, o la cuenta alcanzó un límite de créditos. Revise su saldo de créditos y vuelva a intentarlo.
Plan gratuito: crear una tarea requiere un plan de pago. Actualice su plan en la configuración de suscripción y vuelva a intentarlo.
Name
403 - Forbidden
Description
La tarea 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. Rigue 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 rig_task_id entre sus tareas. Verifique el ID.
Meshy eliminó los archivos de la tarea rig_task_id después de su expires_at. Riguee el personaje nuevamente.
Meshy no puede encontrar la tarea motion_task_id. Verifique el ID.
El clip de movimiento expiró, porque Meshy conserva los archivos de una tarea de Text to Motion durante 3 días. Cree otra tarea de Text to Motion.
Name
429 - Too Many Requests
Description
Superó su límite de tasa. Espere y vuelva a intentarlo. Consulte Límites de tasa.
// 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.
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.
// 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": null,"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?..." }}
Parámetros
Name
id
Type
path
Description
El ID de la tarea proveniente de la respuesta de creación.
Cada evento contiene el objeto de tarea completo, con la misma estructura que devuelve el endpoint Get. Mientras la tarea esté en estado PENDING o IN_PROGRESS, sus campos de resultado aún no tienen valores.
Un objeto de tarea Animación describe una animación aplicada a un personaje con esqueleto. Contiene el estado, el progress y los archivos de animación cuando la tarea tiene éxito.
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 de 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 comenzó la tarea, en milisegundos Unix. Es 0 hasta que la tarea comienza.
Name
finished_at
Type
timestamp
Description
Momento en que finalizó la tarea, 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. Es null a menos que el estado sea FAILED. 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 único archivo 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 único archivo 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 frecuencia de fotogramas modificada, como archivo FBX, por ejemplo cuando 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 es significativo mientras la tarea está en estado PENDING. El campo se omite cuando el valor es 0.
Devuelve todas las animaciones de la biblioteca, ordenadas por action_id. La respuesta es la lista completa, sin paginación, por lo que una sola llamada puede llenar un selector de acciones. Los filtros reducen el resultado. Para obtener todas las animaciones, omítelos todos.
Texto a buscar. Meshy devuelve las animaciones cuyo name o key contiene este texto, sin distinguir mayúsculas y minúsculas. Meshy busca coincidencias literales del texto, así 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.
Las categorías de animaciones biped:
WalkAndRun
BodyMovements
DailyActions
Fighting
Dancing
La categoría de una animación quadruped es un animal, por ejemplo dog o horse.
Name
sub_category
Type
string
Description
La subcategoría a listar, como coincidencia exacta. Puedes 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 action_id separados por comas. Úsalo para buscar IDs específicos en lugar de explorar. Más de 200 IDs devuelve 400.
La respuesta omite un ID que ninguna animación tiene. Así que también puedes usar este filtro para comprobar si los IDs que almacenaste siguen disponibles.
Combinando filtros
Meshy aplica los filtros en conjunto. Cada uno reduce el resultado, por lo que Meshy devuelve una animación solo 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 superposición 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 en cualquier categoría, envía action_ids por sí solo.
Crear una tarea de Animación acepta todos los action_id que devuelve este endpoint, y este endpoint devuelve todos los ID que acepta la creación. Ninguno incluye animaciones retiradas. Si almacenas en caché la biblioteca, actualízala de vez en cuando, para que un ID retirado no permanezca en tu selector.
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 de un rango son válidos.
Name
name
Type
string
Description
El nombre para mostrar de la animación. No es único, ya que 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 para indexar tu propio almacenamiento.
Name
category
Type
string
Description
El grupo de nivel superior, por ejemplo Fighting. Para una animación quadruped, es un animal, por ejemplo dog o horse.
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 GIF animada de la acción. Puedes mostrarla directamente en tu propio selector.
Name
rig_type
Type
string
Description
El tipo de rig en el que se reproduce la animación, biped o quadruped. Coincide con el animation_type de la tarea de Rigging. Un rig solo admite animaciones de su propio tipo.