API de Texto a Movimiento

Genera clips de movimiento de personajes a partir de descripciones de texto. Describe una acción, como "un personaje saludando" o "un zombi avanzando arrastrando los pies", y obtén un clip de movimiento sin procesar. Puedes reorientar el clip hacia personajes con rig en tu propio pipeline o herramientas DCC.

La salida es un clip de movimiento independiente. No necesita un modelo de personaje, ni está vinculado a uno. Para hacer primero el rigging de un personaje, consulta la API de Rigging. Para aplicar un clip a tu personaje con rig, envía el id de la tarea como motion_task_id a la API de Animación.

POST/openapi/v1/text-to-motion

Crear una tarea de Texto a Movimiento

Crea una tarea de Texto a Movimiento, que genera un clip de movimiento a partir de un prompt de texto.

La tarea se ejecuta en segundo plano. Para saber cuánto suele tardar una tarea, consulta Tiempos de procesamiento.

Una tarea prime cuesta 10 créditos y usa el modelo de movimiento de mayor calidad de Meshy. Una tarea swift cuesta 3 créditos y usa un modelo de movimiento más rápido y económico.

Request

POST

/openapi/v1/text-to-motion

# Generate a motion clip with required params only
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "duration": 3
  }'

# Generate a fast, economical clip with Swift mode
curl https://api.meshy.ai/openapi/v1/text-to-motion \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "a character waving",
    "mode": "swift",
    "duration": 4.5
  }'

Response

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

Parámetros

Name
prompt
Type
string
Requerido
Description
Texto que describe el movimiento a generar, hasta 400 caracteres. Un texto más largo devuelve 400.
Name
mode
Type
string
predeterminado prime
Description
El modelo de movimiento, que también determina el formato de archivo del clip.
Valores disponibles:
- prime: mayor calidad, devuelve un clip FBX
- swift: más rápido y económico, devuelve un clip BVH
Cualquier otro valor devuelve 400.
Name
duration
Type
number
Requerido
Description
La duración objetivo del clip en segundos, de 2 a 10 en incrementos de 0.5, por ejemplo 2, 2.5 o 3. Cualquier otro valor devuelve 400.

Devuelve

El campo result de la respuesta contiene el ID de la nueva tarea de Texto a Movimiento.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud no puede ejecutarse. El mensaje de error indica qué problema se encontró. Por ejemplo:
- Prompt ausente o vacío: prompt falta, está vacío o supera los 400 caracteres.
- Mode inválido: mode no es prime ni swift.
- Duración inválida: duration falta, está fuera del rango de 2 a 10, o no está en un incremento de 0.5 segundos.
Corrige la solicitud y envíala de nuevo. Consulta Errores.
Name
401 - Unauthorized
Description
La clave de API falta o no es válida. Revisa 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. 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 suscripción y vuelve a intentarlo.
Name
403 - Forbidden
Description
La moderation de contenido marcó el prompt. Cambia el prompt y envía la solicitud de nuevo.
Name
429 - Too Many Requests
Description
Excediste tu límite de tasa. Espera y vuelve a intentarlo. Consulta Límites de tasa.

GET/openapi/v1/text-to-motion/:id

Obtener una tarea de Text to Motion

Devuelve una tarea de Text to Motion por su ID.

Request

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

curl https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/0630d47c-84b8-4d37-bc02-69e45d9272c1/tasks/018c425b-b2c6-727e-d333-3c1887i9h791/output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

Parámetros

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

Devuelve

El objeto de tarea Text to Motion.

GET/openapi/v1/text-to-motion

Listar tareas de Text to Motion

Devuelve una lista paginada de tus tareas de Text to Motion, empezando por las más recientes. Para recorrer la lista, usa page_num y page_size.

La respuesta es un array de objetos de tarea de Text to Motion.

Las tareas que creas con la API permanecen en la API y no aparecen en My Assets en la aplicación web. Para encontrar una tarea cuyo ID ya no tengas, usa este endpoint.

Request

GET

/openapi/v1/text-to-motion

curl "https://api.meshy.ai/openapi/v1/text-to-motion?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]

GET/openapi/v1/text-to-motion/:id/stream

