Tekst naar Beweging API

Genereer karakterbewegingclips vanuit beschrijvingen in natuurlijke taal. Beschrijf een actie — "een karakter dat zwaait", "een zombie die naar voren sjokt" — en ontvang een ruwe bewegingclip die je kunt hergebruiken op rigged karakters in je eigen pipeline of DCC-tools.

De output is een zelfstandige bewegingclip: het vereist geen en is niet gekoppeld aan een karaktermal. Om eerst een karakter te riggen, zie de Rigging API.

POST/openapi/v1/text-to-motion

Maak een Tekst naar Beweging Taak

Deze endpoint creëert een nieuwe taak om een bewegingsclip te genereren vanuit een tekstprompt.

Een taak met mode prime kost 10 credits en genereert met ons hoogst kwalitatieve bewegingsmodel. Een taak met mode swift kost 3 credits en genereert sneller met ons economische bewegingsmodel.

Parameters

Name
prompt
Type
string
Verplicht
Description
Een omschrijving in natuurlijke taal van de te genereren beweging. Maximaal 400 tekens.
Name
mode
Type
string
standaard prime
Description
De bewegingsgeneratiemodus. Beschikbare waarden: prime, swift. prime produceert de hoogste kwaliteit en levert FBX op; swift is sneller en goedkoper en levert BVH op.
Name
duration
Type
number
Verplicht
Description
De gewenste duur van de bewegingsclip in seconden. Tussen 2 en 10, in stappen van 0.5 (bijvoorbeeld 2, 2.5, 3, … 10).

Retourneert

De result-eigenschap van het antwoord bevat de taak id van de nieuw gecreëerde Tekst naar Beweging taak.

Foutmodi

Name
400 - Bad Request
Description
Het verzoek was onacceptabel. Veelvoorkomende oorzaken:
- Ontbrekende of lege prompt: prompt ontbreekt, is leeg of langer dan 400 tekens.
- Ongeldige mode: mode is niet prime of swift.
- Ongeldige duur: duration ontbreekt, ligt buiten 2–10, of is niet in een 0.5 seconde stap.
Name
401 - Unauthorized
Description
Authenticatie 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 door content moderation gemarkeerd.
Name
429 - Too Many Requests
Description
U heeft uw rate limit overschreden.

Verzoek

POST

/openapi/v1/text-to-motion

# Genereer een bewegingsclip met alleen verplichte parameters
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
  }'

# Genereer een snelle, economische clip met 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

Ophalen van een Text to Motion-taak

Deze endpoint stelt je in staat om een Text to Motion-taak op te halen met een geldig taak id. Raadpleeg Het Text to Motion-taakobject om te zien welke eigenschappen zijn opgenomen.

Parameters

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

Retourneert

De reactie bevat het Text to Motion-taakobject. Bekijk de sectie Het Text to Motion-taakobject voor details.

Aanvraag

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

Reactie

{
  "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 Tekst-naar-Motion Taken

Geeft een gepagineerde lijst terug van de Tekst-naar-Motion-taken van de beller, van nieuw naar oud. Standaard paginering via page_num en page_size.

Het antwoord is een array van Tekst-naar-Motion-taakobjecten.

Let op dat taken die via de API zijn aangemaakt, via de API worden beheerd — ze verschijnen niet in de web-app Mijn Assets. Gebruik deze endpoint om een taak te vinden waarvan je het 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 Tekst naar Beweging Taak

Deze endpoint streamt real-time updates voor een Tekst naar Beweging taak met behulp van Server-Sent Events (SSE).

Parameters

Name
id
Type
path
Description
Unieke identificatie voor de Tekst naar Beweging taak om te streamen.

Retourneert

Retourneert een stream van De Tekst naar Beweging Taakobjecten als Server-Sent Events.

Elk message evenement draagt het volledige taakobject. Terwijl de taak PENDING of IN_PROGRESS is, zijn de resultaat velden nog leeg ("" / 0) en finished_at / expires_at zijn 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 voorbeeld
event: error
data: {
  "status_code": 404,
  "message": "Taak niet gevonden"
}

// Message events dragen het volledige taakobject op elk stadium; de resultaat
// velden blijven leeg totdat de taak slaagt.
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: { // Voorbeeld van een SUCCEEDED taakstream item, dat de structuur van het Tekst naar Beweging Taakobject spiegelt
  "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

Een Text naar Motion Taak Verwijderen

Deze endpoint verwijdert permanent een Text naar Motion taak, inclusief de gegenereerde bewegingsclip. Deze actie is onomkeerbaar.

Pad Parameters

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

Retourneert

Retourneert 200 OK bij succes.

Verzoek

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

Antwoord

// Retourneert 200 Ok bij succes.

Het Text to Motion Task Object

Het Text to Motion Task object vertegenwoordigt de werkunit voor het genereren van een bewegingsclip vanuit 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
Voortgang van de taak (0-100).
Name
created_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) wanneer de taak is aangemaakt.
Een tijdstempel vertegenwoordigt het aantal milliseconden dat is verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339 standaard. Bijvoorbeeld, vrijdag 1 september 2023 12:00:00 PM GMT wordt weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in de Meshy API.
Name
started_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) wanneer de taak begon met verwerken. 0 indien niet begonnen.
Name
finished_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) wanneer de taak is voltooid. 0 indien niet voltooid.
Name
expires_at
Type
timestamp
Description
Tijdstempel (milliseconden sinds epoch) wanneer de taakresultaten assets verlopen. 0 totdat de taak is voltooid. De gegenereerde clip wordt 3 dagen bewaard na het voltooien van de taak; download het voordat het verloopt.
Name
preceding_tasks
Type
integer
Description
Het aantal voorgaande taken in de wachtrij. Alleen relevant als de status PENDING is; weggelaten wanneer nul.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat door deze taak is verbruikt. 10 voor prime mode, 3 voor swift mode. Geeft 0 terug voor FAILED taken (credits worden teruggestort bij een mislukking).
Name
task_error
Type
object
Description
Foutdetails voor mislukte taken; null tenzij de taak FAILED. Zie Fouten voor de volledige task_error objectreferentie.
Name
result
Type
object
Description
Bevat de gegenereerde bewegingsclip zodra de taak SUCCEEDED; tot die tijd 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 met het bewaartermijn van de taak.
- Name
  motion_format
  Type
  string
  Description
  Bestandsformaat van de clip: fbx voor prime mode, bvh voor 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.

Voorbeeld van een 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
}