Basılabilirliği Onar API

Bir 3D modeli FDM basılabilirliği için onarın — manifold olmayan kenarları, bozuk yüzeyleri, delikleri ve diğer topology sorunlarını düzelterek ağın baskıya hazır hale gelmesini sağlayın.

POST/openapi/v1/print/repair

Basılabilirliği Onarma Görevi Oluşturma

Bu uç nokta, yeni bir basılabilirliği onarma görevi oluşturur. Görev, bir 3D model üzerinde topology onarımı çalıştırır ve su geçirmez, baskıya hazır bir sürüm döndürür.

Çıktı formatı, giriş formatıyla eşleşir. model_url üzerinden bir .stl gönderirseniz, yanıttaki model_urls.stl alanı onarılmış ağı tutar ve diğer format alanları boş kalır. input_task_id yolu her zaman kaynak görevin GLB dosyasını okur, bu nedenle çıktı .glb olur.

Parametreler

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

Geometri değişiklikleri nedeniyle onarım sırasında mevcut texture'lar kaldırılır. Onarılmış modele texture'ları geri eklemek için Retexture API'ini kullanın.

  • Name
    model_url
    Type
    string
    Zorunlu
    Description

    Onarılacak 3D modelin URL'si. Desteklenen formatlar: .glb, .gltf, .obj, .fbx, .stl. Maksimum dosya boyutu: 100 MB. http, https veya bir data: URL'si kullanılmalıdır (data URL'leri uzantı kontrollerini atlar).

  • Name
    alpha_thumbnail
    Type
    boolean
    varsayılan false
    Description

    true olarak ayarlandığında, görev ayrıca önizlemenin saydam arka planlı (RGBA) bir sürümünü render eder ve bunu GET yanıtında alpha_thumbnail_url olarak döndürür. Mevcut thumbnail_url alanı değişmez.

Dönüş Değerleri

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

Hata Durumları

  • Name
    400 - Bad Request
    Description

    İstek kabul edilemedi. Yaygın nedenler:

    • Eksik parametre: input_task_id veya model_url sağlanmadı.
    • Geçersiz UUID: input_task_id geçerli bir UUID değil.
    • Geçersiz model URL'si: model_url hatalı biçimlendirilmiş, desteklenmeyen bir şema kullanıyor veya desteklenmeyen bir dosya uzantısına sahip.
    • Model dosyası çok büyük: model_url gövdesi 100 MB'yi aştı.
    • Görev başarıyla tamamlanmamış: referans verilen görev hâlâ beklemede, işlemde veya başarısız oldu.
    • GLB eksik: referans verilen görevin onarılacak bir GLB asset'i yok.
  • 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

    Yaygın nedenler:

    • Ücretsiz plan: görev oluşturmak ücretli bir plan gerektirir. Abonelik sayfasından yükseltme yapın.
    • Yetersiz kredi: çalışma alanı kredi limitine ulaşıldı.
  • Name
    404 - Not Found
    Description

    Referans verilen görev mevcut değil veya başka bir kullanıcıya ait.

  • Name
    429 - Too Many Requests
    Description

    Bekleyen görev kotanızı veya hız sınırınızı aştınız.

Request

POST
/openapi/v1/print/repair
# Repair an existing task
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or repair a model URL directly
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.stl"
  }'

Response

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

Bir Basılabilirliği Onar Görevini Getir

Bu uç nokta, bir basılabilirliği onar görevini kimliğine göre getirir.

Parametreler

  • Name
    id
    Type
    path
    Description

    Getirilecek basılabilirliği onar görevinin kimliği.

Dönüş Değerleri

Basılabilirliği Onar Görevi Nesnesi. model_urls bloğu, görev SUCCEEDED durumuna ulaşana kadar boştur. Yalnızca giriş biçimiyle eşleşen model_urls alanı doldurulur.

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}
DELETE/openapi/v1/print/repair/:id

Bir Basılabilirliği Onar Görevini Sil

Bu uç nokta, bir basılabilirlik onarma görevini ve onarılmış çıktısını kalıcı olarak siler. Bu işlem geri alınamaz.

Yol Parametreleri

  • Name
    id
    Type
    path
    Description

    Silinecek basılabilirlik onarma 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. Worker'ın zaten başlatmış olduğu bir görev için kredi iade edilmez, bu yüzden çalışma sırasında silmek hem kredinizi hem de sonucu kaybetmenize neden 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/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/repair/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/print/repair

Basılabilirlik Onarma Görevlerini Listele

Bu uç nokta, basılabilirlik onarma görevlerinin bir listesini almanızı sağlar.

Parametreler

İsteğe bağlı alanlar

  • Name
    page_num
    Type
    integer
    Description

    Sayfalama için sayfa numarası. 1 değerinden başlar ve varsayılan olarak bu değeri alır.

  • Name
    page_size
    Type
    integer
    Description

    Sayfa başına öğe sınırı. Varsayılan olarak 10 öğedir. İzin verilen azami değer 100 öğedir.

  • Name
    sort_by
    Type
    string
    Description

    Sıralama yapılacak alan. Kullanılabilir değerler:

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

Dönüş Değerleri

Basılabilirlik Onarma Görevi Nesnelerinin sayfalanmış bir listesini döndürür.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-repair",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000030000,
    "expires_at": 1715725401000,
    "task_error": null,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "gltf": "",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]
