API Text to Motion

Gere clipes de movimento de personagens a partir de descrições de texto. Descreva uma ação, como "uma personagem a acenar" ou "um zombie a arrastar-se para a frente", e obtenha um clipe de movimento em bruto. Pode reaplicar o clipe a personagens com rig no seu próprio pipeline ou ferramentas DCC.

O resultado é um clipe de movimento autónomo. Não precisa de um modelo de personagem, nem está associado a um. Para fazer rigging de uma personagem primeiro, consulte a API de Rigging. Para aplicar um clipe à sua 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 Text to Motion

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

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

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

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

Retorna

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

Modos de falha

Name
400 - Bad Request
Description
O pedido não pode ser executado. A mensagem de erro indica qual o problema encontrado. Por exemplo:
- 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.
- Duration inválida: duration está em falta, fora do intervalo 2 a 10, ou não corresponde a um incremento de 0.5 segundos.
Corrija o pedido e envie-o novamente. Consulte Erros.
Name
401 - Unauthorized
Description
A chave de API está em falta 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 o seu saldo de créditos e tente novamente.
- Plano gratuito: Criar uma tarefa requer um plano pago. Atualize o seu plano nas suas definições de subscrição e tente novamente.
Name
403 - Forbidden
Description
A moderation de conteúdo assinalou o prompt. Altere o prompt e envie o pedido novamente.
Name
429 - Too Many Requests
Description
Excedeu o 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

Devolve uma tarefa de Text to Motion através do 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 proveniente da resposta de criação.

Devolve

O objeto de tarefa Text to Motion.

GET/openapi/v1/text-to-motion

Listar tarefas de Text to Motion

Devolve uma lista paginada das suas tarefas de Text to Motion, das mais recentes para as mais antigas. Para percorrer a lista, utilize page_num e page_size.

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

As tarefas que criar com a API permanecem na API e não aparecem em My Assets na aplicação web. Para encontrar uma tarefa cujo ID já não tem, utilize 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 em stream 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 proveniente da resposta de criação.

Retorna

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

Cada evento message transporta o objeto de tarefa completo. Enquanto a tarefa está PENDING ou IN_PROGRESS, os campos de result estão 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

Eliminar uma tarefa de Texto para Movimento

Elimina permanentemente uma tarefa de Texto para Movimento, incluindo o seu clip de movimento. Não pode anular uma eliminaçã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 rota

Name
id
Type
path
Description
O ID da tarefa a eliminar.

Estado da tarefa

Eliminar uma tarefa PENDING reembolsa os créditos que esta utilizou quando foi criada.

Uma tarefa IN_PROGRESS não pode ser eliminada. O pedido retorna 409 Conflict, e a tarefa continua a ser executada. A Meshy não reembolsa uma tarefa que já começou, pelo que eliminá-la custar-lhe-ia tanto os créditos como o resultado. Aguarde que esta atinja o estado SUCCEEDED, FAILED ou CANCELED, e só depois a elimine.

Eliminar uma tarefa num estado final (SUCCEEDED, FAILED ou CANCELED) não reembolsa os seus créditos.

Retorna

200 OK quando a tarefa é eliminada, 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. Contém o estado, o progress e o clipe quando a tarefa é bem-sucedida.

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 estado da tarefa, um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.
Name
progress
Type
integer
Description
Quanto da tarefa está concluído, como uma percentagem de 0 a 100.
Name
created_at
Type
timestamp
Description
Momento em que a tarefa foi criada, em milissegundos Unix.
Name
started_at
Type
timestamp
Description
Momento em que a tarefa foi iniciada, em milissegundos Unix. É 0 até a tarefa começar.
Name
finished_at
Type
timestamp
Description
Momento em que a tarefa terminou, em milissegundos Unix. É 0 até a tarefa terminar.
Name
expires_at
Type
timestamp
Description
Momento em que os ficheiros de resultado da tarefa expiram, em milissegundos Unix. É 0 até a tarefa terminar. A Meshy mantém o clipe durante 3 dias após a tarefa terminar, por isso descarregue-o antes disso.
Name
preceding_tasks
Type
integer
Description
O número de tarefas à frente desta na fila. O valor só é relevante 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 utilizou, 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. Consulte Erros.
Name
result
Type
object
Description
O clipe de movimento gerado quando a tarefa é bem-sucedida. Até lá, os campos estão presentes mas vazios ("" ou 0).
- Name
  motion_url
  Type
  string
  Description
  URL de descarregamento do clipe de movimento. A Meshy assina novamente o URL em cada leitura, e este expira com a janela de retenção da tarefa.
- Name
  motion_format
  Type
  string
  Description
  O formato de ficheiro 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 utilizou para gerar o clipe, prime ou swift.