Text to Motion API

Generuj klipy ruchu postaci na podstawie opisów tekstowych. Opisz akcję, taką jak „postać machająca ręką” lub „zombie powłóczące się do przodu”, i uzyskaj surowy klip ruchu. Możesz dopasować klip do postaci z riggiem we własnym pipeline lub narzędziach DCC.

Wynik to samodzielny klip ruchu. Nie wymaga modelu postaci ani nie jest do niego przypisany. Aby najpierw wykonać rigging postaci, zobacz Rigging API. Aby zastosować klip do postaci z riggiem, wyślij id zadania jako motion_task_id do Animation API.

POST/openapi/v1/text-to-motion

Utwórz zadanie Text to Motion

Tworzy zadanie Text to Motion, które generuje klip ruchu na podstawie promptu tekstowego.

Zadanie jest wykonywane w tle. Informacje o tym, ile zwykle trwa zadanie, znajdziesz w Czasach przetwarzania.

Zadanie prime kosztuje 10 kredytów i wykorzystuje wyższej jakości model ruchu Meshy. Zadanie swift kosztuje 3 kredyty i wykorzystuje szybszy, tańszy model ruchu.

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

Parametry

Name
prompt
Type
string
Wymagane
Description
Tekst opisujący ruch do wygenerowania, do 400 znaków. Dłuższy tekst zwraca 400.
Name
mode
Type
string
domyślne prime
Description
Model ruchu, który określa również format pliku klipu.
Dostępne wartości:
- prime: wyższa jakość, zwraca klip FBX
- swift: szybszy i tańszy, zwraca klip BVH
Każda inna wartość zwraca 400.
Name
duration
Type
number
Wymagane
Description
Docelowa długość klipu w sekundach, od 2 do 10 w krokach co 0.5, na przykład 2, 2.5 lub 3. Każda inna wartość zwraca 400.

Zwraca

Pole result odpowiedzi zawiera ID nowego zadania Text to Motion.

Tryby błędów

Name
400 - Bad Request
Description
Żądanie nie może zostać wykonane. Komunikat błędu wskazuje, jaki problem został wykryty. Na przykład:
- Brakujący lub pusty prompt: prompt jest brakujący, pusty lub dłuższy niż 400 znaków.
- Nieprawidłowy mode: mode nie jest prime ani swift.
- Nieprawidłowy czas trwania: duration jest brakujący, znajduje się poza zakresem od 2 do 10 lub nie jest zgodny z krokiem 0.5 sekundy.
Popraw żądanie, a następnie wyślij je ponownie. Zobacz Błędy.
Name
401 - Unauthorized
Description
Brak klucza API lub klucz API jest nieprawidłowy. Sprawdź nagłówek Authorization.
Name
402 - Payment Required
Description
Na przykład:
- Niewystarczające kredyty: Konto nie ma wystarczającej liczby kredytów na to zadanie lub konto osiągnęło limit kredytów. Sprawdź saldo kredytów, a następnie spróbuj ponownie.
- Plan darmowy: Utworzenie zadania wymaga płatnego planu. Uaktualnij swój plan w ustawieniach subskrypcji, a następnie spróbuj ponownie.
Name
403 - Forbidden
Description
Moderacja treści oznaczyła prompt. Zmień prompt, a następnie wyślij żądanie ponownie.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości. Odczekaj, a następnie spróbuj ponownie. Zobacz Limity szybkości.

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

Pobierz zadanie Text to Motion

Zwraca zadanie Text to Motion na podstawie jego 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
}

Parametry

Name
id
Type
path
Description
ID zadania z odpowiedzi tworzenia.

Zwraca

Obiekt zadania Text to Motion.

GET/openapi/v1/text-to-motion

Lista zadań Text to Motion

Zwraca stronicowaną listę Twoich zadań Text to Motion, od najnowszych. Aby przeglądać listę strona po stronie, użyj page_num i page_size.

Odpowiedź jest tablicą obiektów zadań Text to Motion.

Zadania utworzone za pomocą API pozostają w API i nie pojawiają się w My Assets w aplikacji webowej. Aby znaleźć zadanie, którego identyfikatora już nie posiadasz, użyj tego punktu końcowego.

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

Przesyłaj strumieniowo zadanie Text to Motion