GET/openapi/v1/print/repair/:id/stream

Basılabilirlik Onarma Görevini Akışa Al

Bu uç nokta, Server-Sent Events (SSE) kullanarak bir basılabilirlik onarma görevine ait gerçek zamanlı güncellemeleri akışa alır.

Parametreler

  • Name
    id
    Type
    path
    Description

    Akışa alınacak basılabilirlik onarma görevi için benzersiz tanımlayıcı.

Döndürülenler

Server-Sent Events olarak Basılabilirlik Onarma Görevi Nesneleri akışı döndürür.

Her çerçeve, o aşamaya ait tam görev nesnesini taşır — Get uç noktasının döndürdüğü ile aynı yapı — bu nedenle görev PENDING veya IN_PROGRESS durumundayken çıktı alanları henüz doldurulmamıştır (null, [] veya {}) ve finished_at değeri null'dur. model_urls bloğu yalnızca görev SUCCEEDED durumuna ulaştığında gönderilir.

Request

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

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

Basılabilirliği Onar Görev Nesnesi

  • Name
    id
    Type
    string
    Description

    Görev için benzersiz tanımlayıcı. Uygulama detayı olarak görev id'leri için k-sıralanabilir bir UUID kullansak da, id'nin formatı hakkında herhangi bir varsayımda bulunmamalısınız.

  • Name
    type
    Type
    string
    Description

    Basılabilirliği onar görevinin türü. Değer print-repair şeklindedir.

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

    Görevin ilerleme durumu. Görev henüz başlamadıysa, bu özellik 0 olacaktır. Görev başarıyla tamamlandığında, bu değer 100 olacaktır.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Önceki görevlerin sayısı.

    Bu alanın değeri yalnızca görev durumu PENDING olduğunda anlamlıdır.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

    Görevin başladığı zaman damgası, milisaniye cinsindendir. Görev henüz başlamadıysa, bu özellik 0 olacaktır.

  • Name
    finished_at
    Type
    timestamp
    Description

    Görevin tamamlandığı zaman damgası, milisaniye cinsindendir. Görev henüz tamamlanmadıysa, bu özellik 0 olacaktır.

  • Name
    expires_at
    Type
    timestamp
    Description

    Görev sonucunun sistemden kaldırılacağı zaman damgası, milisaniye cinsindendir. Görev henüz tamamlanmadıysa 0 değerini alır.

  • Name
    task_error
    Type
    object
    Description

    Görev başarısız olduysa hata bilgisi. Görev başarısız olmadıysa bu özellik null değerindedir. Daha fazla ayrıntı için Hatalar bölümüne bakın.

    • Name
      message
      Type
      string
      Description

      Neyin yanlış gittiğini açıklayan hata mesajı.

  • Name
    model_urls
    Type
    object
    Description

    Onarılmış 3D modele indirilebilir URL'ler. Yalnızca girdi formatıyla eşleşen alan doldurulur; diğer format alanları boş dize olarak kalır.

    • Name
      glb
      Type
      string
      Description

      Onarılmış GLB'ye indirilebilir URL. Girdi bir GLB olduğunda veya input_task_id kullanıldığında doldurulur.

    • Name
      gltf
      Type
      string
      Description

      Onarılmış GLTF'ye indirilebilir URL. Girdi bir GLTF yüklemesi olduğunda doldurulur.

    • Name
      fbx
      Type
      string
      Description

      Onarılmış FBX'e indirilebilir URL. Girdi bir FBX yüklemesi olduğunda doldurulur.

    • Name
      obj
      Type
      string
      Description

      Onarılmış OBJ'ye indirilebilir URL. Girdi bir OBJ yüklemesi olduğunda doldurulur.

    • Name
      stl
      Type
      string
      Description

      Onarılmış STL'ye indirilebilir URL. Girdi bir STL yüklemesi olduğunda doldurulur.

    • Name
      usdz
      Type
      string
      Description

      USDZ çıktısı için ayrılmıştır. Basılabilirliği onar görevleri için her zaman boş bir dizedir.

    • Name
      3mf
      Type
      string
      Description

      3MF çıktısı için ayrılmıştır. Basılabilirliği onar görevleri için her zaman boş bir dizedir.

    • Name
      mtl
      Type
      string
      Description

      MTL çıktısı için ayrılmıştır. Basılabilirliği onar görevleri için her zaman boş bir dizedir.

  • Name
    thumbnail_url
    Type
    string
    Description

    Onarılmış modelden oluşturulan bir önizleme görüntüsünün URL'si.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    thumbnail_url alanının şeffaf arka planlı (RGBA) sürümüne indirilebilir URL. Yalnızca görev alpha_thumbnail: true ile oluşturulduğunda ve şeffaf önizleme başarıyla oluşturulduğunda mevcuttur; aksi takdirde bu alan atlanır.

  • Name
    texture_urls
    Type
    array
    Description

    Her zaman boş bir dizidir. Onarım yalnızca girdi geometrisini korur ve texture'ları yeniden oluşturmaz.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bu görev tarafından tüketilen kredi sayısı. Görev SUCCEEDED durumuna ulaştığında 10 değerini alır. FAILED görevler için 0 döner (başarısızlık durumunda krediler iade edilir).

The Repair Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}