API de Texto para Movimento

Gere clipes de movimento de personagens a partir de descrições em texto. Descreva uma ação, como "um personagem acenando" ou "um zumbi cambaleando para frente", e obtenha um clipe de movimento bruto. Você pode retargetar o clipe para personagens com rig em seu próprio pipeline ou ferramentas de DCC.

A saída é um clipe de movimento independente. Ele não precisa de um modelo de personagem, e não está vinculado a nenhum. Para fazer o rigging de um personagem primeiro, consulte a API de Rigging. Para aplicar um clipe ao seu personagem com rig, envie o id da tarefa como motion_task_id para a API de Animação.

POST/openapi/v1/text-to-motion

Criar uma tarefa de Text to Motion

Cria uma tarefa de Text to Motion, que gera um clipe de movimento a partir de um prompt de texto.

A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa geralmente leva, consulte Tempos de processamento.

Uma tarefa prime custa 10 créditos e usa o modelo de movimento de maior qualidade da Meshy. Uma tarefa swift custa 3 créditos e usa um modelo de movimento mais rápido e de menor custo.

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
Texto que descreve o movimento a ser gerado, com até 400 caracteres. Um texto mais longo retorna 400.
Name
mode
Type
string
padrão prime
Description
O modelo de movimento, que também define o formato de arquivo do clipe.
Valores disponíveis:
- prime: maior qualidade, retorna um clipe FBX
- swift: mais rápido e mais barato, retorna um clipe BVH
Qualquer outro valor retorna 400.
Name
duration
Type
number
Obrigatório
Description
A duração alvo do clipe em segundos, de 2 a 10 em incrementos de 0.5, por exemplo 2, 2.5 ou 3. Qualquer outro valor retorna 400.

Retornos

O campo result da resposta contém o ID da nova tarefa de Text to Motion.

Modos de falha

Name
400 - Bad Request
Description
A requisição não pode ser executada. A mensagem de erro informa qual problema foi encontrado. Por exemplo:
- Prompt ausente ou vazio: prompt está ausente, em branco ou tem mais de 400 caracteres.
- Mode inválido: mode não é prime nem swift.
- Duration inválida: duration está ausente, fora do intervalo de 2 a 10, ou não está em um incremento de 0.5 segundo.
Corrija a requisição e envie novamente. Consulte Erros.
Name
401 - Unauthorized
Description
A chave de API está ausente ou é inválida. Verifique o cabeçalho Authorization.
Name
402 - Payment Required
Description
Por exemplo:
- Créditos insuficientes: a conta não tem créditos suficientes para esta tarefa, ou a conta atingiu um limite de créditos. Verifique seu saldo de créditos e tente novamente.
- Plano gratuito: criar uma tarefa requer um plano pago. Faça upgrade do seu plano nas configurações de assinatura e tente novamente.
Name
403 - Forbidden
Description
A moderation de conteúdo sinalizou o prompt. Altere o prompt e envie a requisição novamente.
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.

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

Obter uma tarefa de Text to Motion

Retorna uma tarefa de Text to Motion pelo seu 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
O ID da tarefa retornado pela resposta de criação.

Retorno

O objeto de tarefa Text to Motion.

GET/openapi/v1/text-to-motion

Listar tarefas de Text to Motion

Retorna uma lista paginada das suas tarefas de Text to Motion, das mais recentes para as mais antigas. Para navegar pela lista, use page_num e page_size.

A resposta é um array de objetos de tarefa Text to Motion.

As tarefas que você cria com a API permanecem na API e não aparecem em My Assets no aplicativo web. Para encontrar uma tarefa cujo ID você não tem mais, use 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 uma tarefa de Text to Motion

Transmite as atualizações de uma tarefa de Text to Motion como 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 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
O ID da tarefa retornado na resposta de criação.

Retornos

Um stream de objetos de tarefa Text to Motion como Server-Sent Events.

Todo evento message carrega o objeto completo da tarefa. Enquanto a tarefa estiver PENDING ou IN_PROGRESS, os campos de result ficam vazios ("" ou 0), e finished_at e expires_at são 0. Para acompanhar a tarefa, observe status e progress.

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

Excluir uma tarefa de Text to Motion

Exclui permanentemente uma tarefa de Text to Motion, incluindo seu clipe de movimento. Você não pode desfazer uma exclusão.

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 caminho

Name
id
Type
path
Description
O ID da tarefa a ser excluída.

Status da tarefa

Excluir uma tarefa PENDING reembolsa os créditos usados ao criá-la.

Uma tarefa IN_PROGRESS não pode ser excluída. A requisição retorna 409 Conflict, e a tarefa continua em execução. A Meshy não reembolsa uma tarefa que já foi iniciada, então excluí-la custaria tanto os créditos quanto o resultado. Aguarde até que ela alcance o status SUCCEEDED, FAILED ou CANCELED para então excluí-la.

Excluir uma tarefa em um status final (SUCCEEDED, FAILED ou CANCELED) não reembolsa seus créditos.

Retornos

200 OK quando a tarefa é excluída, ou 409 Conflict quando a tarefa está IN_PROGRESS.

O objeto de tarefa Text to Motion

Um objeto de tarefa Text to Motion descreve a geração de um clipe de movimento. Ele contém o status, o progress e o clipe quando a tarefa é concluída com sucesso.

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
O ID da tarefa. Trate-o como uma string opaca e não dependa do seu formato.
Name
type
Type
string
Description
O tipo da tarefa, sempre text-to-motion.
Name
status
Type
string
Description
O status da tarefa, um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.
Name
progress
Type
integer
Description
Quanto da tarefa foi concluído, como uma porcentagem de 0 a 100.
Name
created_at
Type
timestamp
Description
Horário em que a tarefa foi criada, em milissegundos Unix.
Name
started_at
Type
timestamp
Description
Horário em que a tarefa foi iniciada, em milissegundos Unix. É 0 até a tarefa começar.
Name
finished_at
Type
timestamp
Description
Horário em que a tarefa foi concluída, em milissegundos Unix. É 0 até a tarefa terminar.
Name
expires_at
Type
timestamp
Description
Horário em que os arquivos de resultado da tarefa expiram, em milissegundos Unix. É 0 até a tarefa terminar. A Meshy mantém o clipe por 3 dias após a conclusão da tarefa, então faça o download antes disso.
Name
preceding_tasks
Type
integer
Description
O número de tarefas à frente desta na fila. O valor só é significativo enquanto a tarefa está PENDING. O campo é omitido quando o valor é 0.
Name
consumed_credits
Type
integer
Description
O número de créditos que a tarefa usou, 10 para o mode prime ou 3 para o mode swift. É 0 para uma tarefa FAILED, porque a Meshy reembolsa os créditos quando uma tarefa falha.
Name
task_error
Type
object
Description
Os detalhes do erro quando a tarefa falha, e null caso contrário. Veja Erros.
Name
result
Type
object
Description
O clipe de movimento gerado quando a tarefa é concluída com sucesso. Até lá, os campos estão presentes, mas vazios ("" ou 0).
- Name
  motion_url
  Type
  string
  Description
  URL de download para o clipe de movimento. A Meshy assina a URL novamente a cada leitura, e ela expira com a janela de retenção da tarefa.
- Name
  motion_format
  Type
  string
  Description
  O formato de arquivo do clipe, fbx para o mode prime ou bvh para o mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  A duração do clipe, em milissegundos.
- Name
  mode
  Type
  string
  Description
  O mode que a Meshy usou para gerar o clipe, prime ou swift.