API tekst-do-ruchu

Generuj klipy ruchu postaci na podstawie opisów w języku naturalnym. Opisz działanie — "postać machająca ręką", "zombie wlokący się naprzód" — i otrzymaj surowy klip ruchu, który możesz dostosować do postaci z rig w swoim pipeline lub narzędziach DCC.

Wynik to samodzielny klip ruchu: nie wymaga modelu postaci i nie jest z nim połączony. Aby najpierw dodać rig do postaci, zobacz API Riggowania.

POST/openapi/v1/text-to-motion

Tworzenie zadania Text to Motion

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

Zadanie z mode prime kosztuje 10 kredytów i generuje klipy z użyciem naszego najwyższej jakości modelu ruchu. Zadanie z mode swift kosztuje 3 kredyty i generuje klipy szybciej z użyciem ekonomicznego modelu ruchu.

Parametry

Name
prompt
Type
string
Wymagane
Description
Opis w języku naturalnym ruchu do wygenerowania. Maksymalnie 400 znaków.
Name
mode
Type
string
domyślne prime
Description
Tryb generowania ruchu. Dostępne wartości: prime, swift. prime produkuje najwyższą jakość i generuje FBX; swift jest szybszy i tańszy i generuje BVH.
Name
duration
Type
number
Wymagane
Description
Celowana długość klipu ruchu w sekundach. Pomiędzy 2 a 10, w krokach co 0.5 (na przykład 2, 2.5, 3, … 10).

Zwracane wartości

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

Tryby awaryjne

Name
400 - Bad Request
Description
Żądanie było nieakceptowalne. Typowe przyczyny:
- Brakujący lub pusty prompt: prompt brakuje, jest pusty lub dłuższy niż 400 znaków.
- Niepoprawny mode: mode nie jest prime ani swift.
- Niepoprawna długość: duration brakuje, jest poza zakresem 2–10 lub nie jest krokiem co 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.
Name
429 - Too Many Requests
Description
Przekroczyłeś swój limit szybkości.

Request

POST

/openapi/v1/text-to-motion

# Wygeneruj klip ruchu tylko z wymaganymi parametrami
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
  }'

# Wygeneruj szybki, ekonomiczny klip z trybem Swift
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 pozwala na pobranie zadania Text to Motion, podając prawidłowy id zadania. Odwołaj się do Obiektu zadania Text to Motion, aby zobaczyć, które właściwości są zawarte.

Parametry

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

Zwraca

Odpowiedź zawiera obiekt zadania Text to Motion. Sprawdź sekcję Obiekt zadania Text to Motion dla szczegółów.

Żądanie

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

Odpowiedź

{
  "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ń konwersji tekstu na ruch

Zwraca stronicowaną listę zadań konwersji tekstu na ruch dla wywołującego, poczynając od najnowszych. Standardowe stronicowanie za pomocą page_num i page_size.

Odpowiedź to tablica obiektów zadań konwersji tekstu na ruch.

Zauważ, że zadania utworzone za pośrednictwem API są zarządzane przez API — nie pojawiają się w sekcji Moje zasoby aplikacji webowej. Użyj tego punktu końcowego, aby znaleźć zadanie, którego ID już nie posiadasz.

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

Transmituj zadanie Text to Motion

Ten punkt końcowy transmituje aktualizacje w czasie rzeczywistym dla zadania Text to Motion za pomocą Server-Sent Events (SSE).

Parametry

Name
id
Type
path
Description
Unikalny identyfikator zlecenia Text to Motion do transmisji.

Zwraca

Zwraca strumień Obiektów Zadania Text to Motion jako Server-Sent Events.

Każde wydarzenie message przenosi pełen obiekt zadania. Podczas gdy zadanie jest PENDING lub IN_PROGRESS, pola result są nadal puste ("" / 0) a finished_at / expires_at są 0; obserwuj status i progress.

Żądanie

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

Strumień odpowiedzi

// Przykład wydarzenia błędu
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Wydarzenia message przenoszą pełen obiekt zadania na każdym etapie; pola
// result pozostają puste, dopóki zadanie nie zostanie ukończone.
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: { // Przykład elementu strumienia zadania zakończonego SUCCEEDED, odwzorowującego strukturę 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
}

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

Usuń zadanie Text to Motion

Ten punkt końcowy trwale usuwa zadanie Text to Motion, w tym wygenerowany klip ruchu. Ta czynność jest nieodwracalna.

Parametry ścieżki

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

Zwraca

Zwraca 200 OK w przypadku sukcesu.

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

// Zwraca 200 Ok w przypadku sukcesu.

Obiekt Zadania Tekst-na-Ruch

Obiekt Zadania Tekst-na-Ruch reprezentuje jednostkę pracy do generowania klipu ruchu z tekstowego promptu.

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), kiedy zadanie zostało utworzone.
Znacznik czasu reprezentuje liczbę milisekund upłyniętych od 1 stycznia 1970 UTC, zgodnie ze standardem RFC 3339. Na przykład, piątek, 1 września 2023, godzina 12:00:00 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), kiedy zadanie rozpoczęło przetwarzanie. 0, jeśli nie rozpoczęto.
Name
finished_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki), kiedy zadanie zostało zakończone. 0, jeśli nie zakończono.
Name
expires_at
Type
timestamp
Description
Znacznik czasu (w milisekundach od epoki), kiedy wygasają zasoby wynikowe zadania. 0 dopóki zadanie nie zostanie zakończone. Generowany 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. Istotne tylko, jeśli status to PENDING; pomijane, gdy wynosi zero.
Name
consumed_credits
Type
integer
Description
Liczba kredytów zużytych przez to zadanie. 10 dla trybu prime, 3 dla trybu swift. Zwraca 0 dla zadań FAILED (kredyty są zwracane w przypadku niepowodzenia).
Name
task_error
Type
object
Description
Szczegóły błędu dla niepowodzeń zadania; null, chyba że zadanie FAILED. Zobacz Błędy dla pełnego odniesienia do obiektu task_error.
Name
result
Type
object
Description
Zawiera wygenerowany klip ruchu, gdy zadanie SUCCEEDED; do tego czasu pola są obecne, ale puste ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Pobieralny URL do wygenerowanego klipu ruchu. 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 trybu prime, bvh dla trybu swift.
- Name
  duration_ms
  Type
  integer
  Description
  Czas trwania wygenerowanego klipu w milisekundach.
- Name
  mode
  Type
  string
  Description
  Tryb, w którym klip został wygenerowany: prime lub swift.

Przykładowy Obiekt Zadania Tekst-na-Ruch

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