Auto Split API

Bir 3D modeli, ayrı ayrı basılabilir parçalara ayırın — otomatik olarak, isimlendirdiğiniz parçalara göre veya renk bölgesine göre — isteğe bağlı bağlayıcılarla; bir kesim sonucu oluşan ince bölgeler, her parçanın sağlam basılması için her zaman güçlendirilir.

Auto Split şu anda yalnızca dokusuz (untextured) modelleri desteklemektedir. Görselden 3D'ye ve Çoklu görselden 3D'ye için, girdiyi should_texture değeri false olarak ayarlanmış şekilde oluşturun. Doku içeren bir girdi 400 ile reddedilir.

POST/openapi/v1/print/split

Auto Split Görevi Oluştur

Bu uç nokta yeni bir Auto Split görevi oluşturur. Görev, önceki bir görevin modelini ayrı ayrı basılabilir parçalara böler ve segmentlere ayrılmış modeli döndürür; her parça dosyada kendi nesnesi olarak yer alır.

Parametreler

  • Name
    mode
    Type
    string
    varsayılan auto
    Description

    Modelin parçalara nasıl ayrılacağı.

    Kullanılabilir değerler:

    • auto: Kesimleri Meshy seçer. prompt dikkate alınmaz.
    • by_parts: prompt içinde belirttiğiniz yapısal parçalar boyunca kesim yapılır; örneğin kafa, kollar ve gövde.
    • by_color: prompt içinde belirttiğiniz renk bölgeleri boyunca kesim yapılır. Yüklenen bir görselden üretilmiş bir girdi gerektirir (Görselden 3D'ye veya Çoklu görselden 3D'ye); diğer girdiler 400 ile reddedilir.
Yalnızca şu durumlarda geçerli mode = by_parts or by_color
  • Name
    prompt
    Type
    string
    Zorunlu
    Description

    Bölünecek parçaları, herhangi bir dilde tanımlar. Meshy bundan 1 ila 10 parça adı okur, bu nedenle modeli tarif etmek yerine parçaları adlandırın — örneğin figürü ve tabanı böl ya da kafa, gövde, sol kol, sağ kol, bacaklar. En fazla 600 karakter. İki başarısızlık modu vardır: bir bölme gibi okunan ancak ikiden az parça adlandıran bir açıklama (örneğin ayrı parçalara böl) 400 ile reddedilir ve herhangi bir ücret alınmaz; Meshy'nin hiç okuyamadığı bir açıklama ise auto'ya geri döner, görev yine de çalışır ve ücretlendirilir, yanıtında prompt_ignored: true bulunur.

  • Name
    target_formats
    Type
    array
    varsayılan ["glb"]
    Description

    Bölünmüş modelin dışa aktarılacağı formatlar. Her formatta her parça ayrı bir nesnedir. glb her zaman üretilir ve model_urls içinde döndürülür; ek olarak istediğiniz diğer formatları listeleyin.

    Kullanılabilir değerler: glb, obj, fbx, usdz, blend, 3mf.

  • Name
    layout
    Type
    string
    varsayılan assembled
    Description

    Parçaların her çıktı formatında ve küçük resimde nasıl düzenleneceği.

    Kullanılabilir değerler:

    • assembled: Parçalar kaynak modeldeki konumlarında kalır.
    • on_plate: Parçalar düz bir şekilde yerleştirilir ve dilimlemeye hazır olacak şekilde baskı tablasına yayılır — web uygulamasının On Plate görünümüyle aynı düzenlemedir.

    Her iki düzende de dışa aktarılan dosyalar, parça başına bir nesne içerir ve başka hiçbir şey içermez: bir kesimden arta kalan çökmüş bir ince parça veya nokta benzeri parça, dışa aktarmadan önce kaldırılır, böylece dosyada bulduğunuz her nesne basılabilir olur.

  • Name
    connectors
    Type
    boolean
    varsayılan false
    Description

    Basılan parçaların birbirine oturması için her kesim noktasına geçme (mortise-and-tenon) bağlantı elemanları ekler.

Yalnızca şu durumlarda geçerli connectors = true
  • Name
    connector_type
    Type
    string
    varsayılan cube
    Description

    Her kesim yüzeyindeki bağlantı elemanının şekli.

    Kullanılabilir değerler: cube, cylinder.

  • Name
    connector_size
    Type
    number
    varsayılan 0.5
    Description

    Kesim yüzeyine göre bağlantı elemanı boyutu.

    Geçerli aralık: 0.1 ile 0.8 arası.

  • Name
    connector_height
    Type
    number
    varsayılan 0.1
    Description

    Bağlantı elemanının kesim yüzeyine göre ne kadar dışarı uzandığı.

    Geçerli aralık: 0.1 ile 0.8 arası.

