Text to Motion API

Generuj klipy ruchu postaci na podstawie opisów w języku naturalnym. Opisz czynność — „postać machająca ręką”, „zombie powłóczące się do przodu” — i otrzymaj surowy klip ruchu, który możesz retargetować na postacie z rigiem, korzystając z własnego pipeline'u lub narzędzi DCC.

Wynikiem jest samodzielny klip ruchu: nie wymaga on modelu postaci ani nie jest z nim powiązany. Aby najpierw wykonać rigging postaci, zobacz Rigging API. Aby zastosować wygenerowany klip na swojej postaci z rigiem, przekaż id zadania jako motion_task_id do Animacja API — zastosuj go w ciągu okna przechowywania zasobów wynoszącego 3 dni.

POST/openapi/v1/text-to-motion

Utwórz zadanie Text to Motion

Ten punkt końcowy tworzy nowe zadanie generowania klipu ruchu na podstawie promptu tekstowego.

Zadanie z mode prime kosztuje 10 kredytów i generuje wynik przy użyciu naszego najwyższej jakości modelu ruchu. Zadanie z mode swift kosztuje 3 kredyty i generuje wynik szybciej, korzystając z naszego ekonomicznego modelu ruchu.

Parametry

Name
prompt
Type
string
Wymagane
Description
Opis ruchu do wygenerowania w języku naturalnym. Maksymalnie 400 znaków.
Name
mode
Type
string
domyślne prime
Description
Mode generowania ruchu. Dostępne wartości: prime, swift. prime zapewnia najwyższą jakość i generuje wyjście w formacie FBX; swift jest szybszy i tańszy, a generuje wyjście w formacie BVH.
Name
duration
Type
number
Wymagane
Description
Docelowy czas trwania klipu ruchu w sekundach. Od 2 do 10, z krokiem 0.5 (na przykład 2, 2.5, 3, … 10).

Wartość zwracana

Właściwość result odpowiedzi zawiera id zadania nowo utworzonego zadania Text to Motion.

Przypadki niepowodzenia

Name
400 - Bad Request
Description
Żądanie było niedopuszczalne. Najczęstsze przyczyny:
- Brakujący lub pusty prompt: prompt jest brakujący, pusty lub dłuższy niż 400 znaków.
- Nieprawidłowy mode: mode nie ma wartości prime ani swift.
- Nieprawidłowy czas trwania: duration jest brakujący, znajduje się poza zakresem 2–10 lub nie jest wielokrotnością 0.5 sekundy.
Name
401 - Unauthorized
Description
Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.
Name
402 - Payment Required
Description
Niewystarczająca liczba kredytów do wykonania tego zadania.
Name
403 - Forbidden
Description
Prompt został oznaczony przez moderation treści.
Name
429 - Too Many Requests
Description
Przekroczono limit szybkości.

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

Pobierz zadanie Text to Motion

Ten punkt końcowy umożliwia pobranie zadania Text to Motion na podstawie prawidłowego id zadania. Zapoznaj się z sekcją Obiekt zadania Text to Motion, aby zobaczyć, jakie właściwości są uwzględnione.

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania Text to Motion do pobrania.

Zwraca

Odpowiedź zawiera obiekt zadania Text to Motion. Szczegóły znajdziesz w sekcji Obiekt zadania Text to Motion.

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

Lista zadań Text to Motion

Zwraca stronicowaną listę zadań Text to Motion wywołującego, od najnowszych do najstarszych. Standardowe stronicowanie za pomocą page_num i page_size.

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

Zwróć uwagę, że zadania utworzone za pomocą API są zarządzane przez API — nie są wyświetlane w sekcji Moje zasoby aplikacji webowej. Użyj tego punktu końcowego, aby znaleźć zadanie, którego identyfikator już nie masz.

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

Ten punkt końcowy przesyła strumieniowo aktualizacje w czasie rzeczywistym dla zadania Text to Motion przy użyciu Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zadania Text to Motion do przesyłania strumieniowego.

Zwraca

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

