Creative Lab Katlanabilir Fidget API'si

Bir fotoğrafı, tek bir görevle baskıya hazır, katlanabilir bir fidget oyuncağına dönüştürün. Öznenin silueti, düz bir şekilde katlanıp tekrar açılabilen iç içe geçmiş eşmerkezli halkalara dönüşür. Oyuncak, herhangi bir montaj gerektirmeden tek parça olarak basılır.

POST /openapi/creative-lab/fidget-collapsible/v1

Diğer Creative Lab endpoint'lerinden farklı olarak, bunun ayrı bir prototip ve build aşaması yoktur. Aralarından seçim yapılacak aday görseller bulunmaz; bu nedenle tek bir görev, fotoğrafı doğrudan bir 3B modele dönüştürür.

İsteğin herhangi bir geometri ayarı da yoktur. Web uygulaması; boyut, katman sayısı, boşluk genişliği, duvar kalınlığı, ekstrüzyon derinliği ve şişkinlik değerlerini ayarlamanıza olanak tanır. Her API görevi, bunlar için aynı varsayılan değerleri kullanır.

POST/openapi/creative-lab/fidget-collapsible/v1

Bir Katlanabilir Fidget görevi oluşturun

Bir fotoğraftan katlanabilir fidget modeli oluşturur. Görevin alanları için bkz. Katlanabilir Fidget görevi nesnesi.

Her görev 6 kredi tutar ve ücretli bir plan gerektirir.

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parametreler

Name
image_url
Type
string
Zorunlu
Description
Katlanabilir fidget'a dönüştürülecek fotoğraf; herkese açık bir URL veya data URI (data:image/jpeg;base64,<base64 kodlu görsel verileriniz>) olarak belirtilir.
Görsel, en fazla 20 MB boyutunda bir JPG, JPEG, PNG veya WebP dosyası olmalıdır.
Öznenin silüeti halkalara dönüşür, bu yüzden tek, net ve kapalı bir dış çizgiye sahip bir özne en iyi sonucu verir. Karışık bir arka plan, birden fazla ayrı özne veya çok ince şekiller, iç içe geçmiş duvarlar için yeterli alan bırakmayabilir. Bu durumda görev başarısız olur.
Name
name
Type
string
Description
Görev için en fazla 100 karakterlik bir ad. Bu ad görevin name alanında geri döner ve Meshy bunu modelin üzerine işlemez. Daha uzun bir ad 400 döndürür.

Dönüş Değerleri

result alanı, yeni görevin kimliğini tutar. status değeri SUCCEEDED olana kadar görevi alın veya onu akış olarak izleyin. Ardından yazdırılabilir STL dosyasını model_urls.stl üzerinden indirin. Modeli önce önizlemek için, mevcut olduğunda GLB dosyasını model_urls.glb üzerinden indirin.

Başarısızlık durumları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Örneğin:
- image_url eksik.
- Görsel bir JPG, JPEG, PNG veya WebP dosyası değil.
- Görsel çok küçük, 20 MB'ın üzerinde veya maksimum piksel sayısının üzerinde.
- Meshy görseli indiremiyor, örneğin URL 404 döndürdüğü veya zaman aşımına uğradığı için.
- Data URI geçerli bir base64 değil.
- Görsel, müstehcen (NSFW) olarak işaretlendi.
Hata mesajı hangi sorunun bulunduğunu belirtir. İsteği düzeltin, ardından tekrar gönderin.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Aşağıdakilerden biri geçerlidir:
- Hesapta yeterli kredi yok.
- API anahtarı, çalışma alanı veya üye, kredi sınırına ulaştı.
- Hesap ücretsiz planda.
Kredilerinizi ve planınızı kontrol edin, ardından yeniden deneyin.
Name
403 - Forbidden
Description
Ekibinizde IP Filtering özelliği açık ve Meshy, görseli üçüncü taraf fikri mülkiyeti nedeniyle işaretledi. Kullanım hakkına sahip olduğunuz bir görsel gönderin.
Name
429 - Too Many Requests
Description
Aşağıdaki sınırlardan biri aşıldı:
- Hız sınırınızın izin verdiğinden daha fazla istek gönderdiniz. Birkaç saniye bekleyip tekrar deneyin. Bkz. Hız sınırları.
- Sıraya alınan veya çalışan görev sayınız çok fazla. Bazılarının tamamlanmasını bekleyin, ardından tekrar deneyin.
- Sınırsız bir planda kredisi kalmamış durumda, kredisiz çalıştırılabilecek görev sayısına ulaştınız. Bir görevin tamamlanmasını bekleyin veya kredi ekleyin.
Name
500 - Internal Server Error
Description
Meshy bir sunucu hatasıyla karşılaştı, örneğin görsel üzerinde fikri mülkiyet kontrolünü çalıştıramadığı için. Meshy görevi oluşturmaz ve varsa tahsil ettiği kredileri iade eder. İsteği tekrar deneyin.

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Daraltılabilir Fidget görevi al

