Creative Lab — Katlanabilir Fidget API

Bir kaynak fotoğrafı, baskıya hazır katlanabilir bir fidget oyuncağına dönüştürün: öznenin silueti, düz şekilde katlanıp yeniden uzayabilen iç içe geçmiş halkalar kümesine dönüşür ve montaj gerektirmeden tek parça olarak basılır.

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

Diğer Creative Lab endpoint'lerinden farklı olarak bu endpoint'te prototip/derleme aşaması çifti bulunmaz — aralarından seçim yapılacak ara adaylar yoktur, dolayısıyla tek bir görev görüntüyü baştan sona bir 3D modele kadar taşır. Web uygulamasının sunduğu geometri kontrolleri (boyut, katman sayısı, boşluk genişliği, duvar kalınlığı, ekstrüzyon derinliği, şişkinlik) de istek kapsamına dahil değildir: her görev, sunucu tarafındaki aynı varsayılan değerlerle oluşturulur.

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

Katlanabilir Fidget Görevi Oluşturma

Bir kaynak fotoğraftan katlanabilir bir fidget modeli oluşturun. Yanıt şekli için The Collapsible Fidget Task Object bölümüne bakın.

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

Parametreler

Name
image_url
Type
string
Zorunlu
Description
Meshy'nin katlanabilir bir fidgete dönüştüreceği kaynak fotoğraf. Şu anda .jpg, .jpeg, .png ve .webp formatlarını destekliyoruz.
Görüntüyü sağlamanın iki yolu vardır:
- Herkese açık erişilebilir URL: Genel internetten erişilebilen bir URL.
- Data URI: Görüntünün base64 ile kodlanmış bir data URI'si. Data URI örneği: data:image/jpeg;base64,<base64 ile kodlanmış görüntü verileriniz>.
Tek, net ve kapalı bir dış hatta sahip bir konu en iyi sonucu verir — halkalara dönüşen şey silüettir. Karmaşık arka planlar, birkaç ayrı konu veya çok ince şekiller, iç içe geçmiş duvarlar için yeterli alan bırakmayabilir ve görev bir görev hatasıyla başarısız olur.
Name
name
Type
string
Description
Görüntüleme amaçlı isteğe bağlı görev adı. En fazla 100 karakter. Bu yalnızca bir görev etiketidir; modelin üzerine hiçbir şey işlenmez.

Dönüş Değerleri

Yanıtın result özelliği, yeni oluşturulan katlanabilir fidget görevinin id değerini içerir. Görev SUCCEEDED durumuna ulaşana kadar Get a Task uç noktasını yoklayın veya stream uç noktasına abone olun, ardından yazdırılabilir STL dosyasını model_urls.stl üzerinden indirin (ve mevcutsa, önce önizlemek için GLB dosyasını model_urls.glb üzerinden indirin).

Başarısızlık Durumları

Name
400 - Bad Request
Description
İstek kabul edilemedi. Yaygın nedenler:
- Eksik parametre: image_url zorunludur.
- Geçersiz görüntü formatı: Sağlanan image_url desteklenen bir format değil (.jpg, .jpeg, .png, .webp).
- Görüntü boyutları aralık dışında: Görüntü çok küçük, maksimum dosya boyutunu aşıyor veya maksimum piksel sayısını aşıyor.
- Erişilemeyen URL: image_url indirilemedi (404 veya timeout).
- Geçersiz Data URI: base64 dizesi hatalı biçimlendirilmiş.
- İçerik işaretlendi: Girdi görüntüsü NSFW moderation tarafından işaretlendi.
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
Ya hesabınız ücretsiz planda — bu uç noktada görev oluşturmak ücretli bir plan gerektirir — ya da yeterli krediniz yok.
Name
403 - Forbidden
Description
Girdi görüntüsü fikri mülkiyet ihlali nedeniyle işaretlendi.
Name
429 - Too Many Requests
Description
Hız sınırınızı aştınız.

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"
}

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

Katlanabilir Fidget Görevini Al

Geçerli bir görev id'si verilerek katlanabilir bir fidget görevini alın. Yalnızca bu uç nokta aracılığıyla oluşturulan görevlere burada erişilebilir — başka bir Creative Lab uç noktasından veya web uygulamasında oluşturulan bir görev 404 döndürür.

Yanıt biçimi için Katlanabilir Fidget Görev Nesnesi bölümüne bakın.

Parametreler

Name
id
Type
path
Description
Alınacak katlanabilir fidget görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Yanıt, katlanabilir fidget görev nesnesini içerir.

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=***"
  }
}

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

Katlanabilir Fidget Görevini Sil