Dönüş Değerleri

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

Hata Modları

  • Name
    400 - Bad Request
    Description

    İstek kabul edilemedi. Yaygın nedenler:

    • Eksik prompt: mode değeri by_parts veya by_color olduğunda prompt zorunludur.
    • Prompt ikiden az parça adlandırıyor: by_parts / by_color en az iki adlandırılmış parça gerektirir (örneğin kafa, gövde, taban); ayrı parçalara böl gibi genel bir talimat reddedilir. Herhangi bir ücret alınmaz.
    • Desteklenmeyen girdi görevi: input_task_id, Meshy 6 veya Meshy 7 ile üretilmiş, desteklenen bir türde başarılı bir göreve işaret etmelidir.
    • Doku içeren girdi: Girdi modelinin dokuları var. Şu an için yalnızca dokusuz modeller desteklenmektedir.
    • Referans görsel yok: by_color, yüklenen bir görselden üretilmiş bir girdi gerektirir.
    • Desteklenmeyen format: target_formats içinde stl bulunuyor.
    • Bağlantı elemanı aralık dışı: connector_size veya connector_height değeri 0.1 ile 0.8 aralığının dışında.
  • 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
    404 - Not Found
    Description

    input_task_id mevcut değil veya hesabınıza ait değil.

  • Name
    429 - Too Many Requests
    Description

    Hız sınırınızı aştınız. by_parts ve by_color istekleri ayrıca hesap başına dakikada 12 istekle sınırlı bir prompt ayrıştırma sınırını paylaşır.

  • Name
    503 - Service Unavailable
    Description

    Prompt tabanlı bölme (by_parts ve by_color) geçici olarak kullanılamıyor. Daha sonra tekrar deneyin veya bundan etkilenmeyen mode: "auto" seçeneğini kullanın. Herhangi bir ücret alınmaz.

Request

POST
/openapi/v1/print/split
# Simple request: let Meshy choose the cuts
curl https://api.meshy.cn/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Advanced request: name the parts, add connectors, export glb and obj
curl https://api.meshy.cn/openapi/v1/print/split \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "mode": "by_parts",
    "prompt": "split into the figure and the base",
    "target_formats": ["glb", "obj"],
    "layout": "on_plate",
    "connectors": true,
    "connector_type": "cylinder",
    "connector_size": 0.4
  }'

Response

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

Bir Auto Split Görevini Alma

Bu uç nokta, kimliğine göre bir Auto Split görevini alır.

Parametreler

  • Name
    id
    Type
    path
    Description

    Alınacak Auto Split görevinin kimliği.

Dönüş Değerleri

Auto Split Görevi nesnesi.

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}
DELETE/openapi/v1/print/split/:id

Bir Auto Split Görevini Sil

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

Yol Parametreleri

  • Name
    id
    Type
    path
    Description

    Silinecek Auto Split görevinin kimliği.

Dönüş Değerleri

Başarılı olduğunda 200 OK döner.

Request

DELETE
/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.cn/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.
GET/openapi/v1/print/split

List Auto Split Tasks

Bu uç nokta, Auto Split görevlerinin bir listesini almanızı sağlar.

Parametreler

İsteğe bağlı özellikler

  • Name
    page_num
    Type
    integer
    Description

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

  • Name
    page_size
    Type
    integer
    Description

    Sayfa boyutu sınırı. Varsayılan olarak 10 öğedir. İzin verilen maksimum değer 100 öğedir; daha büyük değerler 100 ile sınırlandırılır.

  • 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ıralar.
    • -created_at: Oluşturulma zamanına göre azalan sırada sıralar.

Dönüş Değerleri

Auto Split Görev Nesneleri'nin sayfalanmış bir listesini döndürür.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-split",
    "model_urls": {
      "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "part_count": 4,
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000082000,
    "task_error": null,
    "consumed_credits": 10
  }
]
GET/openapi/v1/print/split/:id/stream

Bir Auto Split Görevini Akış Olarak Aktar

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

Parametreler

  • Name
    id
    Type
    path
    Description

    Akışı alınacak Auto Split görevinin benzersiz tanımlayıcısı.

Dönüş Değerleri

Server-Sent Events olarak Auto Split Görev Nesneleri akışı döndürür.

Her message olayı, Bir Auto Split Görevini Al tarafından döndürülen tam görev nesnesini taşır; buna consumed_credits, zaman damgaları ve prompt_ignored da dahildir. Görev PENDING veya IN_PROGRESS durumundayken kareler arasında değişen alanlar progress, status, started_at ve preceding_tasks'tır; model_urls, thumbnail_url, part_count ve parts ise görev SUCCEEDED durumuna ulaştığında görünür. Bir error olayı yalnızca status_code ve message taşır, bu yüzden status alanını okumadan önce olay adına göre dallanma yapın.

