Text to Motion API

Genereer bewegingsclips van personages op basis van tekstbeschrijvingen. Beschrijf een actie, zoals "een personage dat zwaait" of "een zombie die naar voren sjokt", en ontvang een ruwe bewegingsclip. Je kunt de clip retargeten naar geriggede personages in je eigen pipeline of DCC-tools.

De uitvoer is een op zichzelf staande bewegingsclip. Er is geen personagemodel voor nodig en de clip is niet aan een model gekoppeld. Om eerst een personage te riggen, zie de Rigging API. Om een clip toe te passen op je geriggede personage, stuur de taak-id als motion_task_id naar de Animatie API.

POST/openapi/v1/text-to-motion

Een Text to Motion-taak maken

Maakt een Text to Motion-taak aan, die een bewegingsclip genereert op basis van een tekstprompt.

De taak wordt op de achtergrond uitgevoerd. Zie Verwerkingstijden voor hoe lang een taak gewoonlijk duurt.

Een prime-taak kost 10 credits en gebruikt Meshy's hoogwaardigere motion-model. Een swift-taak kost 3 credits en gebruikt een sneller, goedkoper motion-model.

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

Parameters

Name
prompt
Type
string
Verplicht
Description
Tekst die de te genereren beweging beschrijft, tot 400 tekens. Langere tekst retourneert 400.
Name
mode
Type
string
standaard prime
Description
Het motion-model, dat ook het bestandsformaat van de clip bepaalt.
Beschikbare waarden:
- prime: hogere kwaliteit, retourneert een FBX-clip
- swift: sneller en goedkoper, retourneert een BVH-clip
Elke andere waarde retourneert 400.
Name
duration
Type
number
Verplicht
Description
De beoogde cliplengte in seconden, van 2 tot 10 in stappen van 0.5, bijvoorbeeld 2, 2.5 of 3. Elke andere waarde retourneert 400.

Retourwaarden

Het veld result van de respons bevat de ID van de nieuwe Text to Motion-taak.

Faalscenario's

Name
400 - Bad Request
Description
Het verzoek kan niet worden uitgevoerd. Het foutbericht geeft aan welk probleem er is gevonden. Bijvoorbeeld:
- 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 het bereik 2 tot 10, of staat niet op een stap van 0.5 seconde.
Corrigeer het verzoek en verstuur het opnieuw. Zie Fouten.
Name
401 - Unauthorized
Description
De API-sleutel ontbreekt of is ongeldig. Controleer de Authorization-header.
Name
402 - Payment Required
Description
Bijvoorbeeld:
- Onvoldoende credits: Het account heeft niet genoeg credits voor deze taak, of het account heeft een credietlimiet bereikt. Controleer uw credit saldo en probeer het opnieuw.
- Gratis abonnement: Voor het aanmaken van een taak is een betaald abonnement vereist. Upgrade uw abonnement in uw abonnementsinstellingen en probeer het opnieuw.
Name
403 - Forbidden
Description
Content moderation heeft de prompt gemarkeerd. Wijzig de prompt en verstuur het verzoek opnieuw.
Name
429 - Too Many Requests
Description
U heeft uw rate limit overschreden. Wacht en probeer het opnieuw. Zie Rate limits.

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

Haal een Text to Motion-taak op

Retourneert een Text to Motion-taak op basis van de ID.

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
}

Parameters

Name
id
Type
path
Description
De taak-ID uit de respons van het aanmaken.

Returns

Het Text to Motion-taakobject.

GET/openapi/v1/text-to-motion

Lijst van Text to Motion-taken opvragen

Geeft een gepagineerde lijst van uw Text to Motion-taken terug, nieuwste eerst. Gebruik page_num en page_size om door de lijst te bladeren.

Het antwoord is een array van Text to Motion-taakobjecten.

Taken die u met de API aanmaakt, blijven in de API en verschijnen niet onder My Assets in de web-app. Gebruik dit endpoint om een taak te vinden waarvan u de ID niet meer heeft.

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

Streamt de updates van een Text to Motion-taak 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
}

Parameters

Name
id
Type
path
Description
De taak-ID uit de create-respons.

Retourwaarden

