Text-to-Motion-API

Erzeuge Bewegungsclips für Charaktere aus Textbeschreibungen. Beschreibe eine Aktion, etwa „ein winkender Charakter" oder „ein vorwärts schlurfender Zombie", und erhalte einen rohen Bewegungsclip. Du kannst den Clip in deiner eigenen Pipeline oder deinen DCC-Tools auf gerigte Charaktere retargetieren.

Die Ausgabe ist ein eigenständiger Bewegungsclip. Er benötigt kein Charaktermodell und ist auch an keines gebunden. Um zunächst einen Charakter zu riggen, siehe die Rigging-API. Um einen Clip auf deinen gerigten Charakter anzuwenden, sende die Task-id als motion_task_id an die Animation-API.

POST/openapi/v1/text-to-motion

Erstellen einer Text-to-Motion-Aufgabe

Erstellt eine Text-to-Motion-Aufgabe, die aus einem Text-prompt einen Bewegungsclip generiert.

Die Aufgabe läuft im Hintergrund. Wie lange eine Aufgabe in der Regel dauert, erfahren Sie unter Verarbeitungszeiten.

Eine prime-Aufgabe kostet 10 Credits und verwendet Meshys hochwertigeres Bewegungsmodell. Eine swift-Aufgabe kostet 3 Credits und verwendet ein schnelleres, kostengünstigeres Bewegungsmodell.

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

Parameter

Name
prompt
Type
string
Erforderlich
Description
Text, der die zu generierende Bewegung beschreibt, bis zu 400 Zeichen. Längerer Text führt zu 400.
Name
mode
Type
string
Standard prime
Description
Das Bewegungsmodell, das auch das Dateiformat des Clips festlegt.
Verfügbare Werte:
- prime: höhere Qualität, liefert einen FBX-Clip
- swift: schneller und günstiger, liefert einen BVH-Clip
Jeder andere Wert führt zu 400.
Name
duration
Type
number
Erforderlich
Description
Die angestrebte Clip-Länge in Sekunden, von 2 bis 10 in Schritten von 0.5, zum Beispiel 2, 2.5 oder 3. Jeder andere Wert führt zu 400.

Rückgabewerte

Das Feld result der Antwort enthält die ID der neuen Text-to-Motion-Aufgabe.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage kann nicht ausgeführt werden. Die Fehlermeldung gibt an, welches Problem gefunden wurde. Zum Beispiel:
- Fehlender oder leerer prompt: prompt fehlt, ist leer oder länger als 400 Zeichen.
- Ungültiger mode: mode ist weder prime noch swift.
- Ungültige duration: duration fehlt, liegt außerhalb des Bereichs 2 bis 10 oder entspricht keinem 0.5-Sekunden-Schritt.
Korrigieren Sie die Anfrage und senden Sie sie erneut. Siehe Fehler.
Name
401 - Unauthorized
Description
Der API-Schlüssel fehlt oder ist ungültig. Überprüfen Sie den Authorization-Header.
Name
402 - Payment Required
Description
Zum Beispiel:
- Unzureichende Credits: Das Konto verfügt nicht über genügend Credits für diese Aufgabe, oder das Konto hat ein Credit-Limit erreicht. Überprüfen Sie Ihr Guthaben und versuchen Sie es erneut.
- Kostenloser Plan: Das Erstellen einer Aufgabe erfordert einen kostenpflichtigen Plan. Aktualisieren Sie Ihren Plan in Ihren Abonnement-Einstellungen und versuchen Sie es erneut.
Name
403 - Forbidden
Description
Die Content-moderation hat den prompt markiert. Ändern Sie den prompt und senden Sie die Anfrage erneut.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten. Warten Sie und versuchen Sie es erneut. Siehe Ratenbegrenzungen.

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

Eine Text-to-Motion-Aufgabe abrufen

Gibt eine Text-to-Motion-Aufgabe anhand ihrer ID zurück.

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
}

Parameter

Name
id
Type
path
Description
Die Aufgaben-ID aus der Erstellungsantwort.

Rückgabe

Das Text-to-Motion-Aufgabenobjekt.

GET/openapi/v1/text-to-motion

Liste der Text-to-Motion-Aufgaben

Gibt eine paginierte Liste Ihrer Text-to-Motion-Aufgaben zurück, neueste zuerst. Um durch die Liste zu blättern, verwenden Sie page_num und page_size.

Die Antwort ist ein Array von Text-to-Motion-Aufgabenobjekten.

Aufgaben, die Sie über die API erstellen, verbleiben in der API und erscheinen nicht unter My Assets in der Web-App. Um eine Aufgabe zu finden, deren ID Sie nicht mehr haben, verwenden Sie diesen Endpunkt.

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