Transmitir en streaming una tarea de Text to Motion

Transmite las actualizaciones de una tarea de Text to Motion como eventos enviados por el servidor (SSE).

Request

GET

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791/stream

curl -N https://api.meshy.ai/openapi/v1/text-to-motion/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 events carry the full task object at every stage; the result
// fields stay empty until the task succeeds.
event: message
data: {
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "IN_PROGRESS",
  "progress": 50,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 0,
  "expires_at": 0,
  "task_error": null,
  "result": {
    "motion_url": "",
    "motion_format": "",
    "duration_ms": 0,
    "mode": ""
  },
  "consumed_credits": 10
}

event: message
data: { // Example of a SUCCEEDED task event, with the same fields as the Text to Motion task object
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

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 Text to Motion como eventos enviados por el servidor.

Cada evento message transporta el objeto de tarea completo. Mientras la tarea esté en PENDING o IN_PROGRESS, los campos de result están vacíos ("" o 0), y finished_at y expires_at son 0. Para seguir el progreso de la tarea, observa status y progress.

DELETE/openapi/v1/text-to-motion/:id

Eliminar una tarea de Text to Motion

Elimina permanentemente una tarea de Text to Motion, incluido su clip de movimiento. No puedes deshacer una eliminación.

Request

DELETE

/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/text-to-motion/018c425b-b2c6-727e-d333-3c1887i9h791 \
  -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 que se va a eliminar.

Estado de la tarea

Eliminar una tarea PENDING reembolsa los créditos que usó al crearla.

No se puede eliminar una tarea IN_PROGRESS. La solicitud devuelve 409 Conflict, y la tarea sigue ejecutándose. Meshy no reembolsa una tarea que ya ha comenzado, por lo 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 se elimina la tarea, o 409 Conflict cuando la tarea está IN_PROGRESS.

El objeto de tarea Text to Motion

Un objeto de tarea Text to Motion describe la generación de un clip de movimiento. Contiene el estado, el progreso y el clip cuando la tarea se completa correctamente.

Propiedades

Example Text to Motion Task Object

{
  "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
  "type": "text-to-motion",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1787314497437,
  "started_at": 1787314498012,
  "finished_at": 1787314505881,
  "expires_at": 1787573705881,
  "task_error": null,
  "result": {
    "motion_url": "https://assets.meshy.ai/.../output/clip.fbx?Expires=...",
    "motion_format": "fbx",
    "duration_ms": 3000,
    "mode": "prime"
  },
  "consumed_credits": 10
}

Name
id
Type
string
Description
El ID de la tarea. Trátalo como una cadena opaca y no dependas de su formato.
Name
type
Type
string
Description
El tipo de tarea, siempre text-to-motion.
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 de la tarea se ha completado, como un porcentaje de 0 a 100.
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. Es 0 hasta que la tarea finaliza. Meshy conserva el clip durante 3 días después de que la tarea finaliza, así que descárgalo antes de ese plazo.
Name
preceding_tasks
Type
integer
Description
El número de tareas que preceden a esta en la cola. El valor solo tiene sentido mientras la tarea está en estado PENDING. El campo se omite cuando el valor es 0.
Name
consumed_credits
Type
integer
Description
El número de créditos que consumió la tarea, 10 para el mode prime o 3 para el mode swift. Es 0 para una tarea FAILED, porque Meshy reembolsa los créditos cuando una tarea falla.
Name
task_error
Type
object
Description
Los detalles del error cuando la tarea falla, y null en caso contrario. Consulta Errores.
Name
result
Type
object
Description
El clip de movimiento generado cuando la tarea se completa correctamente. Hasta entonces, los campos están presentes pero vacíos ("" o 0).
- Name
  motion_url
  Type
  string
  Description
  URL de descarga del clip de movimiento. Meshy firma la URL de nuevo en cada lectura, y expira con la ventana de retención de la tarea.
- Name
  motion_format
  Type
  string
  Description
  El formato de archivo del clip, fbx para el mode prime o bvh para el mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  La duración del clip, en milisegundos.
- Name
  mode
  Type
  string
  Description
  El mode que Meshy usó para generar el clip, prime o swift.