Text to Motion API

Doğal dilde açıklamalardan karakter hareket klipleri oluşturun. Bir eylemi tanımlayın — „el sallayan bir karakter", „ileriye doğru sendeleyen bir zombi" — ve kendi pipeline'ınızda veya DCC araçlarınızda riglenmiş karakterlere yeniden hedefleyebileceğiniz ham bir hareket klibi elde edin.

Çıktı, bağımsız bir hareket klibidir: bir karakter modeline ihtiyaç duymaz ve ona bağlı değildir. Önce bir karakteri riglemek için Rigging API'sine bakın. Oluşturulan bir klibi riglenmiş karakterinize uygulamak için görev id'sini motion_task_id olarak Animasyon API'sine iletin — bunu 3 günlük varlık saklama penceresi içinde uygulayın.

POST/openapi/v1/text-to-motion

Metinden Harekete Görevi Oluşturma

Bu uç nokta, bir metin prompt'undan hareket klibi oluşturmak için yeni bir görev oluşturur.

Görev arka planda çalışır. Genellikle ne kadar sürdüğünü öğrenmek için İşlem Süreleri bölümüne bakın.

mode değeri prime olan bir görev 10 kredi harcar ve en yüksek kaliteli hareket modelimizle üretim yapar. mode değeri swift olan bir görev ise 3 kredi harcar ve ekonomik hareket modelimizle daha hızlı üretim yapar.

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 hareketin doğal dilde açıklaması. En fazla 400 karakter.
Name
mode
Type
string
varsayılan prime
Description
Hareket oluşturma mode'u. Kullanılabilir değerler: prime, swift. prime en yüksek kaliteyi üretir ve FBX çıktısı verir; swift daha hızlı ve daha ucuzdur ve BVH çıktısı verir.
Name
duration
Type
number
Zorunlu
Description
Hareket klibinin saniye cinsinden hedef süresi. 2 ile 10 arasında, 0.5 adımlarla (örneğin 2, 2.5, 3, … 10).

Dönüş Değerleri

Yanıtın result özelliği, yeni oluşturulan Metinden Harekete görevinin id değerini içerir.

Hata Durumları

Name
400 - Bad Request
Description
İstek kabul edilemedi. Yaygın nedenler:
- Eksik veya boş prompt: prompt eksik, boş veya 400 karakterden uzun.
- Geçersiz mode: mode değeri prime veya swift değil.
- Geçersiz süre: duration eksik, 2–10 aralığının dışında veya 0.5 saniyelik adımlarla uyumlu değil.
Name
401 - Unauthorized
Description
Kimlik doğrulama başarısız oldu. Lütfen API anahtarınızı kontrol edin.
Name
402 - Payment Required
Description
Bu görevi gerçekleştirmek için yeterli kredi yok.
Name
403 - Forbidden
Description
Prompt, içerik moderation tarafından işaretlendi.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

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

Bir Text to Motion Görevini Getirme

Bu uç nokta, geçerli bir görev id'si verildiğinde bir Text to Motion görevini almanızı sağlar. Hangi özelliklerin dahil edildiğini görmek için The Text to Motion Task Object bölümüne bakın.

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
Alınacak Text to Motion görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Yanıt, Text to Motion Task nesnesini içerir. Ayrıntılar için The Text to Motion Task Object bölümüne bakın.

GET/openapi/v1/text-to-motion

Metinden Hareket Görevlerini Listele

Çağıranın Metinden Hareket görevlerinin, en yeniden en eskiye sıralanmış, sayfalanmış bir listesini döndürür. page_num ve page_size üzerinden standart sayfalama kullanılır.

Yanıt, Metinden Hareket Görevi nesnelerinden oluşan bir dizidir.

API üzerinden oluşturulan görevlerin API üzerinden yönetildiğini unutmayın — bunlar web uygulamasının My Assets bölümünde görünmez. Artık ID'sine sahip olmadığı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

Bir Text to Motion Görevini Akış Olarak Alma

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir Text to Motion görevi için gerçek zamanlı güncellemeleri akış olarak sunar.

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
}

Parametreler

