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.


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 ha rigueado previamente. La animación puede ser una de las siguientes:

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

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

  • Name
    action_id
    Type
    integer
    Requerido
    Description

    Obligatorio a menos que envíe action_ids o motion_task_id. El ID de la animación predefinida que se aplicará. Para ver la lista completa de animaciones, consulte la referencia de la Biblioteca de animaciones o Listar animaciones.

    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.

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.


GET/openapi/v1/animations/:id

Obtener una tarea de Animación

Devuelve una tarea de Animación según 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": null,
  "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=..."
  }
}

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 un flujo de una tarea de Animación

Transmite las actualizaciones de una tarea de Animación como eventos enviados por el servidor (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": 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.

Devuelve

Un flujo de objetos de tarea de Animación como eventos enviados por el servidor.

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.


El objeto de tarea Animación

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.

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": 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?..."
  }
}
  • 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 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.


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, 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.

Para explorar la misma lista con una vista previa animada de cada acción, consulta 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",
    "rig_type": "biped"
  },
  {
    "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",
    "rig_type": "biped"
  }
]

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

Devuelve

Una lista de objetos de animación.


El objeto de animación

Un objeto de animación describe una animación de 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",
  "rig_type": "biped"
}
  • 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 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.