Creative Lab — Katlanabilir Fidget API

Bir kaynak fotoğrafı, yerinde basılabilen katlanabilir bir fidget oyuncağına dönüştürün: öznenin silueti, düz bir şekilde katlanan ve tekrar açılan iç içe geçmiş eşmerkezli halkalar kümesine dönüşür; montaj gerektirmeden tek parça halinde basılır.

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

Diğer Creative Lab endpoint'lerinden farklı olarak, bu endpoint'in prototip/build aşaması çifti yoktur — aralarından seçim yapılacak ara adaylar bulunmaz, bu nedenle tek bir görev görüntüyü doğrudan 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 isteğin bir parçası değildir: her görev aynı sunucu tarafı varsayılan değerlerle oluşturulur.

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

Katlanabilir Fidget Görevi Oluşturma

Kaynak bir fotoğraftan katlanabilir bir fidget modeli oluşturun. Yanıt şekli için Katlanabilir Fidget Görev Nesnesi 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 fidget'a dönüştüreceği kaynak fotoğraf. Şu anda .jpg, .jpeg, .png ve .webp formatlarını destekliyoruz.

    Görseli sağlamanın iki yolu vardır:

    • Herkese açık erişilebilir URL: Genel internetten erişilebilen bir URL.
    • Data URI: Görselin base64 ile kodlanmış bir data URI'si. Örnek bir data URI: data:image/jpeg;base64,<base64 ile kodlanmış görsel verileriniz>.

    Tek, net ve kapalı bir dış hatta sahip bir konu en iyi sonucu verir — halkalara dönüşecek olan şey siluettir. Karmaşık arka planlar, birden fazla 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ı. Maksimum 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 Görev Alma uç noktasını yoklayın veya stream'e abone olun, ardından yazdırılabilir STL dosyasını model_urls.stl üzerinden indirin (ve mevcutsa, önce önizlemek için model_urls.glb üzerinden GLB dosyasını indirin).

Hata Modları

  • Name
    400 - Bad Request
    Description

    İstek kabul edilemedi. Yaygın nedenler:

    • Eksik parametre: image_url zorunludur.
    • Geçersiz görsel formatı: Sağlanan image_url desteklenen bir formatta değil (.jpg, .jpeg, .png, .webp).
    • Görsel boyutları aralık dışında: Görsel ç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örseli 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 plandadır — bu uç noktada görev oluşturmak ücretli bir plan gerektirir — ya da yeterli krediniz yoktur.

  • Name
    403 - Forbidden
    Description

    Girdi görseli 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 Getir

Geçerli bir id görevi verildiğinde katlanabilir fidget görevini getirin. Yalnızca bu uç nokta üzerinden oluşturulan görevlere burada erişilebilir — başka bir Creative Lab uç noktasından veya web uygulamasında oluşturulmuş bir görev 404 döndürür.

Yanıt şekli için Katlanabilir Fidget Görevi Nesnesi bölümüne bakın.

Parametreler

  • Name
    id
    Type
    path
    Description

    Getirilecek katlanabilir fidget görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Yanıt, katlanabilir fidget görevi 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 edin. Görev hâlâ PENDING durumundaysa, oluşturma sırasında harcanan kredi iade edilir. IN_PROGRESS durumunda olan görevler, iade yapılmadan iptal edilir (worker zaten kaynak tüketiyor olabilir). Zaten bir sonlanmış duruma (SUCCEEDED, FAILED, CANCELED) ulaşmış görevler iptal edilemez.

Yol Parametreleri

  • Name
    id
    Type
    path
    Description

    İptal edilecek katlanabilir fidget görevinin benzersiz tanımlayıcısı.

Dönüş Değerleri

Başarılı olduğunda boş bir gövdeyle 204 No Content döner.

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 veya 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

Katlanabilir Fidget Görevini Akışa Al

Bir katlanabilir fidget görevi için Server-Sent Events (SSE) üzerinden gerçek zamanlı güncellemeleri akışa alın. Var olmayan veya bu uç nokta üzerinden oluşturulmamış bir görev, status_code: 404 içeren tek bir event: error yükü yayar ve akışı kapatır.

Parametreler

  • Name
    id
    Type
    path
    Description

    Akışa alınacak katlanabilir fidget görevi için benzersiz tanımlayıcı.

Dönüş Değerleri

Server-Sent Events olarak bir Katlanabilir Fidget görev nesnesi akışı döndürür. Her kare, aşama için tam görev nesnesini taşır — Get uç noktasının döndürdüğü aynı şekil — bu nedenle görev PENDING veya IN_PROGRESS durumundayken çıkış alanları henüz doldurulmamıştır (null, [] veya {}) ve finished_at değeri null'dı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 PENDING frame below is abbreviated 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=***"
  }
}
GET/openapi/creative-lab/fidget-collapsible/v1

Katlanabilir Fidget Görevlerini Listele

Katlanabilir fidget görevlerinizin sayfalanmış bir listesini alın. Yalnızca 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 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önen Değerler

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örev nesnesi, Meshy'nin bir kaynak fotoğrafı yerinde baskıya uygun katlanabilir bir fidget modeline dönüştürmek için takip ettiği bir iş birimidir. Bu, tek aşamalı bir görevdir: zincirleneceği bir prototip yoktur ve ara silüet yanıtın parçası değildir.

Özellikler

  • Name
    id
    Type
    string
    Description

    Görev için benzersiz tanımlayıcı. Görev kimlikleri için uygulama detayı olarak 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 creative-lab-fidget-collapsible şeklindedir.

  • Name
    name
    Type
    string
    Description

    Görev oluşturulurken sağlanan görev adı. Ad sağlanmadıysa boş 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 ilerlemesi (progress). 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ı takip ederek, 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısını temsil eder. Örneğin, Cuma, 1 Eylül 2023 12:00:00 GMT 1693569600000 olarak temsil edilir. Bu, Meshy API'sindeki 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 bulunur. FAILED görevler için 0 döner (başarısızlık durumunda kredi iade edilir).

  • Name
    model_urls
    Type
    object
    Description

    Oluşturulan 3D model için indirilebilir URL'ler. Görev SUCCEEDED olduğunda doldurulur: stl her zaman bulunur, glb ise yalnızca önizleme render'ı başarılı olduğunda bulunur.

    • Name
      stl
      Type
      string
      Description

      STL dosyasına indirilebilir URL. Bu, baskıya hazır teslim edilebilir öğedir — doğrudan bir dilimleyiciye gönderilebilir.

    • 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 herhangi bir renk taşımaz ve basılmış bir fidget rengini filamentten alır. GLB en iyi çaba (best-effort) esasına dayanır: önizleme render'ı kullanılamadığında bu anahtar model_urls içinden tamamen çıkarılır, bu nedenle bu alanı savunmacı bir şekilde okuyun — stl teslim edilebilir öğedir ve SUCCEEDED durumundaki bir görevde her zaman bulunur.

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