Een stroom van Text to Motion-taakobjecten als Server-Sent Events.

Elke message-event bevat het volledige taakobject. Zolang de taak PENDING of IN_PROGRESS is, zijn de result-velden leeg ("" of 0), en zijn finished_at en expires_at 0. Om de taak te volgen, let op status en progress.

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

Een Text to Motion-taak verwijderen

Verwijdert een Text to Motion-taak permanent, inclusief de bijbehorende motion clip. Je kunt een verwijdering niet ongedaan maken.

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

Padparameters

Name
id
Type
path
Description
De ID van de te verwijderen taak.

Taakstatus

Het verwijderen van een PENDING-taak vergoedt de credits die zijn gebruikt bij het aanmaken ervan.

Een IN_PROGRESS-taak kan niet worden verwijderd. Het verzoek geeft 409 Conflict terug, en de taak blijft actief. Meshy vergoedt geen taak die al is gestart, dus het verwijderen ervan zou je zowel de credits als het resultaat kosten. Wacht tot deze de status SUCCEEDED, FAILED of CANCELED bereikt en verwijder de taak dan.

Het verwijderen van een taak met een definitieve status (SUCCEEDED, FAILED of CANCELED) vergoedt de credits niet.

Resultaten

200 OK wanneer de taak is verwijderd, of 409 Conflict wanneer de taak IN_PROGRESS is.

Het Text to Motion-taakobject

Een Text to Motion-taakobject beschrijft het genereren van één bewegingsclip. Het bevat de status, de progress en de clip wanneer de taak slaagt.

Eigenschappen

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
De taak-ID. Behandel dit als een ondoorzichtige string en vertrouw niet op het formaat ervan.
Name
type
Type
string
Description
Het taaktype, altijd text-to-motion.
Name
status
Type
string
Description
De taakstatus, een van PENDING, IN_PROGRESS, SUCCEEDED, FAILED of CANCELED.
Name
progress
Type
integer
Description
Hoeveel van de taak is voltooid, als een percentage van 0 tot 100.
Name
created_at
Type
timestamp
Description
Tijdstip waarop de taak is aangemaakt, in Unix-milliseconden.
Name
started_at
Type
timestamp
Description
Tijdstip waarop de taak is gestart, in Unix-milliseconden. Dit is 0 totdat de taak start.
Name
finished_at
Type
timestamp
Description
Tijdstip waarop de taak is voltooid, in Unix-milliseconden. Dit is 0 totdat de taak is voltooid.
Name
expires_at
Type
timestamp
Description
Tijdstip waarop de resultaatbestanden van de taak verlopen, in Unix-milliseconden. Dit is 0 totdat de taak is voltooid. Meshy bewaart de clip gedurende 3 dagen nadat de taak is voltooid, dus download deze vóór die tijd.
Name
preceding_tasks
Type
integer
Description
Het aantal taken dat vóór deze taak in de wachtrij staat. Deze waarde is alleen relevant terwijl de taak PENDING is. Dit veld wordt weggelaten wanneer de waarde 0 is.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat de taak heeft gebruikt, 10 voor prime-mode of 3 voor swift-mode. Dit is 0 voor een FAILED-taak, omdat Meshy de credits terugbetaalt wanneer een taak mislukt.
Name
task_error
Type
object
Description
De foutdetails wanneer de taak mislukt, en anders null. Zie Fouten.
Name
result
Type
object
Description
De gegenereerde bewegingsclip wanneer de taak slaagt. Tot die tijd zijn de velden aanwezig maar leeg ("" of 0).
- Name
  motion_url
  Type
  string
  Description
  Download-URL voor de bewegingsclip. Meshy ondertekent de URL opnieuw bij elke leesactie, en deze verloopt met het retentievenster van de taak.
- Name
  motion_format
  Type
  string
  Description
  Het bestandsformaat van de clip, fbx voor prime-mode of bvh voor swift-mode.
- Name
  duration_ms
  Type
  integer
  Description
  De lengte van de clip, in milliseconden.
- Name
  mode
  Type
  string
  Description
  De mode die Meshy heeft gebruikt om de clip te genereren, prime of swift.