API da Testo a Movimento

Genera clip di movimento del personaggio da descrizioni in linguaggio naturale. Descrivi un'azione — "un personaggio che saluta", "uno zombie che avanza barcollando" — e ricevi un clip di movimento grezzo che puoi riassegnare su personaggi rigged nella tua pipeline o nei tuoi strumenti DCC.

L'output è un clip di movimento autonomo: non richiede e non è collegato a un modello di personaggio. Per riggare un personaggio prima, vedi l'API di Rigging.

POST/openapi/v1/text-to-motion

Creare un'attività Text to Motion

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

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 modalità di generazione del movimento. Valori disponibili: prime, swift. prime produce la qualità più alta e output FBX; swift è più veloce ed economica e output BVH.
Name
duration
Type
number
Obbligatorio
Description
La durata target della clip del movimento in secondi. Tra 2 e 10, a intervalli di 0.5 (per esempio 2, 2.5, 3, … 10).

Restituisce

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

Modalità di fallimento

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Prompt mancante o vuoto: prompt è mancante, vuoto, o più lungo di 400 caratteri.
- Modalità non valida: mode non è prime o swift.
- Durata non valida: duration è mancante, al di fuori di 2–10, o non su un intervallo di 0.5 secondi.
Name
401 - Unauthorized
Description
L'autenticazione è fallita. Si prega di controllare la propria chiave API.
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.

Richiesta

POST

/openapi/v1/text-to-motion

# Genera una clip di movimento con soli parametri obbligatori
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": "un personaggio che saluta",
    "duration": 3
  }'

# Genera una clip veloce ed economica con modalità Swift
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": "un personaggio che saluta",
    "mode": "swift",
    "duration": 4.5
  }'

Risposta

{
  "result": "018c425b-b2c6-727e-d333-3c1887i9h791"
}

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

Recupera un'attività di Testo in Movimento

Questo endpoint consente di recuperare un'attività di Testo in Movimento dato un valido id del compito. Consulta L'oggetto Attività di Testo in Movimento per vedere quali proprietà sono incluse.

Parametri

Name
id
Type
path
Description
Identificatore univoco per l'attività di Testo in Movimento da recuperare.

Restituzioni

La risposta contiene l'oggetto Attività di Testo in Movimento. Controlla la sezione L'oggetto Attività di Testo in Movimento per i dettagli.

Richiesta

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

Risposta

{
  "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à di Testo in Movimento

Restituisce un elenco con paginazione delle attività di Testo in Movimento del chiamante, partendo dalle più recenti. Paginazione standard tramite page_num e page_size.

La risposta è un array di Oggetti Attività di Testo in Movimento.

Nota che le attività create tramite l'API sono gestite tramite l'API — non appaiono nei Miei Asset dell'app web. Usa questo endpoint per trovare un'attività di cui non hai più l'ID.

Richiesta

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

Risposta

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]

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

Stream di un'attività Testo in Movimento

Questo endpoint trasmette aggiornamenti in tempo reale per un'attività Testo in Movimento utilizzando Server-Sent Events (SSE).

Parametri

Name
id
Type
path
Description
Identificatore univoco per l'attività Testo in Movimento da trasmettere.

Restituzioni

Restituisce un flusso di Gli Oggetti dell'Attività Testo in Movimento come Server-Sent Events.

Ogni evento message trasporta l'intero oggetto attività. Mentre l'attività è PENDING o IN_PROGRESS, i campi result sono ancora vuoti ("" / 0) e finished_at / expires_at sono 0; osserva status e progress.

Richiesta

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

Stream di Risposta

// Esempio di evento errore
event: error
data: {
  "status_code": 404,
  "message": "Attività non trovata"
}

// Gli eventi di messaggio trasportano l'intero oggetto attività in ogni fase; i campi result rimangono vuoti fino a quando l'attività non ha successo.
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: { // Esempio di un elemento di flusso di attività riuscito, che rispecchia la struttura dell'Oggetto Attività Testo in Movimento
  "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

Eliminare un'attività di Text to Motion

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

Parametri del percorso

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

Restituisce

Restituisce 200 OK in caso di successo.

Richiesta

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

Risposta

// Restituisce 200 Ok in caso di successo.

L'oggetto Task di Testo a Movimento

L'oggetto Task di Testo a Movimento rappresenta l'unità di lavoro per generare un clip di movimento da un prompt di testo.

Proprietà

Name
id
Type
string
Description
Identificatore univoco per il task.
Name
type
Type
string
Description
Tipo di 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
Avanzamento del task (0-100).
Name
created_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) quando 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) quando il task ha iniziato l'elaborazione. 0 se non iniziata.
Name
finished_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) quando il task è terminato. 0 se non terminato.
Name
expires_at
Type
timestamp
Description
Timestamp (millisecondi dall'epoch) quando gli asset risultanti del task scadono. 0 fino al completamento del task. Il clip generato viene conservato per 3 giorni dopo il completamento del task; scaricalo prima che scada.
Name
preceding_tasks
Type
integer
Description
Il numero di task precedenti nella coda. Significativo solo se lo stato è PENDING; omesso quando è zero.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questo task. 10 per il mode prime, 3 per il mode swift. Restituisce 0 per task FAILED (i crediti vengono rimborsati in caso di fallimento).
Name
task_error
Type
object
Description
Dettagli degli errori per i task falliti; null a meno che il task non sia FAILED. Vedi Errori per il riferimento completo all'oggetto task_error.
Name
result
Type
object
Description
Contiene il clip di movimento generato una volta che il task è SUCCEEDED; fino ad allora i campi sono presenti ma vuoti ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  URL scaricabile per il clip di movimento generato. L'URL viene risignato a ogni lettura e scade con la finestra di conservazione del task.
- Name
  motion_format
  Type
  string
  Description
  Formato del file del clip: fbx per il mode prime, bvh per il mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Durata del clip generato in millisecondi.
- Name
  mode
  Type
  string
  Description
  Il mode con cui è stato generato il clip: prime o swift.

Esempio di Oggetto Task di Testo a Movimento

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