Text-zu-Bewegung-API

Erzeugen Sie Bewegungsclips für Charaktere aus Beschreibungen in natürlicher Sprache. Beschreiben Sie eine Aktion — „ein winkender Charakter“, „ein vorwärts schlurfender Zombie“ — und erhalten Sie einen rohen Bewegungsclip, den Sie in Ihrer eigenen Pipeline oder Ihren DCC-Tools auf Charaktere mit Rig übertragen können.

Die Ausgabe ist ein eigenständiger Bewegungsclip: Er erfordert kein Charaktermodell und ist an keines gebunden. Um zunächst einen Charakter zu riggen, siehe die Rigging-API. Um einen erzeugten Clip auf Ihren Charakter mit Rig anzuwenden, übergeben Sie die Aufgaben-id als motion_task_id an die Animation-API — wenden Sie ihn innerhalb des 3-tägigen Zeitfensters für die Aufbewahrung von Assets an.

POST/openapi/v1/text-to-motion

Erstellen einer Text-to-Motion-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 wird mit unserem hochwertigsten Motion-Modell generiert. Eine Aufgabe mit mode swift kostet 3 Credits und wird schneller mit unserem sparsameren Motion-Modell generiert.

Parameter

Name
prompt
Type
string
Erforderlich
Description
Eine Beschreibung der zu generierenden Bewegung in natürlicher Sprache. Maximal 400 Zeichen.
Name
mode
Type
string
Standard prime
Description
Der mode für die Bewegungsgenerierung. 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ückgabewerte

Die Eigenschaft result der Antwort enthält die Aufgaben-id der neu erstellten Text-to-Motion-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 mode: mode ist weder prime noch swift.
- Ungültige duration: duration fehlt, liegt außerhalb von 2–10 oder entspricht nicht einem 0.5-Sekunden-Schritt.
Name
401 - Unauthorized
Description
Die Authentifizierung ist 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 von der moderation als unzulässig eingestuft.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten.

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

Eine Text-zu-Bewegung-Aufgabe abrufen

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

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der abzurufenden Text-zu-Bewegung-Aufgabe.

Rückgabewerte

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

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

Text-to-Motion-Aufgaben auflisten

Gibt eine paginierte Liste der Text-to-Motion-Aufgaben des Aufrufers zurück, die neuesten zuerst. Standard-Paginierung über page_num und page_size.

Die Antwort ist ein Array von Text-to-Motion-Task-Objekten.

Beachten Sie, dass über die API erstellte Aufgaben auch über die API verwaltet werden — sie erscheinen nicht in „Meine Assets“ der Web-App. Verwenden Sie diesen Endpunkt, um eine Aufgabe zu finden, deren ID Ihnen nicht mehr vorliegt.

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 mittels Server-Sent Events (SSE).

Parameter

Name
id
Type
path
Description
Eindeutige Kennung der zu streamenden Text-zu-Bewegung-Aufgabe.

Rückgabewerte

Gibt einen Stream von The Text to Motion Task Objects als Server-Sent Events zurück.

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

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

Eine Text-to-Motion-Aufgabe löschen

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

Pfadparameter

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

Aufgabenstatus

Eine Aufgabe, die sich noch im Status PENDING befindet, wird gelöscht, und die zum Erstellungszeitpunkt verbrauchten Credits werden erstattet.

Eine Aufgabe, die sich bereits im Status IN_PROGRESS befindet, kann nicht gelöscht werden: Die Anfrage wird mit 409 Conflict abgelehnt, und die Aufgabe läuft weiter. Credits für eine Aufgabe, die der Worker bereits gestartet hat, sind nicht erstattungsfähig. Ein Löschen während der Ausführung würde Sie also sowohl die Credits als auch das Ergebnis kosten. Warten Sie, bis sie den Status SUCCEEDED, FAILED oder CANCELED erreicht, und löschen Sie sie dann.

Eine Aufgabe in einem Endzustand (SUCCEEDED, FAILED oder CANCELED) wird ohne Erstattung gelöscht.

Rückgabewerte

Gibt bei Erfolg 200 OK zurück, oder 409 Conflict, wenn sich die Aufgabe im Status IN_PROGRESS befindet.

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

Das Text-to-Motion-Task-Objekt

Das Text-to-Motion-Task-Objekt repräsentiert die Arbeitseinheit zur Generierung eines Motion-Clips aus einem Text-prompt.

Eigenschaften

Name
id
Type
string
Description
Eindeutige Kennung für den Task.
Name
type
Type
string
Description
Typ des Tasks. Der Wert ist text-to-motion.
Name
status
Type
string
Description
Status des Tasks. Mögliche Werte: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Fortschritt des Tasks (0-100).
Name
created_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), zu dem der Task erstellt wurde.
Ein Zeitstempel stellt die Anzahl der Millisekunden dar, die seit dem 1. Januar 1970 UTC vergangen sind, gemäß dem Standard RFC 3339. Zum Beispiel wird Freitag, der 1. September 2023, 12:00:00 Uhr GMT als 1693569600000 dargestellt. Dies gilt für alle Zeitstempel in der Meshy API.
Name
started_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), zu dem die Verarbeitung des Tasks begann. 0, falls noch nicht gestartet.
Name
finished_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), zu dem der Task abgeschlossen wurde. 0, falls noch nicht abgeschlossen.
Name
expires_at
Type
timestamp
Description
Zeitstempel (Millisekunden seit der Epoche), zu dem die Ergebnis-Assets des Tasks ablaufen. 0, bis der Task abgeschlossen ist. Der generierte Clip wird 3 Tage nach Abschluss des Tasks aufbewahrt; lade ihn herunter, bevor er abläuft.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorausgehenden Tasks in der Warteschlange. Nur relevant, wenn der Status PENDING ist; wird bei einem Wert von null weggelassen.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von diesem Task verbrauchten Credits. 10 für den mode prime, 3 für den mode swift. Gibt 0 für Tasks mit Status FAILED zurück (Credits werden bei einem Fehlschlag zurückerstattet).
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Tasks; null, sofern der Task nicht FAILED ist. Siehe Fehler für die vollständige Referenz des task_error-Objekts.
Name
result
Type
object
Description
Enthält den generierten Motion-Clip, sobald der Task SUCCEEDED ist; bis dahin sind die Felder vorhanden, aber leer ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Herunterladbare URL für den generierten Motion-Clip. Die URL wird bei jedem Lesevorgang neu signiert und läuft mit dem Aufbewahrungszeitraum des Tasks ab.
- Name
  motion_format
  Type
  string
  Description
  Dateiformat des Clips: fbx für den mode prime, bvh für den mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Dauer des generierten Clips in Millisekunden.
- Name
  mode
  Type
  string
  Description
  Der mode, mit 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
}