Katlanabilir bir fidget görevini iptal eder. Görev hâlâ PENDING durumundaysa, oluşturma sırasında harcanan kredi iade edilir. Zaten IN_PROGRESS durumunda olan görevler iade yapılmadan iptal edilir (işçi zaten kaynak tüketiyor olabilir). Zaten sonlanmış bir duruma ulaşmış görevler (SUCCEEDED, FAILED, CANCELED) iptal edilemez.

Yol Parametreleri

Name
id
Type
path
Description
İptal edilecek katlanabilir fidget görevi için benzersiz tanımlayıcı.

Döndürülen Değerler

Başarı durumunda boş bir gövdeyle 204 No Content döndürür.

Hata Modları

Name
400 - Bad Request
Description
Görev zaten sonlanmış bir durumda ve iptal edilemez.
Name
404 - Not Found
Description
Görev mevcut değil, farklı bir kullanıcıya ait ya da bu uç nokta üzerinden oluşturulmamış.

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).

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

Bir Katlanabilir Fidget Görevini Akış Olarak Al

Bir katlanabilir fidget görevi için gerçek zamanlı güncellemeleri Server-Sent Events (SSE) aracılığıyla akış olarak alın. Var olmayan veya bu uç nokta üzerinden oluşturulmamış bir görev, status_code: 404 değerine sahip tek bir event: error yükü yayınlar ve akışı kapatır.

Parametreler

Name
id
Type
path
Description
Akışı alınacak katlanabilir fidget görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Server-Sent Events olarak bir Collapsible Fidget görev nesneleri akışı 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/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
  }
}

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

Katlanabilir Fidget Görevlerini Listele

Katlanabilir fidget görevlerinizin sayfalanmış bir listesini alın. Sadece bu uç nokta üzerinden oluşturulan görevler dahil edilir.

Sorgu Parametreleri

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 değer 100 öğedir.
Name
sort_by
Type
string
varsayılan -created_at
Description
Sıralama için kullanı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

Katlanabilir fidget görev nesnesinin sayfalanmış bir listesini döndürür.

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=***"
    }
  }
]

Katlanabilir Fidget Görev Nesnesi

Katlanabilir Fidget Görevi nesnesi, Meshy'nin bir kaynak fotoğrafı yerinde basılabilir katlanabilir bir fidget modeline dönüştürmek için takip ettiği bir iş birimidir. Tek aşamalı bir görevdir: zincirlenecek bir prototip yoktur ve ara silüet yanıtın bir parçası değildir.

Özellikler

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çimiyle ilgili herhangi bir varsayımda bulunmamalısınız.
Name
type
Type
string
Description
Görevin türü. Değer creative-lab-fidget-collapsible şeklindedir.
Name
name
Type
string
Description
Görev oluşturulurken verilen görev adı. Ad sağlanmadıysa boş bir dizedir.
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 progress değeri. 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
created_at
Type
timestamp
Description
Görevin oluşturulduğu zamanın milisaniye cinsinden zaman damgası.
Bir zaman damgası, RFC 3339 standardını izleyerek 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısını temsil eder. Örneğin, 1 Eylül 2023 Cuma, GMT 12:00:00, 1693569600000 olarak temsil edilir. Bu, Meshy API'deki tüm zaman damgaları için geçerlidir.
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 null olur.
Name
finished_at
Type
timestamp
Description
Görevin tamamlandığı zamanın milisaniye cinsinden zaman damgası. Görev henüz tamamlanmadıysa bu özellik null olur.
Name
expires_at
Type
timestamp
Description
Görev sonucunun süresinin dolacağı zamanın milisaniye cinsinden zaman damgası.
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
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ı. 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 krediler iade edilir).
Name
model_urls
Type
object
Description
Oluşturulan 3D model için indirilebilir URL'ler. Görev SUCCEEDED durumuna ulaştığında doldurulur: stl her zaman mevcuttur, glb ise yalnızca önizleme render'ı başarılı olduğunda bulunur.
- Name
  stl
  Type
  string
  Description
  STL dosyasına indirilebilir URL. Bu, basılabilir teslim edilecek dosyadır — doğrudan bir dilimleyiciye gönderin.
- Name
  glb
  Type
  string
  Description
  Modeli bir 3D görüntüleyicide önizlemek için GLB dosyasına indirilebilir URL. Renkleri yalnızca önizleme amaçlıdır: STL renk taşımaz ve basılmış bir fidget rengini filamentten alır. GLB en iyi çaba temelinde sunulur: önizleme render'ı kullanılamadığında bu anahtar model_urls içinden tamamen çıkarılır, bu yüzden bunu savunmacı bir şekilde okuyun — stl, teslim edilecek dosyadır ve bir SUCCEEDED görevinde her zaman mevcuttur.

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=***"
  }
}