API Text to Motion

Genera clip di movimento per personaggi a partire da descrizioni in linguaggio naturale. Descrivi un'azione — "un personaggio che saluta con la mano", "uno zombie che avanza barcollando" — e ricevi una clip di movimento grezza che puoi retargettare su personaggi con rig nella tua pipeline o nei tuoi strumenti DCC.

L'output è una clip di movimento autonoma: non richiede, e non è collegata a, un modello di personaggio. Per eseguire prima il rigging di un personaggio, consulta la API di Rigging. Per applicare una clip generata al tuo personaggio con rig, passa l'id dell'attività come motion_task_id alla API Animazione — applicala entro la finestra di conservazione degli asset di 3 giorni.

POST/openapi/v1/text-to-motion

Crea un'attività Text to Motion

Questo endpoint crea una nuova attività per generare una clip di movimento a partire da un prompt testuale.

Un'attività con mode prime costa 10 crediti e genera con il nostro modello di movimento di massima qualità. Un'attività con mode swift costa 3 crediti e genera più velocemente con il nostro modello di movimento economico.

Parametri

Name
prompt
Type
string
Obbligatorio
Description
Una descrizione in linguaggio naturale del movimento da generare. Massimo 400 caratteri.
Name
mode
Type
string
predefinito prime
Description
La mode di generazione del movimento. Valori disponibili: prime, swift. prime produce la qualità più alta e restituisce FBX; swift è più veloce ed economico e restituisce BVH.
Name
duration
Type
number
Obbligatorio
Description
La durata target della clip di movimento in secondi. Compresa tra 2 e 10, con incrementi di 0.5 (ad esempio 2, 2.5, 3, … 10).

Valori restituiti

La proprietà result della risposta contiene l'id dell'attività dell'attività Text to Motion appena creata.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Prompt mancante o vuoto: prompt è mancante, vuoto, oppure più lungo di 400 caratteri.
- Mode non valida: mode non è prime né swift.
- Duration non valida: duration è mancante, fuori dall'intervallo 2–10, oppure non su un incremento di 0.5 secondi.
Name
401 - Unauthorized
Description
Autenticazione fallita. Controlla la tua API key.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questa attività.
Name
403 - Forbidden
Description
Il prompt è stato segnalato dalla moderation dei contenuti.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.

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

Recupera un'attività Text to Motion

Questo endpoint consente di recuperare un'attività Text to Motion dato un id valido. Fai riferimento a The Text to Motion Task Object per vedere quali proprietà sono incluse.

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività Text to Motion da recuperare.

Restituisce

La risposta contiene l'oggetto Text to Motion Task. Consulta la sezione The Text to Motion Task Object per i dettagli.

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
}

GET/openapi/v1/text-to-motion

Elenco delle attività Text to Motion

Restituisce un elenco paginato delle attività Text to Motion del chiamante, dalla più recente. Paginazione standard tramite page_num e page_size.

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

Nota che le attività create tramite l'API vengono gestite tramite l'API: non compaiono in My Assets dell'app web. Usa questo endpoint per trovare un'attività di cui non hai più l'ID.

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

Effettua lo streaming di un'attività Text to Motion

Questo endpoint effettua lo streaming di aggiornamenti in tempo reale per un'attività Text to Motion utilizzando i Server-Sent Events (SSE).

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività Text to Motion di cui eseguire lo streaming.

Restituisce

Restituisce uno stream di Oggetti Attività Text to Motion come Server-Sent Events.

Ogni evento message contiene l'intero oggetto attività. Mentre l'attività è in stato PENDING o IN_PROGRESS, i campi result sono ancora vuoti ("" / 0) e finished_at / expires_at valgono 0; monitora 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

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

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

Elimina un'attività Text to Motion

Questo endpoint elimina definitivamente un'attività Text to Motion, incluso il clip di movimento generato. Questa azione è irreversibile.

Parametri del percorso

Name
id
Type
path
Description
L'ID dell'attività Text to Motion da eliminare.

Valori restituiti

Restituisce 200 OK in caso di successo.

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

// Returns 200 Ok on success.

L'oggetto Task Text to Motion

L'oggetto Task Text to Motion rappresenta l'unità di lavoro per generare una clip di movimento a partire da un prompt testuale.

Proprietà

Name
id
Type
string
Description
Identificatore univoco del task.
Name
type
Type
string
Description
Tipo del task. Il valore è text-to-motion.
Name
status
Type
string
Description
Stato del task. Valori possibili: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress del task (0-100).
Name
created_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) in cui il task è stato creato.
Un timestamp rappresenta il numero di millisecondi trascorsi dal 1° gennaio 1970 UTC, seguendo lo standard RFC 3339. Ad esempio, venerdì 1 settembre 2023 12:00:00 PM GMT è rappresentato come 1693569600000. Questo si applica a tutti i timestamp in Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) in cui il task ha iniziato l'elaborazione. 0 se non ancora iniziato.
Name
finished_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) in cui il task è terminato. 0 se non ancora terminato.
Name
expires_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) in cui gli asset risultanti dal task scadono. 0 finché il task non termina. La clip generata viene conservata per 3 giorni dopo il completamento del task; scaricala prima che scada.
Name
preceding_tasks
Type
integer
Description
Il numero di task precedenti nella coda. Significativo solo se lo status è PENDING; omesso quando è zero.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questo task. 10 per la mode prime, 3 per la mode swift. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di fallimento).
Name
task_error
Type
object
Description
Dettagli dell'errore per i task falliti; null a meno che il task non sia FAILED. Consulta Errori per il riferimento completo all'oggetto task_error.
Name
result
Type
object
Description
Contiene la clip di movimento generata una volta che il task è SUCCEEDED; fino a quel momento i campi sono presenti ma vuoti ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL scaricabile per la clip di movimento generata. L'URL viene rifirmato a ogni lettura e scade con la finestra di conservazione del task.
- Name
  motion_format
  Type
  string
  Description
  Formato del file della clip: fbx per la mode prime, bvh per la mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Durata della clip generata in millisecondi.
- Name
  mode
  Type
  string
  Description
  La mode con cui è stata generata la clip: prime o swift.

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
}