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 Text to Motion

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

A tarefa é executada em segundo plano. Para saber quanto tempo demora normalmente, consulte Tempos de Processamento.

Uma tarefa com mode prime custa 10 créditos e gera com o nosso modelo de movimento da mais alta qualidade. Uma tarefa com mode swift custa 3 créditos e gera mais rapidamente com o nosso modelo de movimento 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
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 em FBX; swift é mais rápido e económico e gera em BVH.
Name
duration
Type
number
Obrigatório
Description
A duração pretendida do clipe de movimento em segundos. Entre 2 e 10, em passos de 0.5 (por exemplo, 2, 2.5, 3, … 10).

Retorna

A propriedade result da resposta contém o id da tarefa de Text to Motion recém-criada.

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.
- Mode inválido: mode não é prime nem swift.
- Duração inválida: duration está em falta, fora do intervalo 2–10, ou não corresponde a um passo de 0.5 segundos.
Name
401 - Unauthorized
Description
Falha na autenticação. 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 sinalizado pela moderation de conteúdo.
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa.

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.

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

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).

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
}

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.

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

Eliminar uma tarefa de Text to Motion

Este endpoint elimina permanentemente uma tarefa de Text to Motion, incluindo o clipe de movimento gerado. Esta ação é irreversível.

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 is left 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 Caminho

Name
id
Type
path
Description
O ID da tarefa de Text to Motion a eliminar.

Estado da Tarefa

Uma tarefa que ainda está PENDING é eliminada e os créditos consumidos no momento da criação são reembolsados.

Uma tarefa que já está IN_PROGRESS não pode ser eliminada: o pedido é rejeitado com 409 Conflict e a tarefa continua em execução. Os créditos de uma tarefa que o worker já começou a processar não são reembolsáveis, pelo que eliminá-la a meio da execução custar-lhe-ia tanto os créditos como o resultado. Aguarde que atinja o estado SUCCEEDED, FAILED ou CANCELED e só depois a elimine.

Uma tarefa num estado terminal (SUCCEEDED, FAILED ou CANCELED) é eliminada sem reembolso.

Retorna

Retorna 200 OK em caso de sucesso, ou 409 Conflict quando a tarefa está IN_PROGRESS.

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

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