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.cn/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.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/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.cn/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.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/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.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.cn/***/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}