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 rigado — ya sea una acción predefinida de la biblioteca de animaciones (action_id) 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 con éxito (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 que se aplicará. Consulte la Referencia de la biblioteca de animaciones para obtener una lista completa de las animaciones disponibles. Proporcione exactamente uno de action_id o motion_task_id.
Name
motion_task_id
Type
string
Description
El id de una tarea de Text to Motion completada con éxito para aplicar en lugar de una acción predefinida. El clip generado se retargetiza sobre el personaje rigado y se toma una instantánea del clip en el momento de la creación, por lo que esta tarea no se ve afectada si la tarea de origen caduca o se elimina posteriormente. Los assets de la tarea de origen se conservan durante 3 días — aplique el clip antes de que caduque. Requiere un rig bípedo. Proporcione exactamente uno de action_id 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 de destino. Aplicable solo cuando operation_type es change_fps. Valores permitidos: 24, 25, 30, 60.

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 la 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 proporciona ni action_id ni motion_task_id.
- Parámetros en conflicto: se proporcionaron tanto action_id como motion_task_id — son mutuamente excluyentes.
- Tarea de rig inválida: el rig_task_id no es válido o hace referencia a una tarea fallida/inexistente.
- ID de acción inválido: el action_id no corresponde a una animación válida.
- Tarea de movimiento no lista: la tarea motion_task_id aún no ha llegado a SUCCEEDED.
- Rig no compatible: motion_task_id requiere un rig bípedo; se rechazan los rigs cuadrúpedos.
Name
401 - Unauthorized
Description
Error de autenticación. Compruebe 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 caducado (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 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 que se desea eliminar.

Devuelve

Devuelve 200 OK si tiene éxito.

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

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
}

The Animation Task Object

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

Properties

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 el 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 el epoch) de cuando la tarea comenzó a procesarse. 0 si no ha comenzado.
Name
finished_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde el epoch) de cuando la tarea finalizó. 0 si no ha finalizado.
Name
expires_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde el epoch) de cuando expiran los activos 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 URL de las animaciones de salida si la tarea es SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL descargable de la animación en formato GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL descargable de la animación en formato FBX.
- Name
  processed_usdz_url
  Type
  string
  Description
  URL descargable de la animación procesada en formato USDZ.
- Name
  processed_armature_fbx_url
  Type
  string
  Description
  URL descargable del esqueleto procesado en formato FBX.
- Name
  processed_animation_fps_fbx_url
  Type
  string
  Description
  URL descargable de la animación con los FPS modificados en formato FBX (por ejemplo, si se usó 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
}