Text to Motion API

Genera clip di movimento dei personaggi a partire da descrizioni testuali. Descrivi un'azione, come "un personaggio che saluta con la mano" o "uno zombie che avanza barcollando", e ottieni una clip di movimento grezza. Puoi effettuare il retargeting della clip su personaggi con rig nella tua pipeline o nei tuoi strumenti DCC.

L'output è una clip di movimento autonoma. Non richiede un modello di personaggio e non è associata ad alcuno. Per prima cosa effettuare il rigging di un personaggio, consulta la Rigging API. Per applicare una clip al tuo personaggio con rig, invia l'id del task come motion_task_id alla Animazione API.

POST/openapi/v1/text-to-motion

Crea un task Text to Motion

Crea un task Text to Motion, che genera una clip di movimento a partire da un prompt testuale.

Il task viene eseguito in background. Per la durata tipica di un task, consulta Tempi di elaborazione.

Un task prime costa 10 crediti e utilizza il modello di movimento di qualità superiore di Meshy. Un task swift costa 3 crediti e utilizza un modello di movimento più veloce e a costo inferiore.

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

Parametri

Name
prompt
Type
string
Obbligatorio
Description
Testo che descrive il movimento da generare, fino a 400 caratteri. Un testo più lungo restituisce 400.
Name
mode
Type
string
predefinito prime
Description
Il modello di movimento, che determina anche il formato file della clip.
Valori disponibili:
- prime: qualità superiore, restituisce una clip FBX
- swift: più veloce ed economico, restituisce una clip BVH
Qualsiasi altro valore restituisce 400.
Name
duration
Type
number
Obbligatorio
Description
La lunghezza target della clip in secondi, da 2 a 10 con incrementi di 0.5, ad esempio 2, 2.5 o 3. Qualsiasi altro valore restituisce 400.

Valori restituiti

Il campo result della risposta contiene l'ID del nuovo task Text to Motion.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Il messaggio di errore indica quale problema è stato riscontrato. Ad esempio:
- Prompt mancante o vuoto: prompt è mancante, vuoto o supera i 400 caratteri.
- Mode non valido: mode non è prime né swift.
- Duration non valida: duration è mancante, fuori dall'intervallo 2-10, oppure non è un multiplo di 0.5 secondi.
Correggi la richiesta, quindi inviala di nuovo. Consulta Errori.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'header Authorization.
Name
402 - Payment Required
Description
Ad esempio:
- Crediti insufficienti: l'account non ha crediti sufficienti per questo task, oppure l'account ha raggiunto un limite di credito. Controlla il tuo saldo crediti, quindi riprova.
- Piano gratuito: la creazione di un task richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, quindi riprova.
Name
403 - Forbidden
Description
La moderation dei contenuti ha segnalato il prompt. Modifica il prompt, quindi invia nuovamente la richiesta.
Name
429 - Too Many Requests
Description
Hai superato il limite di frequenza. Attendi, quindi riprova. Consulta Limiti di frequenza.

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

Ottieni un task Text to Motion

Restituisce un task Text to Motion in base al suo 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
}

Parametri

Name
id
Type
path
Description
L'ID del task dalla risposta di creazione.

Restituisce

L'oggetto task Text to Motion.

GET/openapi/v1/text-to-motion

Elenco dei task Text to Motion

Restituisce un elenco paginato dei tuoi task Text to Motion, dal più recente al meno recente. Per scorrere l'elenco, usa page_num e page_size.

La risposta è un array di oggetti task Text to Motion.

I task creati tramite l'API restano nell'API e non compaiono in My Assets nell'app web. Per trovare un task di cui non hai più l'ID, usa questo 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

Esegui lo streaming di un task Text to Motion

Esegue lo streaming degli aggiornamenti di un task Text to Motion come 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
}

Parametri

Name
id
Type
path
Description
L'ID del task restituito dalla risposta di creazione.

Restituisce

Un flusso di oggetti task Text to Motion come Server-Sent Events.

Ogni evento message contiene l'oggetto task completo. Finché il task è PENDING o IN_PROGRESS, i campi result sono vuoti ("" o 0), e finished_at ed expires_at sono 0. Per seguire l'andamento del task, osserva status e progress.

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

Elimina un task di Text to Motion

Elimina definitivamente un task di Text to Motion, inclusa la sua clip di movimento. Non puoi annullare un'eliminazione.

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

Parametri del percorso

Name
id
Type
path
Description
L'ID del task da eliminare.

Stato del task

Eliminare un task PENDING rimborsa i crediti utilizzati al momento della sua creazione.

Un task IN_PROGRESS non può essere eliminato. La richiesta restituisce 409 Conflict, e il task continua a essere eseguito. Meshy non rimborsa un task che è già iniziato, quindi eliminarlo ti farebbe perdere sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminalo.

Eliminare un task in uno stato finale (SUCCEEDED, FAILED o CANCELED) non rimborsa i suoi crediti.

Risultati restituiti

200 OK quando il task viene eliminato, oppure 409 Conflict quando il task è IN_PROGRESS.

L'oggetto task Text to Motion

Un oggetto task Text to Motion descrive la generazione di una clip di movimento. Contiene lo stato, il progress e la clip quando il task ha successo.

Proprietà

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
L'ID del task. Trattalo come una stringa opaca e non fare affidamento sul suo formato.
Name
type
Type
string
Description
Il tipo di task, sempre text-to-motion.
Name
status
Type
string
Description
Lo stato del task, uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
progress
Type
integer
Description
Quanto del task è stato completato, come percentuale da 0 a 100.
Name
created_at
Type
timestamp
Description
Ora di creazione del task, in millisecondi Unix.
Name
started_at
Type
timestamp
Description
Ora di avvio del task, in millisecondi Unix. È 0 finché il task non inizia.
Name
finished_at
Type
timestamp
Description
Ora di completamento del task, in millisecondi Unix. È 0 finché il task non termina.
Name
expires_at
Type
timestamp
Description
Ora in cui i file di risultato del task scadono, in millisecondi Unix. È 0 finché il task non termina. Meshy conserva la clip per 3 giorni dopo il completamento del task, quindi scaricala entro quel termine.
Name
preceding_tasks
Type
integer
Description
Il numero di task davanti a questo nella coda. Il valore è significativo solo mentre il task è PENDING. Il campo viene omesso quando il valore è 0.
Name
consumed_credits
Type
integer
Description
Il numero di crediti utilizzati dal task, 10 per il mode prime o 3 per il mode swift. È 0 per un task FAILED, perché Meshy rimborsa i crediti quando un task fallisce.
Name
task_error
Type
object
Description
I dettagli dell'errore quando il task fallisce, altrimenti null. Vedi Errori.
Name
result
Type
object
Description
La clip di movimento generata quando il task ha successo. Fino ad allora, i campi sono presenti ma vuoti ("" o 0).
- Name
  motion_url
  Type
  string
  Description
  URL di download per la clip di movimento. Meshy firma nuovamente l'URL a ogni lettura, e scade con la finestra di conservazione del task.
- Name
  motion_format
  Type
  string
  Description
  Il formato file della clip, fbx per il mode prime o bvh per il mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  La durata della clip, in millisecondi.
- Name
  mode
  Type
  string
  Description
  Il mode utilizzato da Meshy per generare la clip, prime o swift.