Text to Motion API

Metin açıklamalarından karakter hareket klipleri oluşturun. "El sallayan bir karakter" veya "ileri doğru sendeleyerek yürüyen bir zombi" gibi bir eylemi tanımlayın ve ham bir hareket klibi elde edin. Bu klibi kendi pipeline'ınızda veya DCC araçlarınızda rig'lenmiş karakterlere yeniden hedefleyebilirsiniz.

Çıktı, bağımsız bir hareket klibidir. Bir karakter modeline ihtiyaç duymaz ve herhangi birine bağlı değildir. Önce bir karakteri rig'lemek için Rigging API bölümüne bakın. Bir klibi rig'lenmiş karakterinize uygulamak için görev id'sini motion_task_id olarak Animasyon API'sine gönderin.

POST/openapi/v1/text-to-motion

Metinden Harekete görevi oluşturma

Bir metin promptundan hareket klibi oluşturan bir Metinden Harekete görevi oluşturur.

Görev arka planda çalışır. Bir görevin genellikle ne kadar sürdüğü için bkz. İşlem süreleri.

Bir prime görevi 10 kredi karşılığındadır ve Meshy'nin daha yüksek kaliteli hareket modelini kullanır. Bir swift görevi 3 kredi karşılığındadır ve daha hızlı, daha düşük maliyetli bir hareket modeli kullanır.

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

Parametreler

Name
prompt
Type
string
Zorunlu
Description
Oluşturulacak hareketi açıklayan, en fazla 400 karakter uzunluğunda metin. Daha uzun metinler 400 döndürür.
Name
mode
Type
string
varsayılan prime
Description
Hareket modeli, aynı zamanda klibin dosya formatını da belirler.
Kullanılabilir değerler:
- prime: daha yüksek kalite, bir FBX klip döndürür
- swift: daha hızlı ve ucuz, bir BVH klip döndürür
Başka herhangi bir değer 400 döndürür.
Name
duration
Type
number
Zorunlu
Description
Hedef klip uzunluğu saniye cinsinden, 2'den 10'a kadar 0,5 artışlarla, örneğin 2, 2.5 veya 3. Başka herhangi bir değer 400 döndürür.

Dönüş değerleri

Yanıtın result alanı, yeni Metinden Harekete görevinin kimliğini (ID) tutar.

Başarısızlık modları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Hata mesajı hangi sorunun bulunduğunu belirtir. Örneğin:
- Eksik veya boş prompt: prompt eksik, boş veya 400 karakterden uzun.
- Geçersiz mode: mode, prime veya swift değil.
- Geçersiz duration: duration eksik, 2 ile 10 aralığının dışında veya 0,5 saniyelik bir adımda değil.
İsteği düzeltin, ardından yeniden gönderin. Bkz. Hatalar.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Örneğin:
- Yetersiz kredi: Hesapta bu görev için yeterli kredi yok veya hesap bir kredi sınırına ulaştı. Kredi bakiyenizi kontrol edin, ardından tekrar deneyin.
- Ücretsiz plan: Bir görev oluşturmak ücretli bir plan gerektirir. abonelik ayarlarınızdan planınızı yükseltin, ardından tekrar deneyin.
Name
403 - Forbidden
Description
İçerik moderation'ı promptu işaretledi. Promptu değiştirin, ardından isteği yeniden gönderin.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız. Bekleyin, ardından tekrar deneyin. Bkz. Hız sınırları.

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

Bir Text to Motion görevini alma

Bir Text to Motion görevini ID'siyle döndürür.

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
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev ID'si.

Dönüş Değerleri

Text to Motion görev nesnesi.

GET/openapi/v1/text-to-motion

Text to Motion görevlerini listele

Text to Motion görevlerinizin, en yeniden en eskiye sıralanmış şekilde sayfalanmış bir listesini döndürür. Liste boyunca sayfalar arasında gezinmek için page_num ve page_size kullanın.

Yanıt, Text to Motion görev nesnelerinden oluşan bir dizidir.

API ile oluşturduğunuz görevler API içinde kalır ve web uygulamasındaki My Assets bölümünde görünmez. Kimliğini artık elinizde bulundurmadığınız bir görevi bulmak için bu uç noktayı kullanın.

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

Metinden Harekete görevini akış olarak alma