Każde zdarzenie message zawiera pełny obiekt zadania. Gdy zadanie ma status PENDING lub IN_PROGRESS, pola result są nadal puste ("" / 0), a finished_at / expires_at mają wartość 0; obserwuj status i 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

Usuwanie zadania Text to Motion

Ten punkt końcowy trwale usuwa zadanie Text to Motion, wraz z wygenerowanym klipem ruchu. Ta operacja jest nieodwracalna.

Parametry ścieżki

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

Status zadania

Zadanie, które nadal ma status PENDING, jest usuwane, a kredyty zużyte w momencie utworzenia są zwracane.

Zadanie, które ma już status IN_PROGRESS, nie może zostać usunięte: żądanie zostaje odrzucone z kodem 409 Conflict, a zadanie nadal działa. Kredyty za zadanie, które worker już zaczął przetwarzać, nie podlegają zwrotowi, więc usunięcie go w trakcie działania kosztowałoby Cię zarówno kredyty, jak i wynik. Poczekaj, aż osiągnie status SUCCEEDED, FAILED lub CANCELED, a następnie je usuń.

Zadanie w stanie końcowym (SUCCEEDED, FAILED lub CANCELED) jest usuwane bez zwrotu kredytów.

Zwraca

Zwraca 200 OK w przypadku powodzenia lub 409 Conflict, gdy zadanie ma status IN_PROGRESS.

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

Obiekt zadania Text to Motion

Obiekt zadania Text to Motion reprezentuje jednostkę pracy służącą do generowania klipu ruchu na podstawie promptu tekstowego.

Właściwości

Name
id
Type
string
Description
Unikalny identyfikator zadania.
Name
type
Type
string
Description
Typ zadania. Wartość to text-to-motion.
Name
status
Type
string
Description
Status zadania. Możliwe wartości: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Postęp zadania (0–100).
Name
created_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) utworzenia zadania.
Znacznik czasu przedstawia liczbę milisekund, które upłynęły od 1 stycznia 1970 UTC, zgodnie z normą RFC 3339. Na przykład piątek, 1 września 2023, 12:00:00 czasu GMT jest reprezentowany jako 1693569600000. Dotyczy to wszystkich znaczników czasu w Meshy API.
Name
started_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) rozpoczęcia przetwarzania zadania. 0, jeśli nie rozpoczęto.
Name
finished_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki) zakończenia zadania. 0, jeśli nie zakończono.
Name
expires_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki), kiedy wygasają zasoby będące wynikiem zadania. 0 do momentu zakończenia zadania. Wygenerowany klip jest przechowywany przez 3 dni po zakończeniu zadania; pobierz go, zanim wygaśnie.
Name
preceding_tasks
Type
integer
Description
Liczba poprzedzających zadań w kolejce. Ma znaczenie tylko wtedy, gdy status to PENDING; pomijane, gdy wynosi zero.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. 10 dla mode prime, 3 dla mode swift. Dla zadań FAILED zwraca 0 (w przypadku niepowodzenia kredyty są zwracane).
Name
task_error
Type
object
Description
Szczegóły błędu dla nieudanych zadań; null, chyba że zadanie zakończy się statusem FAILED. Pełny opis obiektu task_error znajdziesz w sekcji Błędy.
Name
result
Type
object
Description
Zawiera wygenerowany klip ruchu po zakończeniu zadania statusem SUCCEEDED; do tego momentu pola są obecne, ale puste ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Adres URL do pobrania wygenerowanego klipu ruchu. Adres URL jest ponownie podpisywany przy każdym odczycie i wygasa wraz z oknem przechowywania zadania.
- Name
  motion_format
  Type
  string
  Description
  Format pliku klipu: fbx dla mode prime, bvh dla mode swift.
- Name
  duration_ms
  Type
  integer
  Description
  Czas trwania wygenerowanego klipu w milisekundach.
- Name
  mode
  Type
  string
  Description
  Tryb, w którym wygenerowano klip: prime lub 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
}