Bir Daraltılabilir Fidget görevini döndürür. Yalnızca bu uç nokta ile oluşturulan görevler döndürülür. Başka bir Creative Lab uç noktasından veya web uygulamasında oluşturulan bir görev 404 döndürür.

Alanlar için bkz. Daraltılabilir Fidget görev nesnesi.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından alınan görev kimliği.

Döndürülen değer

Daraltılabilir Fidget görev nesnesi.

Hata durumları

Name
400 - Bad Request
Description
id geçerli bir görev kimliği değil. Oluşturma yanıtındaki result kimliğini gönderin.
Name
403 - Forbidden
Description
Ekibinizde IP Filtering özelliği açık ve Meshy, görevin görselini üçüncü taraf fikri mülkiyet açısından işaretledi. Enterprise plan kullanan ekipler bu hatayı almaz. Kullanım haklarına sahip olduğunuz bir görselden görev oluşturun.
Name
404 - Not Found
Description
Bu kimliğe sahip hiçbir Daraltılabilir Fidget görevi hesabınıza ait değil veya görev bu uç nokta ile oluşturulmadı. Kimliği kontrol edin.
Name
500 - Internal Server Error
Description
Meshy fikri mülkiyet kontrolünü çalıştıramadı. İsteği tekrar deneyin.

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Collapsible Fidget görevini sil

Bir Collapsible Fidget görevini iptal eder. PENDING durumundaki bir görevi iptal etmek kredilerini iade eder. IN_PROGRESS durumundaki bir görev, bir işçi süreci zaten başlattığı için iade yapılmadan iptal edilir. Nihai bir duruma sahip bir görev (SUCCEEDED, FAILED veya CANCELED) iptal edilemez.

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

Yol parametreleri

Name
id
Type
path
Description
İptal edilecek görevin kimliği.

Dönüş değerleri

Boş bir gövdeyle birlikte 204 No Content.

Hata modları

Name
400 - Bad Request
Description
Şunlardan biri geçerlidir:
- id geçerli bir görev kimliği değil. Oluşturma yanıtındaki result kimliğini gönderin.
- Görev zaten nihai bir duruma sahip (SUCCEEDED, FAILED veya CANCELED), bu nedenle iptal edilemez.
Name
404 - Not Found
Description
Bu kimliğe sahip hesabınıza ait bir Collapsible Fidget görevi yok veya görev bu uç nokta ile oluşturulmamış. Kimliği kontrol edin.

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Katlanabilir Fidget görevini akış olarak alma

Bir Katlanabilir Fidget görevinin güncellemelerini Server-Sent Events (SSE) olarak akışa alır. Görev mevcut değilse veya bu uç nokta ile oluşturulmadıysa, akış status_code: 404 ile bir error olayı gönderir ve kapanır.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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 following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Parametreler

Name
id
Type
path
Description
Oluşturma yanıtından gelen görev ID'si.

Dönüş Değerleri

Katlanabilir Fidget görev nesnelerinin akışı. Her olay, Bir Katlanabilir Fidget görevini alma işleminin döndürdüğü şekliyle tam görev nesnesini içerir. Görev PENDING veya IN_PROGRESS durumundayken, çıktı alanları hâlâ boştur (null, [] veya {}) ve finished_at değeri null'dur.

Eğer IP Filtreleme görevin sonucunu engellerse, akış onun yerine bir get isteğinin döndüreceği status_code ile birlikte tek bir error olayı gönderir.

GET/openapi/creative-lab/fidget-collapsible/v1

Collapsible Fidget görevlerini listele

Collapsible Fidget görevlerinizi, her seferinde bir sayfa olmak üzere döndürür. Yalnızca bu uç nokta ile oluşturulan görevler dahildir.

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

Sorgu parametreleri

