API de Texto a Movimiento

Genera clips de movimiento de personajes a partir de descripciones en lenguaje natural. Describe una acción — "un personaje saludando", "un zombi avanzando arrastrando los pies" — y recibe un clip de movimiento en bruto que puedes reorientar sobre personajes con rig (骨骼绑定) en tu propio pipeline o herramientas DCC.

La salida es un clip de movimiento independiente: no requiere 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 generado sobre tu personaje con rig, pasa el id de la tarea como motion_task_id a la API de Animación — aplícalo dentro de la ventana de retención de recursos de 3 días.

POST/openapi/v1/text-to-motion

Crear una tarea de Text to Motion

Este endpoint crea una nueva tarea para generar un clip de movimiento a partir de un prompt de texto.

Una tarea con mode prime cuesta 10 créditos y genera con nuestro modelo de movimiento de mayor calidad. Una tarea con mode swift cuesta 3 créditos y genera más rápido con nuestro modelo de movimiento económico.

Parámetros

Name
prompt
Type
string
Requerido
Description
Una descripción en lenguaje natural del movimiento a generar. Máximo 400 caracteres.
Name
mode
Type
string
predeterminado prime
Description
El mode de generación de movimiento. Valores disponibles: prime, swift. prime produce la mayor calidad y genera FBX; swift es más rápido y económico y genera BVH.
Name
duration
Type
number
Requerido
Description
La duración objetivo del clip de movimiento en segundos. Entre 2 y 10, en pasos de 0.5 (por ejemplo 2, 2.5, 3, … 10).

Devuelve

La propiedad result de la respuesta contiene el id de la tarea de la tarea de Text to Motion recién creada.

Modos de fallo

Name
400 - Bad Request
Description
La solicitud fue inaceptable. Causas comunes:
- Prompt ausente o vacío: prompt falta, está en blanco o supera los 400 caracteres.
- Mode inválido: mode no es prime ni swift.
- Duración inválida: duration falta, está fuera del rango 2–10, o no está en un paso de 0.5 segundos.
Name
401 - Unauthorized
Description
Falló la autenticación. Por favor, verifica tu clave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarea.
Name
403 - Forbidden
Description
El prompt fue marcado por moderation de contenido.
Name
429 - Too Many Requests
Description
Has excedido tu límite de tasa.

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"
}

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

Recuperar una tarea de Texto a Movimiento

Este endpoint le permite recuperar una tarea de Texto a Movimiento dado un id de tarea válido. Consulte El objeto de tarea de Texto a Movimiento para ver qué propiedades se incluyen.

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de Texto a Movimiento que se desea recuperar.

Devuelve

La respuesta contiene el objeto de tarea de Texto a Movimiento. Consulte la sección El objeto de tarea de Texto a Movimiento para más detalles.

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
}

GET/openapi/v1/text-to-motion

Listar tareas de Text to Motion

Devuelve una lista paginada de las tareas de Text to Motion del solicitante, comenzando por las más recientes. Paginación estándar mediante page_num y page_size.

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

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

Este endpoint transmite actualizaciones en tiempo real de una tarea de Text to Motion mediante Server-Sent Events (SSE).

Parámetros

Name
id
Type
path
Description
Identificador único de la tarea de Text to Motion que se desea transmitir.

Devuelve

Devuelve un flujo de objetos de tarea de Text to Motion como Server-Sent Events.

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

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 stream item, mirroring The Text to Motion Task Object structure
  "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
}

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

Eliminar una tarea de Text to Motion

Este endpoint elimina permanentemente una tarea de Text to Motion, incluido el clip de movimiento generado. Esta acción es irreversible.

Parámetros de ruta

Name
id
Type
path
Description
El ID de la tarea de Text to Motion que se va a eliminar.

Devuelve

Devuelve 200 OK si tiene éxito.

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

// Returns 200 Ok on success.

El objeto Text to Motion Task

El objeto Text to Motion Task representa la unidad de trabajo para generar un clip de movimiento a partir de un prompt de texto.

Propiedades

Name
id
Type
string
Description
Identificador único de la tarea.
Name
type
Type
string
Description
Tipo de la tarea. El valor es text-to-motion.
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 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 epoch) de cuando la tarea comenzó a procesarse. 0 si no ha comenzado.
Name
finished_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde epoch) de cuando la tarea finalizó. 0 si no ha finalizado.
Name
expires_at
Type
timestamp
Description
Marca de tiempo (milisegundos desde epoch) de cuando los assets resultantes de la tarea expiran. 0 hasta que la tarea finalice. El clip generado se conserva durante 3 días después de que la tarea finaliza; descárgalo antes de que expire.
Name
preceding_tasks
Type
integer
Description
El recuento de tareas precedentes en la cola. Solo tiene sentido si el estado es PENDING; se omite cuando es cero.
Name
consumed_credits
Type
integer
Description
El número de créditos consumidos por esta tarea. 10 para el mode prime, 3 para el mode swift. Devuelve 0 para tareas FAILED (los créditos se reembolsan en caso de fallo).
Name
task_error
Type
object
Description
Detalles del error para tareas fallidas; null a menos que la tarea sea FAILED. Consulta Errores para la referencia completa del objeto task_error.
Name
result
Type
object
Description
Contiene el clip de movimiento generado una vez que la tarea es SUCCEEDED; hasta entonces los campos están presentes pero vacíos ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL descargable para el clip de movimiento generado. La URL se vuelve a firmar en cada lectura y expira con la ventana de retención de la tarea.
- Name
  motion_format
  Type
  string
  Description
  Formato de archivo del clip: fbx para el mode prime, bvh para el mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Duración del clip generado en milisegundos.
- Name
  mode
  Type
  string
  Description
  El mode con el que se generó el clip: prime o swift.

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
}