Name
id
Type
path
Description
Akışı alınacak Text to Motion görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Text to Motion Görev Nesneleri'nin Server-Sent Events olarak bir akışını döndürür.

Her message olayı, görevin tam nesnesini taşır. Görev PENDING veya IN_PROGRESS durumundayken, result alanları hâlâ boştur ("" / 0) ve finished_at / expires_at 0'dır; status ve progress'i takip edin.

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

Bir Text to Motion Görevini Sil

Bu uç nokta, oluşturulan hareket klibi de dahil olmak üzere bir Text to Motion görevini kalıcı olarak siler. Bu işlem geri alınamaz.

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

Yol Parametreleri

Name
id
Type
path
Description
Silinecek Text to Motion görevinin ID'si.

Görev Durumu

Hâlâ PENDING durumunda olan bir görev silinir ve oluşturma sırasında harcanan kredi iade edilir.

Zaten IN_PROGRESS durumunda olan bir görev silinemez: istek 409 Conflict ile reddedilir ve görev çalışmaya devam eder. İşçinin (worker) zaten başlattığı bir görev için harcanan kredi iade edilemez, bu yüzden çalışma sırasında silmek hem krediyi hem de sonucu kaybetmenize neden olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Uç durumda (SUCCEEDED, FAILED veya CANCELED) olan bir görev iade yapılmadan silinir.

Dönüş Değerleri

Başarılı olduğunda 200 OK, görev IN_PROGRESS durumundaysa 409 Conflict döner.

Text to Motion Görev Nesnesi

Text to Motion Görev nesnesi, bir metin promptundan bir hareket klibi oluşturma iş birimini temsil eder.

Ö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 için benzersiz tanımlayıcı.
Name
type
Type
string
Description
Görevin türü. Değer text-to-motion'dır.
Name
status
Type
string
Description
Görevin durumu. Olası değerler: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Görevin ilerleme durumu (0-100).
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman damgası (epoch'tan bu yana geçen milisaniye).
Bir zaman damgası, RFC 3339 standardını takip ederek 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısını temsil eder. Örneğin, 1 Eylül 2023 Cuma günü 12:00:00 GMT, 1693569600000 olarak temsil edilir. Bu, Meshy API'deki tüm zaman damgaları için geçerlidir.
Name
started_at
Type
timestamp
Description
Görevin işlenmeye başladığı zaman damgası (epoch'tan bu yana geçen milisaniye). Başlamadıysa 0.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman damgası (epoch'tan bu yana geçen milisaniye). Tamamlanmadıysa 0.
Name
expires_at
Type
timestamp
Description
Görev sonucu varlıklarının süresinin dolacağı zaman damgası (epoch'tan bu yana geçen milisaniye). Görev tamamlanana kadar 0. Oluşturulan klip, görev tamamlandıktan sonra 3 gün boyunca saklanır; süresi dolmadan önce indirin.
Name
preceding_tasks
Type
integer
Description
Kuyruktaki önceki görevlerin sayısı. Yalnızca durum PENDING olduğunda anlamlıdır; sıfır olduğunda atlanır.
Name
consumed_credits
Type
integer
Description
Bu görev tarafından tüketilen kredi sayısı. prime mode için 10, swift mode için 3. FAILED görevler için 0 döner (başarısızlık durumunda kredi iade edilir).
Name
task_error
Type
object
Description
Başarısız görevler için hata ayrıntıları; görev FAILED olmadıkça null. Tam task_error nesne referansı için Hatalar bölümüne bakın.
Name
result
Type
object
Description
Görev SUCCEEDED olduğunda oluşturulan hareket klibini içerir; o zamana kadar alanlar mevcuttur ancak boştur ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Oluşturulan hareket klibi için indirilebilir URL. URL her okumada yeniden imzalanır ve görevin saklama penceresiyle birlikte süresi dolar.
- Name
  motion_format
  Type
  string
  Description
  Klibin dosya formatı: prime mode için fbx, swift mode için bvh.
- Name
  duration_ms
  Type
  integer
  Description
  Oluşturulan klibin milisaniye cinsinden süresi.
- Name
  mode
  Type
  string
  Description
  Klibin oluşturulduğu mode: prime veya swift.