Name
page_num
Type
integer
varsayılan 1
Description
Döndürülecek sayfa, 1 ile 255 arasında. 0 ilk sayfayı döndürür. 0 ile 255 dışındaki bir değer 400 döndürür.
Name
page_size
Type
integer
varsayılan 10
Description
Sayfa başına görev sayısı, en fazla 100. 101 ile 255 arasındaki bir değer 100 görev döndürür ve 0 varsayılanı kullanır. 0 ile 255 dışındaki bir değer 400 döndürür.
Name
sort_by
Type
string
varsayılan -created_at
Description
Sıralama düzeni.
Kullanılabilir değerler:
- -created_at: en yeniden en eskiye
- +created_at: en eskiden en yeniye

Döndürülenler

Collapsible Fidget görev nesnelerinden oluşan bir dizi.

Collapsible Fidget görev nesnesi

Bir Collapsible Fidget görevi, bir fotoğrafı yazdırılmaya hazır (print-in-place) katlanabilir bir fidget modeline dönüştürür. Bu tek aşamalı bir görevdir, bu nedenle zincirlenebileceği bir prototip görev yoktur. Yanıt, Meshy'nin süreç boyunca oluşturduğu silueti içermez.

Özellikler

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Name
id
Type
string
Description
Görev kimliği. Biçimine güvenmeyin.
Name
type
Type
string
Description
Görev türü, her zaman creative-lab-fidget-collapsible.
Name
name
Type
string
Description
Görevi oluştururken gönderdiğiniz name değeri, göndermediyseniz "".
Name
status
Type
string
Description
Görevin durumu.
Kullanılabilir değerler:
- PENDING: kuyrukta bekliyor
- IN_PROGRESS: sonuç üretiliyor
- SUCCEEDED: kesin, sonuçla birlikte
- FAILED: kesin, nedeni task_error içinde
- CANCELED: kesin, sonuç yok
Name
progress
Type
integer
Description
Tamamlanan işin yüzdesi, 0 ile 100 arasında. Görev başlayana kadar 0, başarılı olduğunda 100 olur.
Name
created_at
Type
timestamp
Description
Görevin oluşturulduğu zaman, Unix milisaniye cinsinden.
Name
started_at
Type
timestamp
Description
Bir çalışanın (worker) göreve başladığı zaman, Unix milisaniye cinsinden. O ana kadar null.
Name
finished_at
Type
timestamp
Description
Görevin kesin bir duruma ulaştığı zaman, Unix milisaniye cinsinden. O ana kadar null.
Name
expires_at
Type
timestamp
Description
Görev sonucunun süresinin dolduğu zaman, Unix milisaniye cinsinden. Bu, finished_at'ten 3 gün sonra, ya da görev tamamlanana kadar created_at'ten 3 gün sonradır. API sonuçlarını süresiz olarak saklayan Enterprise hesapları için bu süre yaklaşık 100 yıl sonrasıdır. Bkz. Varlık saklama.
Name
preceding_tasks
Type
integer
Description
Görev PENDING durumundayken kuyruktaki konumu. 1, sıradaki görev olduğu anlamına gelir. Görev kuyruktan ayrıldıktan sonra 0, liste sonuçlarında ise her zaman 0'dır.
Name
task_error
Type
object
Description
Görevin neden başarısız olduğu. status değeri FAILED olmadıkça null. Bkz. Hatalar.
Name
consumed_credits
Type
integer
Description
Görev için, varsa iade sonrası ücretlendirilen kredi sayısı. Hata döndüren bir istek ücretlendirilmez. Başarısız bir görev 0'dır, çünkü Meshy bunu iade eder. İptal etme, bir görevi yalnızca PENDING durumundayken iade eder. Meshy ücretlendirmeyi okuyamazsa, bir get veya stream yanıtı bu alanı dışarıda bırakır ve bir liste isteği 500 döndürür. Bu durumda isteği yeniden deneyin.
Name
model_urls
Type
object
Description
3D model için indirme URL'leri, görev başarılı olana kadar boştur. Başarılı bir görev her zaman stl içerir ve yalnızca Meshy önizlemeyi oluşturduysa glb içerir.
- Name
  stl
  Type
  string
  Description
  Yazdırılacak dosya olan STL dosyası için indirme URL'si. Bunu doğrudan bir dilimleyicide açabilirsiniz.
- Name
  glb
  Type
  string
  Description
  Modeli bir 3D görüntüleyicide önizlemek için bir GLB dosyasının indirme URL'si. Renkleri yalnızca önizleme içindir. STL dosyasının rengi yoktur, bu nedenle yazdırılan fidget rengini filamentten alır.
  Meshy önizlemeyi oluşturamazsa, model_urls içinde glb anahtarı bulunmaz, bu nedenle okumadan önce anahtarın varlığını kontrol edin. SUCCEEDED durumundaki bir görev her zaman stl içerir.