Çok Renkli Baskı API'si

3D modelleri, 3D baskı için en fazla 16 renkten oluşan yapılandırılabilir bir renk paleti ile çok renkli 3MF formatına dönüştürün.

POST/openapi/v1/print/multi-color

Çok Renkli 3D Baskı Görevi Oluştur

Bu uç nokta, yeni bir çok renkli 3D baskı görevi oluşturur. Görev, bir 3D modeli 3D baskı için uygun çok renkli bir 3MF dosyasına dönüştürür.

Görev arka planda çalışır. Genellikle ne kadar sürdüğü için bkz. İşlem Süreleri.

Parametreler

input_task_id veya model_url parametrelerinden yalnızca biri gereklidir. İkisi de sağlanırsa input_task_id önceliklidir.

Name
input_task_id
Type
string
Zorunlu
Description
Girdi olarak kullanılacak başarılı bir görevin ID'si. Desteklenen görev türleri: Görselden 3D'ye, Çoklu görselden 3D'ye, Metinden 3D'ye, Yeniden ağ ve Yeniden dokulama. Görevin durumu SUCCEEDED olmalıdır.

Name
model_url
Type
string
Zorunlu
Description
Herkese açık erişilebilir bir .glb veya .fbx model URL'si, ya da bir GLB'nin base64 data: URL'si (data:model/gltf-binary;base64,...). Bir .fbx dosyası http veya https URL'si olarak gönderilmelidir.
Maksimum dosya boyutu: http veya https URL'si için 400 MB, data: URI'si için 100 MB.
100 MB üzerindeki bir dosya en fazla 8.000.000 yüze sahip olabilir. Yüzler üçgen olarak sayılır: bir dörtgen 2 olarak sayılır ve birden fazla kez çizilen bir ağ her kopya için bir kez sayılır. 100 MB üzerinde, bir FBX dosyası ikili FBX 7.1 veya daha yenisi olmalı ve bir GLB dosyası Draco sıkıştırması kullanmamalıdır.

Name
max_colors
Type
integer
varsayılan 4
Description
Çıktı paletindeki maksimum renk sayısı.
Geçerli aralık: 1 ila 16.
Name
style
Type
string
varsayılan realistic
Description
Oluşturulan 3MF dosyasının görsel renk stili.
Kullanılabilir değerler:
- realistic: İnce, foto-gerçekçi ayrıntı için renkleri doğrudan modelin dokusundan örnekler. Daha büyük bir dosya üretir.
- cartoon: Stilize bir görünüm için renkleri temiz, tekdüze bölgelere düzleştirir. Daha küçük bir dosya üretir.
Girdi renk taşımalıdır: realistic, her ağ parçasında UV koordinatlarına sahip tek bir temel renk dokusu gerektirir; cartoon ayrıca köşe başına renkleri de kabul eder. Dokusuz (beyaz) modeller reddedilir — bkz. model_missing_texture.
Name
max_depth
Type
integer
varsayılan 4
Description
Doku renklerini ağ üzerine örneklemek için kullanılan alt bölümleme derinliği. Daha yüksek değerler, daha büyük bir dosya pahasına daha ince renk ayrıntısı yakalar. Yalnızca realistic stiline uygulanır; cartoon için göz ardı edilir.
Geçerli aralık: 3 ila 6.
Name
printer_brand
Type
string
varsayılan bambu
Description
3MF içine yazılan dilimleyici ön ayarının ait olduğu yazıcı markası, böylece dosya eşleşen bir yazıcı, filament ve işlem profiliyle o markanın dilimleyicisinde açılır. Her marka, 0,4 mm nozulu varsayılan yazıcısını kullanır.
Kullanılabilir değerler: bambu, anycubic, creality, elegoo, flashforge, prusa, qidi, snapmaker, ankermake.

Dönüş Değerleri

Yanıtın result özelliği, yeni oluşturulan 3D baskı görevinin id'sini içerir.

Hata Modları

