API de Animación

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

POST/openapi/v1/animations

Crear una tarea de Animación

Este endpoint te permite crear una nueva tarea para aplicar una acción de animación específica a un personaje previamente preparado con rigging. Incluye opciones de posprocesamiento.

Parámetros

Name
rig_task_id
Type
string
Requerido
Description
El id de una tarea de rigging completada correctamente (desde POST /openapi/v1/rigging). El personaje de esta tarea será animado.
Name
action_id
Type
integer
Requerido
Description
El identificador de la acción de animación que se aplicará. Consulta la Referencia de la Biblioteca de animaciones para ver una lista completa de las animaciones disponibles.
Name
post_process
Type
object
Description
Posprocesamiento opcional para la salida de la animación. Omítelo 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 que se 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.

Devuelve

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

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no era aceptable. Causas comunes:
- Parámetro faltante: falta rig_task_id o action_id.
- Tarea de rigging no válida: el rig_task_id no es válido o hace referencia a una tarea fallida/inexistente.
- ID de acción no válido: el action_id no corresponde a una animación válida.
Name
401 - Unauthorized
Description
La autenticación falló. Comprueba tu 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.
Name
429 - Too Many Requests
Description
Has superado tu 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
  }'

# 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 te permite recuperar una tarea de Animación dado un id de tarea válido. Consulta 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 va a recuperar.

Devuelve

La respuesta contiene el objeto de tarea de Animación. Consulta la sección El objeto de tarea de Animación para obtener 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, incluidos 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 va a eliminar.

Devuelve

Devuelve 200 OK si se completa correctamente.

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/: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 Los objetos de tarea de Animación 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 de tarea de Animación

El objeto de tarea de Animación representa la unidad de trabajo para aplicar una animación a un personaje con rig.

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
progress de la tarea (0-100).
Name
created_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época) en que 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, viernes, 1 de septiembre de 2023 12:00:00 PM GMT se representa como 1693569600000. Esto se aplica a todas las marcas de tiempo en Meshy API.
Name
started_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época) en que la tarea comenzó a procesarse. 0 si no ha comenzado.
Name
finished_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época) en que la tarea finalizó. 0 si no ha finalizado.
Name
expires_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde la época) en que expiran los assets de resultado 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. Está 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 animación de salida si la tarea SUCCEEDED.
- Name
  animation_glb_url
  Type
  string
  Description
  URL descargable para la animación en formato GLB.
- Name
  animation_fbx_url
  Type
  string
  Description
  URL descargable para la animación en formato FBX.
- 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 cambiado en formato FBX (p. ej., si se utilizó la operación change_fps).
Name
preceding_tasks
Type
integer
Description
El recuento de tareas anteriores en la cola. Solo es significativo 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
}