API de Texto para Movimento

Gere clipes de movimento de personagens a partir de descrições em linguagem natural. Descreva uma ação — "uma personagem a acenar", "um zombie a arrastar-se para a frente" — e receba um clipe de movimento em bruto que pode reaplicar a personagens com rigging no seu próprio pipeline ou ferramentas DCC.

O resultado é um clipe de movimento autónomo: não requer, nem está associado a, um modelo de personagem. Para primeiro fazer o rigging de uma personagem, consulte a API de Rigging. Para aplicar um clipe gerado à sua personagem com rigging, passe o id da tarefa como motion_task_id para a API de Animação — aplique-o dentro da janela de 3 dias de retenção de recursos.

POST/openapi/v1/text-to-motion

Criar uma Tarefa de Texto para Movimento

Este endpoint cria uma nova tarefa para gerar um clip de movimento a partir de um prompt de texto.

Uma tarefa com mode prime custa 10 créditos e gera com o nosso modelo de movimento de mais alta qualidade. Uma tarefa com mode swift custa 3 créditos e gera mais rapidamente com o nosso modelo de movimento económico.

Parâmetros

Name
prompt
Type
string
Obrigatório
Description
Uma descrição em linguagem natural do movimento a gerar. Máximo de 400 caracteres.
Name
mode
Type
string
predefinição prime
Description
O mode de geração de movimento. Valores disponíveis: prime, swift. prime produz a mais alta qualidade e gera FBX; swift é mais rápido e económico e gera BVH.
Name
duration
Type
number
Obrigatório
Description
A duração pretendida do clip de movimento em segundos. Entre 2 e 10, em incrementos de 0.5 (por exemplo, 2, 2.5, 3, … 10).

Retornos

A propriedade result da resposta contém o id da tarefa da tarefa de Texto para Movimento recém-criada.

Modos de Falha

Name
400 - Bad Request
Description
O pedido foi inaceitável. Causas comuns:
- Prompt ausente ou vazio: prompt está ausente, em branco, ou tem mais de 400 caracteres.
- Mode inválido: mode não é prime nem swift.
- Duração inválida: duration está ausente, fora do intervalo 2–10, ou não corresponde a um incremento de 0.5 segundos.
Name
401 - Unauthorized
Description
A autenticação falhou. Por favor, verifique a sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa.
Name
403 - Forbidden
Description
O prompt foi assinalado pela moderation de conteúdo.
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa.

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

Obter uma Tarefa de Texto para Movimento

Este endpoint permite-lhe obter uma tarefa de Texto para Movimento a partir de um id de tarefa válido. Consulte O Objeto de Tarefa de Texto para Movimento para ver quais propriedades estão incluídas.

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de Texto para Movimento a obter.

Retorno

A resposta contém o objeto de Tarefa de Texto para Movimento. Consulte a secção O Objeto de Tarefa de Texto para Movimento para mais detalhes.

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 Tarefas de Texto para Movimento

Devolve uma lista paginada das tarefas de Texto para Movimento do autor da chamada, das mais recentes para as mais antigas. Paginação padrão através de page_num e page_size.

A resposta é um array de objetos de Tarefa de Texto para Movimento.

Note que as tarefas criadas através da API são geridas através da API — não aparecem em Os Meus Assets da aplicação web. Utilize este endpoint para encontrar uma tarefa cujo ID já não tenha.

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 em Stream uma Tarefa de Texto para Movimento

Este endpoint transmite em stream atualizações em tempo real de uma tarefa de Texto para Movimento utilizando Server-Sent Events (SSE).

Parâmetros

Name
id
Type
path
Description
Identificador único da tarefa de Texto para Movimento a transmitir em stream.

Retorna

Retorna um stream de Objetos de Tarefa de Texto para Movimento como Server-Sent Events.

Cada evento message transporta o objeto de tarefa completo. Enquanto a tarefa estiver PENDING ou IN_PROGRESS, os campos result continuam vazios ("" / 0) e finished_at / expires_at são 0; observe status e 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 uma Tarefa de Texto para Movimento

Este endpoint elimina permanentemente uma tarefa de Texto para Movimento, incluindo o clipe de movimento gerado. Esta ação é irreversível.

Parâmetros de Path

Name
id
Type
path
Description
O ID da tarefa de Texto para Movimento a eliminar.

Retorna

Retorna 200 OK em caso de sucesso.

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.

O objeto Text to Motion Task

O objeto Text to Motion Task representa a unidade de trabalho para gerar um clipe de movimento a partir de um prompt de texto.

Propriedades

Name
id
Type
string
Description
Identificador único da tarefa.
Name
type
Type
string
Description
Tipo da tarefa. O valor é text-to-motion.
Name
status
Type
string
Description
Estado da tarefa. Valores possíveis: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progresso da tarefa (0-100).
Name
created_at
Type
timestamp
Description
Carimbo de data/hora (milissegundos desde a epoch) de quando a tarefa foi criada.
Um carimbo de data/hora representa o número de milissegundos decorridos desde 1 de janeiro de 1970 UTC, seguindo o padrão RFC 3339. Por exemplo, sexta-feira, 1 de setembro de 2023 às 12:00:00 GMT é representado como 1693569600000. Isto aplica-se a todos os carimbos de data/hora na Meshy API.
Name
started_at
Type
timestamp
Description
Carimbo de data/hora (milissegundos desde a epoch) de quando a tarefa começou a ser processada. 0 se ainda não tiver começado.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora (milissegundos desde a epoch) de quando a tarefa terminou. 0 se ainda não tiver terminado.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora (milissegundos desde a epoch) de quando os assets resultantes da tarefa expiram. 0 até a tarefa terminar. O clipe gerado é mantido durante 3 dias após a conclusão da tarefa; faça o download antes de expirar.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes na fila. Só é relevante se o estado for PENDING; é omitido quando é zero.
Name
consumed_credits
Type
integer
Description
O número de créditos consumidos por esta tarefa. 10 para o mode prime, 3 para o mode swift. Devolve 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).
Name
task_error
Type
object
Description
Detalhes do erro para tarefas falhadas; null a menos que a tarefa tenha FAILED. Consulte Erros para a referência completa do objeto task_error.
Name
result
Type
object
Description
Contém o clipe de movimento gerado uma vez que a tarefa tenha SUCCEEDED; até então os campos estão presentes mas vazios ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL de download do clipe de movimento gerado. O URL é reassinado em cada leitura e expira com a janela de retenção da tarefa.
- Name
  motion_format
  Type
  string
  Description
  Formato do ficheiro do clipe: fbx para o mode prime, bvh para o mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Duração do clipe gerado em milissegundos.
- Name
  mode
  Type
  string
  Description
  O mode com que o clipe foi gerado: prime ou 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
}