Tekst naar Beweging API

Genereer bewegingsclips voor personages op basis van beschrijvingen in natuurlijke taal. Beschrijf een actie — "een personage dat zwaait", "een zombie die naar voren strompelt" — en ontvang een ruwe bewegingsclip die je kunt retargeten naar geriggede personages in je eigen pipeline of DCC-tools.

De output is een op zichzelf staande bewegingsclip: er is geen personagemodel voor nodig en de clip is er ook niet aan gekoppeld. Zie eerst de Rigging API om een personage te riggen. Om een gegenereerde clip toe te passen op je geriggede personage, geef je de taak-id door als motion_task_id aan de Animatie API — pas dit toe binnen het asset-retentievenster van 3 dagen.

POST/openapi/v1/text-to-motion

Een Text to Motion-taak aanmaken

Deze endpoint maakt een nieuwe taak aan om een motion clip te genereren op basis van een tekstprompt.

Een taak met mode prime kost 10 credits en genereert met ons hoogwaardigste motion-model. Een taak met mode swift kost 3 credits en genereert sneller met ons economische motion-model.

Parameters

Name
prompt
Type
string
Verplicht
Description
Een beschrijving in natuurlijke taal van de te genereren beweging. Maximaal 400 tekens.
Name
mode
Type
string
standaard prime
Description
De mode voor het genereren van beweging. Beschikbare waarden: prime, swift. prime levert de hoogste kwaliteit en geeft FBX als uitvoer; swift is sneller en goedkoper en geeft BVH als uitvoer.
Name
duration
Type
number
Verplicht
Description
De beoogde duur van de motion clip in seconden. Tussen 2 en 10, in stappen van 0.5 (bijvoorbeeld 2, 2.5, 3, … 10).

Retourwaarden

De eigenschap result van de response bevat het task-id van de zojuist aangemaakte Text to Motion-taak.

Faalmodi

Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
- Ontbrekende of lege prompt: prompt ontbreekt, is leeg, of is langer dan 400 tekens.
- Ongeldige mode: mode is niet prime of swift.
- Ongeldige duration: duration ontbreekt, valt buiten 2–10, of zit niet op een stap van 0.5 seconde.
Name
401 - Unauthorized
Description
Authenticatie is mislukt. Controleer uw API-sleutel.
Name
402 - Payment Required
Description
Onvoldoende credits om deze taak uit te voeren.
Name
403 - Forbidden
Description
De prompt is gemarkeerd door contentmoderation.
Name
429 - Too Many Requests
Description
U heeft uw rate limit overschreden.

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

Een Text to Motion-taak ophalen

Met deze endpoint kunt u een Text to Motion-taak ophalen op basis van een geldig taak-id. Raadpleeg The Text to Motion Task Object om te zien welke eigenschappen worden opgenomen.

Parameters

Name
id
Type
path
Description
Unieke identificatie voor de Text to Motion-taak die moet worden opgehaald.

Retourwaarden

De respons bevat het Text to Motion Task-object. Raadpleeg de sectie The Text to Motion Task Object voor meer details.

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

Lijst met Text to Motion-taken opvragen

Retourneert een gepagineerde lijst van de Text to Motion-taken van de aanroeper, nieuwste eerst. Standaard paginering via page_num en page_size.

De respons is een array van Text to Motion Task-objecten.

Merk op dat taken die via de API zijn aangemaakt, ook via de API worden beheerd — ze verschijnen niet in Mijn Assets van de web-app. Gebruik deze endpoint om een taak te vinden waarvan je de ID niet meer hebt.

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 een Text to Motion-taak

Deze endpoint streamt realtime updates voor een Text to Motion-taak met behulp van Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unieke identifier voor de te streamen Text to Motion-taak.

Retourneert

Retourneert een stream van The Text to Motion Task Objects als Server-Sent Events.

Elk message-event bevat het volledige taakobject. Zolang de taak PENDING of IN_PROGRESS is, blijven de result-velden leeg ("" / 0) en zijn finished_at / expires_at gelijk aan 0; let op status en 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

Delete a Text to Motion Task

Dit endpoint verwijdert een Text to Motion-taak permanent, inclusief de gegenereerde motion clip. Deze actie is onomkeerbaar.

Padparameters

Name
id
Type
path
Description
De ID van de Text to Motion-taak die verwijderd moet worden.

Taakstatus

Een taak die nog PENDING is, wordt verwijderd en de credits die bij het aanmaken zijn verbruikt, worden terugbetaald.

Een taak die al IN_PROGRESS is, kan niet worden verwijderd: het verzoek wordt geweigerd met 409 Conflict en de taak blijft doorlopen. Credits voor een taak waar de worker al aan is begonnen, zijn niet terugbetaalbaar, dus het tussentijds verwijderen ervan zou u zowel de credits als het resultaat kosten. Wacht tot de taak SUCCEEDED, FAILED of CANCELED bereikt en verwijder deze dan.

Een taak in een eindstatus (SUCCEEDED, FAILED of CANCELED) wordt verwijderd zonder terugbetaling.

Retourwaarden

Retourneert 200 OK bij succes, of 409 Conflict wanneer de taak IN_PROGRESS is.

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

Het Text to Motion Taakobject

Het Text to Motion Taakobject vertegenwoordigt de werkeenheid voor het genereren van een bewegingsclip op basis van een tekstprompt.

Eigenschappen

Name
id
Type
string
Description
Unieke identificatie voor de taak.
Name
type
Type
string
Description
Type van de taak. De waarde is text-to-motion.
Name
status
Type
string
Description
Status van de taak. Mogelijke waarden: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress van de taak (0-100).
Name
created_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) van het moment waarop de taak is aangemaakt.
Een tijdstempel geeft het aantal milliseconden weer dat is verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339-standaard. Vrijdag 1 september 2023 12:00:00 PM GMT wordt bijvoorbeeld weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in Meshy API.
Name
started_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) van het moment waarop de taak begon te verwerken. 0 als deze nog niet is gestart.
Name
finished_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) van het moment waarop de taak is voltooid. 0 als deze nog niet is voltooid.
Name
expires_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) waarop de resultaatassets van de taak verlopen. 0 totdat de taak is voltooid. De gegenereerde clip wordt 3 dagen na voltooiing van de taak bewaard; download deze voordat hij verloopt.
Name
preceding_tasks
Type
integer
Description
Het aantal voorgaande taken in de wachtrij. Alleen relevant wanneer de status PENDING is; wordt weggelaten wanneer de waarde nul is.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat door deze taak is verbruikt. 10 voor de prime-mode, 3 voor de swift-mode. Geeft 0 terug voor FAILED-taken (credits worden terugbetaald bij een mislukking).
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken; null tenzij de taak FAILED is. Zie Fouten voor de volledige referentie van het task_error-object.
Name
result
Type
object
Description
Bevat de gegenereerde bewegingsclip zodra de taak SUCCEEDED is; tot dan zijn de velden aanwezig maar leeg ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Downloadbare URL voor de gegenereerde bewegingsclip. De URL wordt bij elke lezing opnieuw ondertekend en verloopt binnen het retentievenster van de taak.
- Name
  motion_format
  Type
  string
  Description
  Bestandsformaat van de clip: fbx voor de prime-mode, bvh voor de swift-mode.
- Name
  duration_ms
  Type
  integer
  Description
  Duur van de gegenereerde clip in milliseconden.
- Name
  mode
  Type
  string
  Description
  De mode waarmee de clip is gegenereerd: prime of 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
}