Text-to-Motion-API

Erzeugen Sie Charakterbewegungsclips aus natürlichsprachlichen Beschreibungen. Beschreiben Sie eine Aktion – "eine Figur winkt", "ein Zombie schlurft vorwärts" – und erhalten Sie einen Rohbewegungsclip, den Sie auf rigged Charaktere in Ihrer eigenen Pipeline oder DCC-Tools anpassen können.

Die Ausgabe ist ein eigenständiger Bewegungsclip: Er erfordert kein Charaktermodell und ist nicht daran angehängt. Um einen Charakter zuerst zu riggen, siehe die Rigging-API.

POST/openapi/v1/text-to-motion

Erstellen einer Text zu Bewegung Aufgabe

Dieser Endpunkt erstellt eine neue Aufgabe, um einen Bewegungsclip aus einem Text-Prompt zu generieren.

Eine Aufgabe mit mode prime kostet 10 Credits und generiert mit unserem hochqualitativen Bewegungsmodell. Eine Aufgabe mit mode swift kostet 3 Credits und generiert schneller mit unserem wirtschaftlichen Bewegungsmodell.

Parameter

Name
prompt
Type
string
Erforderlich
Description
Eine natürlichsprachliche Beschreibung der zu generierenden Bewegung. Maximal 400 Zeichen.
Name
mode
Type
string
Standard prime
Description
Der Bewegungsmodus der Generierung. Verfügbare Werte: prime, swift. prime erzeugt die höchste Qualität und gibt FBX aus; swift ist schneller und günstiger und gibt BVH aus.
Name
duration
Type
number
Erforderlich
Description
Die Zieldauer des Bewegungsclips in Sekunden. Zwischen 2 und 10, in Schritten von 0.5 (zum Beispiel 2, 2.5, 3, … 10).

Rückgaben

Die result-Eigenschaft der Antwort enthält die Aufgabend id der neu erstellten Text zu Bewegung Aufgabe.

Fehlerfälle

Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
- Fehlender oder leerer Prompt: prompt fehlt, ist leer oder länger als 400 Zeichen.
- Ungültiger Modus: mode ist nicht prime oder swift.
- Ungültige Dauer: duration fehlt, liegt außerhalb von 2–10 oder ist nicht im 0.5 Sekunden-Schritt.
Name
401 - Unauthorized
Description
Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.
Name
402 - Payment Required
Description
Unzureichende Credits, um diese Aufgabe auszuführen.
Name
403 - Forbidden
Description
Der Prompt wurde durch Content-moderation gekennzeichnet.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten.

Request

POST

/openapi/v1/text-to-motion

# Generieren eines Bewegungsclips nur mit den erforderlichen Parametern
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
  }'

# Generieren eines schnellen, wirtschaftlichen Clips im Swift-Modus
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

Abrufen einer Text-zu-Bewegung-Aufgabe

Dieser Endpunkt ermöglicht es Ihnen, eine Text-zu-Bewegung-Aufgabe mit einer gültigen Aufgaben-id abzurufen. Siehe Das Text-zu-Bewegung-Aufgabenobjekt, um zu sehen, welche Eigenschaften enthalten sind.

Parameter

Name
id
Type
path
Description
Eindeutiger Bezeichner für die abzurufende Text-zu-Bewegung-Aufgabe.

Rückgabewerte

Die Antwort enthält das Text-zu-Bewegung-Aufgabenobjekt. Details finden Sie im Abschnitt Das Text-zu-Bewegung-Aufgabenobjekt.

Anfrage

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

Antwort

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

Liste der Text-zu-Bewegung-Aufgaben

Gibt eine paginierte Liste der Text-zu-Bewegung-Aufgaben des Anrufers zurück, beginnend mit den neuesten. Standard-Paginierung über page_num und page_size.

Die Antwort ist ein Array von Text-zu-Bewegung-Aufgaben-Objekten.

Beachten Sie, dass Aufgaben, die über die API erstellt wurden, auch über die API verwaltet werden — sie erscheinen nicht in den "Meine Assets" der Web-App. Verwenden Sie diesen Endpunkt, um eine Aufgabe zu finden, deren ID Sie nicht mehr haben.

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

Streamen einer Text-zu-Bewegung-Aufgabe