Przesyła strumieniowo aktualizacje zadania Text to Motion jako 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
}

Parametry

Name
id
Type
path
Description
ID zadania z odpowiedzi tworzącej zadanie.

Zwraca

Strumień obiektów zadania Text to Motion jako Server-Sent Events.

Każde zdarzenie message zawiera pełny obiekt zadania. Dopóki zadanie ma status PENDING lub IN_PROGRESS, pola result są puste ("" lub 0), a finished_at i expires_at wynoszą 0. Aby śledzić postęp zadania, obserwuj status i progress.

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

Usunięcie zadania Text to Motion

Trwale usuwa zadanie Text to Motion, w tym jego klip ruchu. Nie można cofnąć usunięcia.

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

Parametry ścieżki

Name
id
Type
path
Description
ID zadania do usunięcia.

Status zadania

Usunięcie zadania o statusie PENDING zwraca kredyty wykorzystane podczas jego tworzenia.

Zadania o statusie IN_PROGRESS nie można usunąć. Żądanie zwraca 409 Conflict, a zadanie nadal się wykonuje. Meshy nie zwraca kredytów za zadanie, które już się rozpoczęło, więc usunięcie go kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Usunięcie zadania w statusie końcowym (SUCCEEDED, FAILED lub CANCELED) nie zwraca jego kredytów.

Zwraca

200 OK, gdy zadanie zostało usunięte, lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

Obiekt zadania Text to Motion

Obiekt zadania Text to Motion opisuje generowanie jednego klipu ruchu. Zawiera status, progress oraz klip, gdy zadanie zakończy się sukcesem.

Właściwości

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
Identyfikator zadania. Traktuj go jako nieprzejrzysty ciąg znaków i nie polegaj na jego formacie.
Name
type
Type
string
Description
Typ zadania, zawsze text-to-motion.
Name
status
Type
string
Description
Status zadania, jeden z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED lub CANCELED.
Name
progress
Type
integer
Description
Ile zadania zostało wykonane, jako wartość procentowa od 0 do 100.
Name
created_at
Type
timestamp
Description
Czas utworzenia zadania, w milisekundach Unix.
Name
started_at
Type
timestamp
Description
Czas rozpoczęcia zadania, w milisekundach Unix. Wynosi 0, dopóki zadanie się nie rozpocznie.
Name
finished_at
Type
timestamp
Description
Czas zakończenia zadania, w milisekundach Unix. Wynosi 0, dopóki zadanie się nie zakończy.
Name
expires_at
Type
timestamp
Description
Czas wygaśnięcia plików wynikowych zadania, w milisekundach Unix. Wynosi 0, dopóki zadanie się nie zakończy. Meshy przechowuje klip przez 3 dni po zakończeniu zadania, więc pobierz go przed upływem tego czasu.
Name
preceding_tasks
Type
integer
Description
Liczba zadań znajdujących się przed tym zadaniem w kolejce. Wartość ta ma znaczenie tylko wtedy, gdy zadanie ma status PENDING. Pole jest pomijane, gdy wartość wynosi 0.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez zadanie, 10 dla trybu prime lub 3 dla trybu swift. Dla zadania FAILED wynosi 0, ponieważ Meshy zwraca kredyty w przypadku niepowodzenia zadania.
Name
task_error
Type
object
Description
Szczegóły błędu, gdy zadanie zakończy się niepowodzeniem, w przeciwnym razie null. Zobacz Błędy.
Name
result
Type
object
Description
Wygenerowany klip ruchu, gdy zadanie zakończy się sukcesem. Do tego czasu pola są obecne, ale puste ("" lub 0).
- Name
  motion_url
  Type
  string
  Description
  Adres URL do pobrania klipu ruchu. Meshy podpisuje adres URL ponownie przy każdym odczycie, a jego ważność wygasa wraz z oknem przechowywania zadania.
- Name
  motion_format
  Type
  string
  Description
  Format pliku klipu, fbx dla trybu prime lub bvh dla trybu swift.
- Name
  duration_ms
  Type
  integer
  Description
  Długość klipu, w milisekundach.
- Name
  mode
  Type
  string
  Description
  Tryb, którego Meshy użyło do wygenerowania klipu, prime lub swift.