Name
400 - Bad Request
Description
İstek kabul edilemedi. Yaygın nedenler:
- Eksik parametre: model_url veya input_task_id sağlanmalıdır.
- Geçersiz model biçimi: model_url, desteklenmeyen bir uzantıya sahip bir dosyayı gösteriyor (yalnızca .glb ve .fbx desteklenir).
- Erişilemeyen URL: model_url indirilemedi.
- Model dosyası çok büyük: model_url dosyası 400 MB'ı (http veya https URL'si) ya da 100 MB'ı (data: URI'si) aşıyor.
- Çok fazla yüz: model_url dosyası 100 MB'ın üzerinde ve 8.000.000'dan fazla yüze sahip. Yüz sayısını azaltın, ardından dosyayı tekrar gönderin.
- 100 MB üzerinde ASCII FBX: model_url dosyası 100 MB üzerinde bir ASCII FBX. Bunu ikili FBX veya GLB olarak gönderin.
- Okunamayan model dosyası: model_url dosyası 100 MB'ın üzerinde ve başlığı okunamıyor, örneğin Draco sıkıştırmalı bir GLB veya 7.1'den eski bir ikili FBX.
- Model başlığı çok karmaşık: model_url dosyası 100 MB'ın üzerinde ve başlığı kontrol edilemeyecek kadar çok ağ, düğüm veya kayıt içeriyor. Dosyadaki nesne sayısını azaltın, ardından tekrar gönderin.
- Geçersiz girdi görevi: input_task_id, başarılı bir göreve referans vermelidir.
- Geçersiz max_colors: Değer 1 ile 16 arasında olmalıdır.
- Geçersiz style: Değer realistic veya cartoon olmalıdır.
- Geçersiz max_depth: Değer 3 ile 6 arasında olmalıdır.
- Geçersiz printer_brand: Değer yukarıda listelenen markalardan biri olmalıdır.
- Renk kaynağı yok: Girdi modelinin ne temel renk dokusu var (realistic, her ağ parçasında UV'li tek bir doku gerektirir) ne de köşe renkleri var (cartoon ikisini de kabul eder). Modeli önce dokulandırın veya köşe renkli modeller için cartoon kullanın. .fbx yüklemeleri, görev onları normalleştirdikten sonra kontrol edilir ve bunun yerine model_missing_texture ile başarısız olur.
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
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to a multi-color 3MF with a Creality slicer preset
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8,
    "printer_brand": "creality"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/print/multi-color/:id

Çok Renkli 3D Baskı Görevini Alma

Bu uç nokta, ID'sine göre bir çok renkli 3D baskı görevini alır.

Parametreler

Name
id
Type
path
Description
Alınacak 3D baskı görevinin ID'si.

Dönüş Değerleri

3D Baskı Görevi nesnesi.

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

DELETE/openapi/v1/print/multi-color/:id

Bir Çok Renkli 3D Baskı Görevini Sil

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

Yol Parametreleri

Name
id
Type
path
Description
Silinecek çok renkli 3D baskı 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şlatmış olduğu bir görev için krediler iade edilemez, bu nedenle çalışma sırasında silmek hem kredilerinize hem de sonuca mal olur. SUCCEEDED, FAILED veya CANCELED durumuna ulaşmasını bekleyin, ardından silin.

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

Dönüş Değerleri

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

Request

DELETE

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/multi-color/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/multi-color

Çok Renkli 3D Baskı Görevlerini Listele

Bu uç nokta, çok renkli 3D baskı 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'dir.
Name
page_size
Type
integer
Description
Sayfa boyutu sınırı. Varsayılan olarak 10 öğedir. İzin verilen maksimum 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ırayla sıralar.
- -created_at: Oluşturulma zamanına göre azalan sırayla sıralar.

Dönüş Değerleri

3D Baskı Görev Nesneleri için sayfalanmış bir liste döndürür.

Request

GET

/openapi/v1/print/multi-color

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]

GET/openapi/v1/print/multi-color/:id/stream

Çok Renkli Bir 3D Baskı Görevini Akışa Alma

Bu uç nokta, Server-Sent Events (SSE) kullanarak çok renkli bir 3D baskı görevi için gerçek zamanlı güncellemeleri akışa alır.

Parametreler

Name
id
Type
path
Description
Akışa alınacak çok renkli 3D baskı görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

3D Baskı Görevi Nesnelerinin Server-Sent Events olarak 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/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/multi-color/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

3D Baskı Görevi 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
3D Baskı görevinin türü. Değer print-multi-color şeklindedir.
Name
model_urls
Type
object
Description
Meshy tarafından oluşturulan 3D model dosyasına indirilebilir URL. Bir format oluşturulmamışsa, boş bir dize döndürmek yerine o format için özellik atlanır.
- Name
  3mf
  Type
  string
  Description
  Çok renkli 3MF dosyasına indirilebilir URL.
Name
progress
Type
integer
Description
Görevin progress'i. Görev henüz başlamadıysa, bu özellik 0 olacaktır. 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 değerlerinden 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 damgası, milisaniye cinsinden.
Name
started_at
Type
timestamp
Description
Görevin başladığı zaman damgası, milisaniye cinsinden. Görev henüz başlamadıysa, bu özellik 0 olacaktır.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zaman damgası, milisaniye cinsinden. Görev henüz tamamlanmadıysa, bu özellik 0 olacaktır.
Name
task_error
Type
object
Description
Başarısız görevler için hata detayları. Tam task_error nesne 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ı. Görev durumu PENDING, IN_PROGRESS veya SUCCEEDED olduğunda mevcuttur. FAILED görevler için 0 döner (başarısızlık durumunda kredi iadesi yapılır).

The 3D Print Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}