Bir Metinden Harekete görevinin güncellemelerini Sunucu Gönderimli Olaylar (SSE) olarak akış halinde yayınlar.

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
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev kimliği.

Döndürülenler

Metinden Harekete görev nesnelerinin Sunucu Gönderimli Olaylar olarak akışı.

Her message olayı tam görev nesnesini taşır. Görev PENDING veya IN_PROGRESS durumundayken, result alanları boştur ("" veya 0), ve finished_at ile expires_at değerleri 0'dır. Görevi takip etmek için status ve progress alanlarını izleyin.

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

Bir Text to Motion görevini sil

Bir Text to Motion görevini, hareket klibi de dahil olmak üzere kalıcı olarak siler. Bir silme işlemini geri alamazsınız.

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

Yol parametreleri

Name
id
Type
path
Description
Silinecek görevin ID'si.

Görev durumu

PENDING durumundaki bir görevi silmek, oluşturulduğunda kullanılan kredileri iade eder.

IN_PROGRESS durumundaki bir görev silinemez. İstek 409 Conflict döndürür ve görev çalışmaya devam eder. Meshy, başlamış olan bir görev için iade yapmaz, bu nedenle onu silmek size hem kredileri hem de sonucu kaybettirir. SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Nihai bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görevi silmek kredilerini iade etmez.

Dönüş değerleri

Görev silindiğinde 200 OK, görev IN_PROGRESS durumundaysa 409 Conflict.

Metinden Hareketliliğe görev nesnesi

Bir Metinden Hareketliliğe görev nesnesi, tek bir hareket klibinin oluşturulmasını açıklar. Görev başarılı olduğunda durumu, progress bilgisini ve klibi tutar.

Özellikler

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
Görev kimliği. Bunu anlamsız bir dize olarak değerlendirin ve biçimine güvenmeyin.
Name
type
Type
string
Description
Görev türü, her zaman text-to-motion.
Name
status
Type
string
Description
Görev durumu; PENDING, IN_PROGRESS, SUCCEEDED, FAILED veya CANCELED değerlerinden biridir.
Name
progress
Type
integer
Description
Görevin ne kadarının tamamlandığı, 0 ile 100 arasında bir yüzde olarak.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman, Unix milisaniye cinsinden.
Name
started_at
Type
timestamp
Description
Görevin başladığı zaman, Unix milisaniye cinsinden. Görev başlayana kadar 0 değerindedir.
Name
finished_at
Type
timestamp
Description
Görevin bittiği zaman, Unix milisaniye cinsinden. Görev bitene kadar 0 değerindedir.
Name
expires_at
Type
timestamp
Description
Görevin sonuç dosyalarının sona erdiği zaman, Unix milisaniye cinsinden. Görev bitene kadar 0 değerindedir. Meshy, klibi görev bittikten sonra 3 gün boyunca saklar; bu nedenle süre dolmadan indirin.
Name
preceding_tasks
Type
integer
Description
Kuyrukta bu görevden önce bulunan görev sayısı. Bu değer yalnızca görev PENDING durumundayken anlamlıdır. Değer 0 olduğunda bu alan belirtilmez.
Name
consumed_credits
Type
integer
Description
Görevin kullandığı kredi sayısı; prime mode için 10, swift mode için 3. FAILED bir görev için 0 değerindedir, çünkü Meshy bir görev başarısız olduğunda kredileri iade eder.
Name
task_error
Type
object
Description
Görev başarısız olduğunda hata ayrıntıları, aksi halde null. Bkz. Hatalar.
Name
result
Type
object
Description
Görev başarılı olduğunda oluşturulan hareket klibi. O ana kadar alanlar mevcuttur ama boştur ("" veya 0).
- Name
  motion_url
  Type
  string
  Description
  Hareket klibi için indirme URL'si. Meshy, URL'yi her okumada yeniden imzalar ve URL, görevin saklama süresiyle birlikte sona erer.
- Name
  motion_format
  Type
  string
  Description
  Klibin dosya biçimi; prime mode için fbx, swift mode için bvh.
- Name
  duration_ms
  Type
  integer
  Description
  Klip uzunluğu, milisaniye cinsinden.
- Name
  mode
  Type
  string
  Description
  Meshy'nin klibi oluşturmak için kullandığı mode, prime veya swift.