Request

GET
/openapi/v1/print/split/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.cn/openapi/v1/print/split/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}

Auto Split Görev Nesnesi

Bir Auto Split görevi yalnızca aşağıdaki özellikleri taşır. Diğer görev nesnelerinin içerdiği üretim prompt alanları (name, object_prompt, texture_prompt vb.), tekil model_url ve texture_urls bir bölme (split) işlemi için asla doldurulmaz ve döndürülmez. Görev çalışırken doldurulan özellikler (thumbnail_url, model_urls, zaman damgaları) her zaman mevcuttur, değer alana kadar boştur; bu nedenle anahtar kümesi PENDING ile SUCCEEDED arasında değişmez.

  • Name
    id
    Type
    string
    Description

    Görev için benzersiz tanımlayıcı. Uygulama detayı olarak görev kimlikleri için k-sıralanabilir bir UUID kullansak da, kimliğin biçimi hakkında hiçbir varsayımda bulunmamalısınız.

  • Name
    type
    Type
    string
    Description

    Görevin türü. Değer print-split'tir.

  • Name
    model_urls
    Type
    object
    Description

    Bölünmüş modele indirilebilir URL'ler, istenen her biçim için bir tane. Dosyadaki her parça ayrı bir nesnedir. Bir biçim istenmediyse o biçime ait özellik atlanır.

    • Name
      glb
      Type
      string
      Description

      Bölünmüş modelin GLB biçimindeki indirilebilir URL'si.

    • Name
      obj
      Type
      string
      Description

      Bölünmüş modelin OBJ biçimindeki indirilebilir URL'si.

    • Name
      fbx
      Type
      string
      Description

      Bölünmüş modelin FBX biçimindeki indirilebilir URL'si.

    • Name
      usdz
      Type
      string
      Description

      Bölünmüş modelin USDZ biçimindeki indirilebilir URL'si.

    • Name
      blend
      Type
      string
      Description

      Bölünmüş modelin Blender biçimindeki indirilebilir URL'si.

    • Name
      3mf
      Type
      string
      Description

      Bölünmüş modelin 3MF biçimindeki indirilebilir URL'si.

  • Name
    thumbnail_url
    Type
    string
    Description

    Bölünmüş modelin, her parçanın farklı bir renkte gösterildiği ve istenen layout düzeninde sunulan render edilmiş önizlemesine indirilebilir URL.

  • Name
    prompt_ignored
    Type
    boolean
    Description

    Bir by_parts veya by_color isteğinin prompt alanı hiçbir parça adı belirtmediğinde true olur; bu durumda Meshy modeli otomatik olarak bölmüştür — sonuçtaki parça adları sizin değil, Meshy'nin verdiği adlardır. PENDING durumundan itibaren mevcuttur. auto görevlerinde ve prompt'un takip edildiği durumlarda atlanır.

  • Name
    part_count
    Type
    integer
    Description

    Bölünmüş modeldeki basılabilir parça sayısı — dışa aktarılan dosyalardaki her nesne için bir tane. Segmentasyonun basılabilir bir parçaya dönüştüremediği çökmüş ince parçalar dışa aktarmadan önce dosyalardan kaldırılır ve sayıma dahil edilmez.

  • Name
    progress
    Type
    integer
    Description

    Görevin ilerleme durumu. Görev henüz başlamadıysa bu özellik 0 olur. Görev başarılı olduğunda bu değer 100 olur.

  • Name
    status
    Type
    string
    Description

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

  • 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ın milisaniye cinsinden zaman damgası.

  • Name
    started_at
    Type
    timestamp
    Description

    Görevin başladığı zamanın milisaniye cinsinden zaman damgası. Görev henüz başlamadıysa bu özellik 0 olur.

  • Name
    finished_at
    Type
    timestamp
    Description

    Görevin tamamlandığı zamanın milisaniye cinsinden zaman damgası. Görev henüz tamamlanmadıysa bu özellik 0 olur.

  • Name
    task_error
    Type
    object
    Description

    Başarısız görevler için hata ayrıntıları. task_error nesnesinin tam referansı için Hatalar bölümüne bakın.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bu görev tarafından tüketilen kredi sayısı. Her zaman mevcuttur: görev kabul edildikten sonra 10, FAILED görevler için ise 0, çünkü başarısızlık durumunda ücret iade edilir. Bir görevi hâlâ PENDING durumundayken silmek de ücretin iadesini sağlar.

The Auto Split Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-split",
  "model_urls": {
    "glb": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.cn/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "part_count": 4,
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000082000,
  "task_error": null,
  "consumed_credits": 10
}