Dieser Endpunkt streamt Echtzeit-Updates für eine Text-zu-Bewegung-Aufgabe unter Verwendung von Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutiger Bezeichner für die Text-zu-Bewegung-Aufgabe zum Streamen.

Rückgaben

Gibt einen Stream von Die Text-zu-Bewegung-Aufgaben-Objekten als Server-Sent Events zurück.

Jedes message-Ereignis enthält das vollständige Aufgabenobjekt. Solange die Aufgabe PENDING oder IN_PROGRESS ist, bleiben die Felder result leer ("" / 0) und finished_at / expires_at sind 0; beobachten Sie status und 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

// Beispiel für ein Fehlerereignis
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Nachrichtenevents enthalten das vollständige Aufgabenobjekt in jeder Phase; die Ergebnisfelder bleiben leer, bis die Aufgabe erfolgreich abgeschlossen ist.
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: { // Beispiel eines SUCCEEDED-Aufgabenstream-Elements, das die Struktur der Text-zu-Bewegung-Aufgabe widerspiegelt
  "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

Löschen einer Text-to-Motion-Aufgabe

Dieser Endpunkt löscht dauerhaft eine Text-to-Motion-Aufgabe, einschließlich des generierten Bewegungsclips. Diese Aktion ist unwiderruflich.

Pfadparameter

Name
id
Type
path
Description
Die ID der zu löschenden Text-to-Motion-Aufgabe.

Rückgaben

Gibt 200 OK bei Erfolg zurück.

Anfrage

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

Antwort

// Gibt 200 Ok bei Erfolg zurück.

Das Text-zu-Bewegung Auftragsobjekt

Das Text-zu-Bewegung Auftragsobjekt repräsentiert die Arbeitseinheit zur Erstellung eines Bewegungsclips aus einem Text-prompt.

Eigenschaften

Name
id
Type
string
Description
Eindeutiger Identifikator für den Auftrag.
Name
type
Type
string
Description
Typ des Auftrags. Der Wert ist text-to-motion.
Name
status
Type
string
Description
Status des Auftrags. Mögliche Werte: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Fortschritt des Auftrags (0-100).
Name
created_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit dem Epoch) wann der Auftrag erstellt wurde.
Ein Zeitstempel repräsentiert die Anzahl der Millisekunden, die seit dem 1. Januar 1970 UTC vergangen sind, gemäß dem RFC 3339 Standard. Zum Beispiel wird Freitag, der 1. September 2023, 12:00:00 Ortszeit GMT als 1693569600000 dargestellt. Dies gilt für alle Zeitstempel in der Meshy API.
Name
started_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit dem Epoch) wann der Auftrag begonnen hat zu verarbeiten. 0 wenn nicht gestartet.
Name
finished_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit dem Epoch) wann der Auftrag abgeschlossen wurde. 0 wenn nicht abgeschlossen.
Name
expires_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit dem Epoch) wann die Ergebnassets des Auftrags verfallen. 0 bis der Auftrag abgeschlossen ist. Der generierte Clip wird für 3 Tage nach Abschluss des Auftrags beibehalten; laden Sie ihn herunter, bevor er verfällt.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorausgehenden Aufgaben in der Warteschlange. Sinnvoll nur, wenn der Status PENDING ist; wird ausgelassen, wenn null.
Name
consumed_credits
Type
integer
Description
Die Anzahl der Credits, die von diesem Auftrag verbraucht wurden. 10 für prime mode, 3 für swift mode. Gibt 0 für FAILED Aufträge zurück (Credits werden bei einem Misserfolg zurückerstattet).
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Aufträge; null, es sei denn der Auftrag ist FAILED. Siehe Fehler für die vollständige task_error Objekt-Referenz.
Name
result
Type
object
Description
Beinhaltet den generierten Bewegungsclip, sobald der Auftrag SUCCEEDED ist; bis dahin sind die Felder vorhanden, aber leer ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Herunterladbare URL für den generierten Bewegungsclip. Die URL wird bei jedem Lesen neu signiert und läuft mit dem Aufbewahrungsfenster des Auftrags ab.
- Name
  motion_format
  Type
  string
  Description
  Dateiformat des Clips: fbx für prime mode, bvh für swift mode.
- Name
  duration_ms
  Type
  integer
  Description
  Dauer des generierten Clips in Millisekunden.
- Name
  mode
  Type
  string
  Description
  Der Modus, in dem der Clip generiert wurde: prime oder 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
}