API de Texto para Movimento

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

O resultado é um clip de movimento autónomo: não requer, nem está ligado a, um modelo de personagem. Para fazer o rigging de um personagem primeiro, veja a API de Rigging.

POST/openapi/v1/text-to-motion

Criar uma Tarefa de Texto para Movimento

Este endpoint cria uma nova tarefa para gerar um clipe 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 ser gerado. Máximo de 400 caracteres.
Name
mode
Type
string
predefinição prime
Description
O modo 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 alvo do clipe de movimento em segundos. Entre 2 e 10, em passos de 0.5 (por exemplo 2, 2.5, 3, … 10).

Retornos

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

Modos de Falha

Name
400 - Bad Request
Description
O pedido foi inaceitável. Causas comuns:
- Prompt em falta ou vazio: prompt está em falta, em branco, ou tem mais de 400 caracteres.
- Modo inválido: mode não é prime ou swift.
- Duração inválida: duration está em falta, fora do intervalo 2-10, ou não está num passo de 0.5 segundos.
Name
401 - Unauthorized
Description
A autenticação falhou. Por favor verifique a sua API key.
Name
402 - Payment Required
Description
Créditos insuficientes para executar esta tarefa.
Name
403 - Forbidden
Description
O prompt foi sinalizado 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

Recuperar uma Tarefa de Texto para Movimento

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

Parâmetros

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

Retornos

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

Pedido

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

Resposta

{
  "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 chamador, 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 — elas não aparecem nos Meus Assets da aplicação web. Use este endpoint para encontrar uma tarefa cujo ID já não possua.

Pedido

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

Resposta

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

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

Transmitir uma Tarefa de Texto para Movimento

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

Parâmetros

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

Retorna

Retorna um fluxo de Os Objetos da Tarefa de Texto para Movimento como Server-Sent Events.

Cada evento message carrega o objeto completo da tarefa. 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

// Exemplo de evento de erro
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Eventos de mensagem carregam o objeto completo da tarefa em cada etapa; os campos de resultado
// permanecem vazios até que a tarefa seja concluída com sucesso.
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: { // Exemplo de um item de fluxo de tarefa bem-sucedido (SUCCEEDED), espelhando a estrutura do Objeto da Tarefa de Texto para Movimento
  "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 clip de movimento gerado. Esta ação é irreversível.

Parâmetros de Caminho

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

Retornos

Retorna 200 OK em caso de sucesso.

Pedido

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

Resposta

// Retorna 200 Ok em caso de sucesso.

O Objeto Tarefa de Texto para Movimento

O objeto Tarefa de Texto para Movimento representa a unidade de trabalho para gerar um clip de movimento a partir de um prompt de texto.

Propriedades

Name
id
Type
string
Description
Identificador único para a tarefa.
Name
type
Type
string
Description
Tipo da tarefa. O valor é text-to-motion.
Name
status
Type
string
Description
Status 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 época) 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, 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 época) quando a tarefa começou a ser processada. 0 se não iniciada.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora (milissegundos desde a época) quando a tarefa terminou. 0 se não finalizada.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora (milissegundos desde a época) quando os assets do resultado da tarefa expiram. 0 até que a tarefa termine. O clip gerado é retido por 3 dias após a conclusão da tarefa; faça o download antes que expire.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes na fila. Relevante apenas se o status for PENDING; omitido quando for zero.
Name
consumed_credits
Type
integer
Description
O número de créditos usados por esta tarefa. 10 para o mode prime, 3 para o mode swift. Retorna 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 FAILED. Veja Erros para a referência completa do objeto task_error.
Name
result
Type
object
Description
Contém o clip de movimento gerado assim que a tarefa SUCCEEDED; até lá, os campos estão presentes mas vazios ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL descarregável para o clip de movimento gerado. O URL é re-assinado a cada leitura e expira com a janela de retenção da tarefa.
- Name
  motion_format
  Type
  string
  Description
  Formato de ficheiro do clip: fbx para o mode prime, bvh para o mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Duração do clip gerado em milissegundos.
- Name
  mode
  Type
  string
  Description
  O mode com que o clip foi gerado: prime ou swift.

Exemplo de Objeto Tarefa de Texto para Movimento

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