Stream einer Text-to-Motion-Aufgabe

Streamt die Updates einer Text-to-Motion-Aufgabe als 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
}

Parameter

Name
id
Type
path
Description
Die Task-ID aus der Antwort der Erstellung.

Rückgabewerte

Ein Stream von Text-to-Motion-Task-Objekten als Server-Sent Events.

Jedes message-Event enthält das vollständige Task-Objekt. Solange die Aufgabe PENDING oder IN_PROGRESS ist, sind die result-Felder leer ("" oder 0), und finished_at sowie expires_at sind 0. Um den Fortschritt der Aufgabe zu verfolgen, beobachten Sie status und progress.

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

Einen Text-zu-Motion-Task löschen

Löscht einen Text-zu-Motion-Task dauerhaft, einschließlich seines Motion-Clips. Ein Löschvorgang kann nicht rückgängig gemacht werden.

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

Pfadparameter

Name
id
Type
path
Description
Die ID des zu löschenden Tasks.

Task-Status

Das Löschen eines PENDING-Tasks erstattet die Credits, die bei seiner Erstellung verwendet wurden.

Ein IN_PROGRESS-Task kann nicht gelöscht werden. Die Anfrage gibt 409 Conflict zurück, und der Task läuft weiter. Meshy erstattet keinen Task, der bereits gestartet wurde, da das Löschen Sie sowohl die Credits als auch das Ergebnis kosten würde. Warten Sie, bis er den Status SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie ihn dann.

Das Löschen eines Tasks in einem finalen Status (SUCCEEDED, FAILED oder CANCELED) erstattet dessen Credits nicht.

Rückgabewerte

200 OK, wenn der Task gelöscht wurde, oder 409 Conflict, wenn der Task IN_PROGRESS ist.

Das Text-to-Motion-Task-Objekt

Ein Text-to-Motion-Task-Objekt beschreibt die Generierung eines Motion-Clips. Es enthält den Status, den progress und den Clip, sobald der Task erfolgreich abgeschlossen wurde.

Eigenschaften

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
Die Task-ID. Behandeln Sie sie als intransparente Zeichenkette und verlassen Sie sich nicht auf ihr Format.
Name
type
Type
string
Description
Der Task-Typ, immer text-to-motion.
Name
status
Type
string
Description
Der Task-Status, einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED oder CANCELED.
Name
progress
Type
integer
Description
Wie viel vom Task erledigt ist, als Prozentsatz von 0 bis 100.
Name
created_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task erstellt wurde, in Unix-Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task gestartet wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task startet.
Name
finished_at
Type
timestamp
Description
Zeitpunkt, zu dem der Task abgeschlossen wurde, in Unix-Millisekunden. Der Wert ist 0, bis der Task abgeschlossen ist.
Name
expires_at
Type
timestamp
Description
Zeitpunkt, zu dem die Ergebnisdateien des Tasks ablaufen, in Unix-Millisekunden. Der Wert ist 0, bis der Task abgeschlossen ist. Meshy speichert den Clip 3 Tage nach Abschluss des Tasks, laden Sie ihn also rechtzeitig herunter.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der Tasks, die in der Warteschlange vor diesem liegen. Der Wert ist nur aussagekräftig, solange der Task den Status PENDING hat. Das Feld wird weggelassen, wenn der Wert 0 ist.
Name
consumed_credits
Type
integer
Description
Die Anzahl der vom Task verbrauchten Credits, 10 für den prime-mode oder 3 für den swift-mode. Bei einem FAILED-Task ist der Wert 0, da Meshy die Credits erstattet, wenn ein Task fehlschlägt.
Name
task_error
Type
object
Description
Die Fehlerdetails, wenn der Task fehlschlägt, andernfalls null. Siehe Fehler.
Name
result
Type
object
Description
Der generierte Motion-Clip, sobald der Task erfolgreich abgeschlossen wurde. Bis dahin sind die Felder vorhanden, aber leer ("" oder 0).
- Name
  motion_url
  Type
  string
  Description
  Download-URL für den Motion-Clip. Meshy signiert die URL bei jedem Lesevorgang neu, und sie läuft mit dem Aufbewahrungszeitraum des Tasks ab.
- Name
  motion_format
  Type
  string
  Description
  Das Dateiformat des Clips, fbx für den prime-mode oder bvh für den swift-mode.
- Name
  duration_ms
  Type
  integer
  Description
  Die Länge des Clips, in Millisekunden.
- Name
  mode
  Type
  string
  Description
  Der von Meshy zur Generierung des Clips verwendete mode, prime oder swift.