Metinden Hareket API

Doğal dil tanımlarından karakter hareket klipleri oluşturun. Bir eylemi tanımlayın — "bir karakterin el sallaması", "ileri doğru yürüyen bir zombi" — ve kendi iş akışınızda veya DCC araçlarınızda rig edilmiş karakterlere yeniden hedefleyebileceğiniz ham bir hareket klibi alın.

Çıktı, bağımsız bir hareket klibidir: bir karakter modeline ihtiyaç duymaz ve onunla bağlantılı değildir. Önce bir karakteri riglemek için, Rigging API'ye bakın.

POST/openapi/v1/text-to-motion

Metinden Animasyona Görev Oluştur

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

prime modundaki bir görev 10 krediye mal olur ve en yüksek kaliteli animasyon modelimiz ile üretir. swift modundaki bir görev 3 krediye mal olur ve daha uygun fiyatlı animasyon modelimiz ile daha hızlı üretir.

Parametreler

Name
prompt
Type
string
Zorunlu
Description
Üretilecek animasyonun doğal dilde açıklaması. Maksimum 400 karakter.
Name
mode
Type
string
varsayılan prime
Description
Animasyon oluşturma modu. Kullanılabilir değerler: prime, swift. prime en yüksek kaliteyi üretir ve FBX çıktısı verir; swift daha hızlı ve daha ucuz olup BVH çıktısı verir.
Name
duration
Type
number
Zorunlu
Description
Animasyon klibinin hedef süresi, saniye cinsinden. 2 ile 10 arasında, 0.5 saniye adımlarında (örneğin 2, 2.5, 3, … 10).

Dönüş Değerleri

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

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemezdi. Yaygın nedenler:
- 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–10 arasında değil veya 0.5 saniyelik adımda 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ştirecek yeterli krediniz yok.
Name
403 - Forbidden
Description
Prompt içerik moderation tarafından engellendi.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

Request

POST

/openapi/v1/text-to-motion

# Sadece gerekli parametrelerle bir animasyon klibi oluşturun
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
  }'

# Swift mod ile hızlı, ekonomik bir klip oluşturun
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

Bir Metinden Hareket Görevi Çağırma

Bu uç nokta, geçerli bir görev id verilerek bir Metinden Hareket görevini çağırmanıza olanak tanır. Hangi özelliklerin dahil edildiğini görmek için Metinden Hareket Görev Nesnesi bölümüne bakın.

Parametreler

Name
id
Type
path
Description
Çağırmak için Metinden Hareket görevine ait benzersiz kimlik.

Döndürülenler

Yanıt, Metinden Hareket Görevi nesnesini içerir. Detaylar için Metinden Hareket Görev Nesnesi bölümüne bakın.

İstek

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

Yanıt

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

Metinden Hareket Görevlerini Listele

Çağırıcının Metinden Hareket görevlerinin, en yeniler önce olacak şekilde sayfalanmış bir listesini döndürür. page_num ve page_size ile standart sayfalama.

Yanıt, Metinden Hareket Görevi nesneleri dizisidir.

API üzerinden oluşturulan görevlerin API aracılığıyla yönetildiğini unutmayın — bunlar web uygulamasının My Assets bölümünde görünmez. Artık kimliğini bilmediğiniz bir görevi bulmak için bu uç noktayı kullanın.

İstek

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

Yanıt

[
  {
    "id": "018c425b-b2c6-727e-d333-3c1887i9h791",
    "type": "text-to-motion",
    "status": "SUCCEEDED",
    "...": "..."
  }
]

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

Metni Harekete Dönüştürme Görevini Aktarma

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir Metni Harekete Dönüştürme görevi için gerçek zamanlı güncellemeler aktarır.

Parametreler

Name
id
Type
path
Description
Aktarılacak Metni Harekete Dönüştürme görevine ait benzersiz kimlik.

Dönenler

Metni Harekete Dönüştürme Görev Nesneleri'nin bir akışını Server-Sent Events olarak döndürür.

Her message olayı tam görev nesnesini taşır. Görev PENDING veya IN_PROGRESS olduğunda, result alanları hala boş ("" / 0) ve finished_at / expires_at 0dır; status ve progressü izleyin.

İstek

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

Yanıt Akışı

// Hata olayı örneği
event: error
data: {
  "status_code": 404,
  "message": "Görev bulunamadı"
}

// Mesaj olayları her aşamada tam görev nesnesini taşır; sonuç
// alanları görev başarılı olana kadar boş kalır.
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: { // Başarılı bir görev akış öğesi örneği, Metni Harekete Dönüştürme Görev Nesnesi yapısını yansıtır
  "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

Bir Metinden Hareketli Görev Silme

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

Yol Parametreleri

Name
id
Type
path
Description
Silinecek Metinden Hareketli görevinin ID'si.

Döndürülenler

Başarı durumunda 200 OK döner.

İstek

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

Yanıt

// Başarı durumunda 200 Ok döner.

Metinden Hareket Görev Nesnesi

Metinden Hareket Görev nesnesi, bir metin prompt'undan bir hareket klibi oluşturmak için yapılan iş birimini temsil eder.

Özellikler

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 olarak belirlenir.
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 zamanda (epoch'tan itibaren milisaniye).
Bir zaman damgası, 1 Ocak 1970 UTC tarihinden itibaren geçen milisaniye sayısını temsil eder ve RFC 3339 standardını takip eder. Örneğin, Cuma, 1 Eylül 2023 12:00:00 PM 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ığı zamanda (epoch'tan itibaren milisaniye). Başlamadıysa 0.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zamanda (epoch'tan itibaren milisaniye). Tamamlanmadıysa 0.
Name
expires_at
Type
timestamp
Description
Görev sonucu varlıkların sona erdiği zamanda (epoch'tan itibaren milisaniye). Görev tamamlanana kadar 0. Üretilen klip, görev tamamlandıktan sonra 3 gün süreyle saklanır; sona ermeden önce indirin.
Name
preceding_tasks
Type
integer
Description
Kuyrukta bekleyen önceki görevlerin sayısı. Anlamlıdır yalnızca durum PENDING olduğunda; sıfır olduğunda yok sayılır.
Name
consumed_credits
Type
integer
Description
Bu görev tarafından tüketilen kredi sayısı. prime modunda 10, swift modunda 3. FAILED görevler için 0 döner (hata durumunda krediler iade edilir).
Name
task_error
Type
object
Description
Başarısız olan görevler için hata detayları; görev FAILED değilse null. Tam task_error nesnesi referansı için Hatalar'a bakın.
Name
result
Type
object
Description
Görev SUCCEEDED olduğunda oluşturulan hareket klibini içerir; o zamana kadar alanlar mevcut fakat boş ("" / 0).
- Name
  motion_url
  Type
  string
  Description
  Oluşturulan hareket klibi için indirilebilir URL. URL, her okuma sırasında yeniden imzalanır ve görevin saklama süresi ile birlikte sona erer.
- Name
  motion_format
  Type
  string
  Description
  Klibin dosya formatı: prime modu için fbx, swift modu için bvh.
- Name
  duration_ms
  Type
  integer
  Description
  Oluşturulan klibin süresi milisaniye cinsindendir.
- Name
  mode
  Type
  string
  Description
  Klibin üretildiği modu: prime veya swift.

Örnek Metinden Hareket Görev Nesnesi

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