Dönüştür API

Dönüştür API, mevcut 3D modelleri farklı dosya formatlarına dönüştürmenize olanak tanır.

POST/openapi/v1/convert

Dönüştürme Görevi Oluştur

Bu uç nokta, yeni bir format dönüştürme görevi oluşturur.

Parametreler

input_task_id veya model_url değerlerinden yalnızca biri gereklidir. Her ikisi de sağlanırsa, input_task_id önceliklidir.

  • Name
    input_task_id
    Type
    string
    Zorunlu
    Description

    Modelini dönüştürmek istediğiniz, tamamlanmış bir Meshy görevinin ID'si. Görevin durumu SUCCEEDED olmalıdır.

  • Name
    model_url
    Type
    string
    Zorunlu
    Description

    Bir 3D model dosyasına işaret eden, herkese açık bir URL veya data URI. Desteklenen formatlar: .glb, .gltf, .obj, .fbx, .stl. Data URI'ler için MIME type olarak application/octet-stream kullanın.

  • Name
    target_formats
    Type
    string[]
    Zorunlu
    Description

    Dönüştürülen model için çıktı formatlarının listesi. Kullanılabilir değerler: glb, fbx, obj, usdz, blend, stl, 3mf.

Dönüş Değerleri

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

Hata Modları

  • 400 - Bad Request

İstek kabul edilemedi. Yaygın nedenler:

  • Eksik parametre: model_url veya input_task_id değerlerinden biri sağlanmalıdır.
  • Eksik target_formats: En az bir hedef format belirtilmelidir.
  • Geçersiz girdi görevi: input_task_id, başarılı bir göreve işaret etmelidir.
  • Geçersiz model formatı: model_url, desteklenmeyen bir uzantıya sahip bir dosyaya işaret ediyor.
  • Erişilemeyen URL: model_url indirilemedi.
  • 401 - Unauthorized

Kimlik doğrulama başarısız oldu. Lütfen API anahtarınızı kontrol edin.

  • 402 - Payment Required

Bu görevi gerçekleştirmek için yeterli kredi yok.

  • 429 - Too Many Requests

Hız sınırınızı aştınız.

Request

POST
/openapi/v1/convert
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/convert/:id

Bir Dönüştürme Görevini Getir

Bu uç nokta, kimliğine göre bir dönüştürme görevini getirir.

Parametreler

  • Name
    id
    Type
    path
    Description

    Getirilecek dönüştürme görevinin kimliği.

Dönüş Değerleri

Dönüştürme Görevi nesnesi.

Request

GET
/openapi/v1/convert/:id
curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}
DELETE/openapi/v1/convert/:id

Bir Dönüştürme Görevini Sil

Bu uç nokta, ilişkili tüm modeller ve veriler dahil olmak üzere bir dönüştürme görevini kalıcı olarak siler. Bu işlem geri alınamaz.

Yol Parametreleri

  • Name
    id
    Type
    path
    Description

    Silinecek dönüştürme görevinin ID'si.

Görev Durumu

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

Zaten IN_PROGRESS durumunda olan bir görev silinemez: istek 409 Conflict ile reddedilir ve görev çalışmaya devam eder. Worker'ın zaten başlattığı bir görev için krediler iade edilemez, bu nedenle görevi çalışma sırasında silmek hem kredilerinize hem de sonuca mal olur. Görevin SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

Sonlanmış bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görev iade yapılmadan silinir.

Dönüş Değerleri

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

Request

DELETE
/openapi/v1/convert/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -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."
}
GET/openapi/v1/convert

Dönüştürme Görevlerini Listele

Bu uç nokta, dönüştürme görevlerinin bir listesini almanızı sağlar.

Parametreler

  • Name
    page_num
    Type
    integer
    varsayılan 1
    Description

    Sayfalama için sayfa numarası.

  • Name
    page_size
    Type
    integer
    varsayılan 10
    Description

    Sayfa boyutu sınırı. İzin verilen maksimum 100 öğedir.

  • Name
    sort_by
    Type
    string
    Description

    Sıralanacak alan. Kullanılabilir değerler:

    • +created_at: Oluşturulma zamanına göre artan sırada sıralar.
    • -created_at: Oluşturulma zamanına göre azalan sırada sıralar.

Dönüş Değerleri

Sayfalanmış bir Dönüştürme Görevi Nesneleri listesi döndürür.

Request

GET
/openapi/v1/convert
curl https://api.meshy.ai/openapi/v1/convert?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]
GET/openapi/v1/convert/:id/stream

Dönüştürme Görevini Akışa Al (Stream)

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir dönüştürme görevi için gerçek zamanlı güncellemeleri akışa alır.

Parametreler

  • Name
    id
    Type
    path
    Description

    Akışa alınacak dönüştürme görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Server-Sent Events olarak Dönüştürme Görevi Nesnelerinin bir akışını döndürür.

PENDING veya IN_PROGRESS durumundaki görevler için yanıt akışı yalnızca gerekli progress ve status alanlarını içerecektir.

Request

GET
/openapi/v1/convert/:id/stream
curl -N https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

Convert Task Nesnesi

Convert Task nesnesi, bir format dönüştürme işini temsil eder.

Özellikler

  • id · string

Görev için benzersiz tanımlayıcı.

  • type · string

Görevin türü. Değer convert şeklindedir.

  • model_urls · object

Dönüştürülen model dosyaları için indirilebilir URL'ler. Yalnızca target_formats içinde belirtilen formatlar URL'lere sahip olacaktır. Diğer format özellikleri boş dize olacaktır.

  • progress · integer

Görevin ilerlemesi (0-100).

  • status · string

Görevin durumu. Olası değerler: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • preceding_tasks · integer

Önceki görevlerin sayısı. Yalnızca durum PENDING olduğunda anlamlıdır.

  • created_at · timestamp

Görevin oluşturulduğu zaman damgası, milisaniye cinsinden.

  • started_at · timestamp

Görevin başladığı zaman damgası, milisaniye cinsinden. Başlamadıysa 0.

  • finished_at · timestamp

Görevin bittiği zaman damgası, milisaniye cinsinden. Bitmediyse 0.

  • task_error · object

Görev başarısız olursa hata nesnesi. Daha fazla ayrıntı için Hatalar sayfasına bakın.

  • consumed_credits · integer

Bu görev tarafından tüketilen kredi sayısı (her convert görevi için 1 kredi). FAILED görevler için 0 döner.