Creative Lab — Keycap API

Meshy'nin keycap tasarım görsellerine dönüştürmesi için kaynak fotoğraf. Şu anda .jpg, .jpeg, .png ve .webp biçimlerini destekliyoruz.

Biçim, görsel verisi çözümlenerek algılanır, URL'nin dosya uzantısından değil — uzantısı olmayan veya yönlendirme yapan bir URL, baytlar desteklenen bir biçime çözümlendiği sürece çalışır. HTTP yönlendirmeleri takip edilir. EXIF yönlendirmesi normalize edilir, böylece döndürülmüş bir telefon fotoğrafı göründüğü gibi kullanılır.

Sınırlar: her kenarda en az 32 piksel, toplamda en fazla 178.956.970 piksel ve indirildikten sonra en fazla 20.000.000 bayt. Bir data URI için sınır çözümlenmiş baytlara uygulanır, dolayısıyla kaynak dosyanın kendisi bu boyuta kadar olabilir — yaklaşık üçte bir daha büyük olan base64 metnidir ve bu, istek gövdeniz için önemlidir, bu sınır için değil. Bir data URI, bir image/* içerik türü ve ;base64 bildirmelidir.

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. Data URI örneği: data:image/jpeg;base64,<base64 ile kodlanmış görsel verileriniz>.

Görüntüleme amaçlı isteğe bağlı görev adı. En fazla 100 karakter.

true olarak ayarlandığında, image_urls içinde döndürülen görüntüleme render'ı, arka planı kaldırılmış şeffaf bir RGBA PNG olur; böylece herhangi bir arka plan üzerine yerleştirebilirsiniz.

Bu yalnızca görüntüleme render'ı için geçerlidir. Build uç noktasının tükettiği aday bundan etkilenmez, dolayısıyla 3D sonuç her iki durumda da aynıdır.

İstek kabul edilemedi. Yaygın nedenler:

• Eksik parametre: image_url gereklidir.
• Geçersiz görsel biçimi: Sağlanan image_url desteklenen bir biçim 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.

Kimlik doğrulama başarısız oldu. Lütfen API anahtarınızı kontrol edin.

Hesap ücretsiz plandadır (görev oluşturmak için ücretli bir plan gereklidir) veya yeterli krediye sahip değildir.

Girdi görseli fikri mülkiyet moderation tarafından işaretlendi.

Hız sınırınızı aştınız.

Beklenmeyen bir sunucu tarafı hatası oluştu — örneğin içerik moderation hizmeti kullanılamıyordu, girdi görselinin hazırlanması başarısız oldu veya görev oluşturulamadı. Bu durumda hiçbir görev oluşturulmaz, dolayısıyla yeniden denemek güvenlidir.

Aynı OpenAPI uç noktası üzerinden oluşturulmuş bir prototip görevinin görev kimliği. Prototip aynı Meshy hesabı tarafından oluşturulmuş olmalı, SUCCEEDED durumuna ulaşmış olmalı ve en az bir aday üretmiş olmalıdır.

Webapp üzerinden oluşturulan prototip görevleri kabul edilmez — build uç noktası yalnızca POST /openapi/creative-lab/keycap/v1/prototype tarafından üretilen prototip görevlerini kabul eder ve başka herhangi bir kaynağı 404 ile reddeder.

Başarılı prototip görevinin candidate_ids dizisinden alınan, oluşturulacak aday. O göreve ait olmalıdır; başka herhangi bir değer 400 ile reddedilir.

Görüntüleme amaçlı isteğe bağlı görev adı. En fazla 100 karakter.

Üzerine inşa edilecek keycap tabanı. Şu anda mevcut olan tek değer cherry-mx-1x1-r1 — standart bir Cherry MX profilli 1u keycap. 3–5 ek yaygın standart boyut planlanmaktadır; özel boyutlar desteklenmemektedir.

Şekillendirilmiş kafanın hedef boyutu, milimetre cinsinden: en uzun boyutu bu değere ölçeklenir. Aralık: [10, 40]. Yaklaşık 32.9 üzerindeki değerler, kafanın hâlâ tabanın koruyucu ayak izi sınırına sığması için azaltılabilir; bu nedenle teslim edilen en uzun boyut istenenden küçük olabilir. Uygulanan değer bugün itibarıyla görev nesnesinde geri yansıtılmaz — gerçekte aldığınız boyutu doğrulamanız gerekiyorsa, indirilen modeldeki keycap-head ağının sınırlayıcı kutusunu ölçün.

Kafa tabana oturtulmadan önce uygulanan dikey ofset, milimetre cinsinden. Aralık: [-5, 5].

İstek kabul edilemedi. Yaygın nedenler:

• Eksik parametre: input_task_id ve candidate_id zorunludur.
• Geçersiz UUID: input_task_id geçerli bir UUID değil.
• Üst görev başarılı değil: Referans verilen prototip görevi henüz SUCCEEDED durumuna ulaşmadı.
• Aday yok: Prototip görevi başarılı oldu ancak hiçbir aday üretmedi.
• Bilinmeyen aday: candidate_id, girdi görevinin adaylarından biri değil.
• Seçenekler aralık dışında: options alanlarından biri izin verilen aralığın veya enum kümesinin dışında kaldı.

Kimlik doğrulama başarısız oldu. Lütfen API anahtarınızı kontrol edin.

Hesap ücretsiz plan üzerinde (görev oluşturmak için ücretli bir plan gereklidir) veya yetersiz kredisi var.

Referans verilen prototip görevi mevcut değil, farklı bir kullanıcıya ait veya webapp üzerinden oluşturulmuş (yalnızca API modundaki prototip görevleri build'e zincirlenebilir).

Hız sınırınızı aştınız.

Beklenmeyen bir sunucu tarafı hatası oluştu — örneğin içerik moderation hizmeti kullanılamadı, girdi görüntüsünün hazırlanması başarısız oldu veya görev oluşturulamadı. Bu durumda hiçbir görev oluşturulmaz, bu nedenle yeniden denemek güvenlidir.

Getirilecek keycap görevinin benzersiz tanımlayıcısı.

İptal edilecek keycap görevi için benzersiz tanımlayıcı.

Görev zaten sonlanmış bir durumda ve iptal edilemez.

Görev mevcut değil, farklı bir kullanıcıya ait veya aşaması URL yoluyla eşleşmiyor.

İptal işlemi sırasında beklenmeyen bir sunucu tarafı hatası oluştu. Görev iptal edilmiş veya edilmemiş olabilir — yeniden denemeden önce doğrulamak için görevi tekrar okuyun.

Akış olarak alınacak keycap görevi için benzersiz tanımlayıcı.

prototype veya build olabilir. Koleksiyon yalnızca aşaması URL ile eşleşen görevleri döndürür — /prototype çağrısı asla build görevlerini döndürmez ve bunun tersi de geçerlidir.

Sayfalama için sayfa numarası.

Sayfa boyutu sınırı. İzin verilen maksimum 100 öğedir.

Sıralama yapılacak alan. Kullanılabilir değerler:

• +created_at: Oluşturulma zamanına göre artan sırayla sırala.
• -created_at: Oluşturulma zamanına göre azalan sırayla sırala.

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 hiçbir varsayımda bulunmamalısınız.

Görevin türü. Değer creative-lab-keycap-prototype şeklindedir.

Görev oluşturulduğunda sağlanan görev adı. Ad sağlanmadıysa boş dizedir.

Görevin durumu. Olası değerler PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED değerlerinden biridir.

Görevin progress'i. Görev henüz başlamadıysa, bu özellik 0 olacaktır. Görev başarılı olduğunda, bu 100 olacaktır.

Görevin oluşturulduğu zamanın milisaniye cinsinden zaman damgası.

Görevin başladığı zamanın milisaniye cinsinden zaman damgası. Görev henüz başlamadıysa, bu özellik 0 olacaktır.

Görevin tamamlandığı zamanın milisaniye cinsinden zaman damgası. Görev henüz tamamlanmadıysa, bu özellik 0 olacaktır.

Görev sonucunun süresinin dolacağı zamanın milisaniye cinsinden zaman damgası.

Önceki görevlerin sayısı.

Başarısız görevler için hata detayları. Tam task_error nesne referansı için Hatalar bölümüne bakın.

Bu görev tarafından tüketilen kredi sayısı. SUCCEEDED durumuna ulaşan bir görevden, aşaması için tam tutar tahsil edilir. Hiç oluşturulmamış bir görevden (istek sırasında 4xx, moderation reddi dahil) hiç ücret alınmaz. FAILED durumuna ulaşan bir görev 0 döner — ücret iade edilir, asenkron moderation engeli dahil. DELETE ile iptal etmek yalnızca görev hâlâ PENDING durumundayken ücreti iade eder; zaten IN_PROGRESS durumundaki bir görev ücretlendirilmeye devam eder, çünkü iş harcanmıştır.

Bitmiş keycap tasarım render'ının indirilebilir URL'si — adayın bitmiş bir keycap olarak nasıl göründüğü. Tek bir giriş tutar; image_urls[i], candidate_ids[i]'ye karşılık gelir. Görev SUCCEEDED durumuna ulaşana kadar boştur. URL yalnızca görüntüleme amaçlıdır; derleme uç noktası bu URL'leri değil, candidate_ids'i tüketir. model_urls ile aynı URL yaşam döngüsüne sahiptir: imzalıdır, Authorization başlığı gerektirmez, expires_at'e kadar geçerlidir ve görev yeniden okunduğunda değişmez.

image_urls ile paralel, opak aday tanımlayıcıları. Seçtiğiniz tasarıma karşılık gelen girişi derleme isteğinin candidate_id'si olarak geçirin. Bu id'lerin formatı hakkında hiçbir varsayımda bulunmayın.

Görev için benzersiz tanımlayıcı.

Görevin türü. Değer creative-lab-keycap-build şeklindedir.

Görev oluşturulurken belirtilen görev adı. Ad belirtilmemişse boş dizedir.

Görevin durumu. Olası değerler PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED değerlerinden biridir.

Görevin ilerlemesi (progress). Görev henüz başlamadıysa bu özellik 0 olur. Görev başarıyla tamamlandığında bu değer 100 olur.

Görevin oluşturulduğu zaman damgası, milisaniye cinsinden.

Görevin başladığı zaman damgası, milisaniye cinsinden.

Görevin tamamlandığı zaman damgası, milisaniye cinsinden.

Görev sonucunun süresinin dolduğu zaman damgası, milisaniye cinsinden.

Önceki görevlerin sayısı. Yalnızca durum PENDING olduğunda anlamlıdır.

Başarısız görevler için hata ayrıntıları. Tam task_error nesnesi referansı için Hatalar bölümüne bakın.

Bu görev tarafından tüketilen kredi sayısı. SUCCEEDED durumuna ulaşan bir görevden, aşamasına ait tam tutar tahsil edilir. Hiç oluşturulmamış bir görevden (istek anında bir 4xx hatası, moderation reddi dahil) hiçbir ücret alınmaz. FAILED durumuna ulaşan bir görev 0 döndürür — ücret, asenkron bir moderation engeli dahil olmak üzere iade edilir. DELETE ile iptal etme yalnızca görev hâlâ PENDING durumundayken ücreti iade eder; zaten IN_PROGRESS durumundaki bir görev, iş harcandığı için ücretlendirilmeye devam eder.

Oluşturulan model dosyaları için indirilebilir URL'ler. Hem GLB hem de OBJ paketi gerçek dünya milimetre ölçeğinde, Y-yukarı olarak ve keycap'in ön yüzü +Z yönüne bakacak şekilde dışa aktarılır. Ağlar (mesh) keycap-head ve keycap-base olarak adlandırılır; taban bir desen doldurmasına geri döndüğünde, sap boşluğu için üçüncü bir ağ olan keycap-base-interior de bulunur. Tam olarak iki ağ olduğunu varsaymayın.

Bunlar imzalı URL'lerdir: bunları bir Authorization başlığı olmadan getirin. expires_at değerine kadar geçerli kalırlar; bu değer finished_at'ten 3 gün sonrasıdır ve bu süre içinde görevi yeniden okumak, yeni imzalanmış bir URL yerine aynı URL'yi döndürür. Dosyaları bu süre dolmadan kendiniz indirip saklayın — süresi dolmuş bir bağlantıyı yenilemenin bir yolu yoktur.

Türe göre anahtarlandırılmış, ara işlem görüntüleri için indirilebilir URL'ler. model_urls ile aynı URL yaşam döngüsüne sahiptir: imzalıdır, Authorization başlığı gerektirmez, expires_at'e kadar geçerlidir ve görev yeniden okunduğunda değişmez kalır. Şu anda üretilen türler:

• head_design — oluşturma işleminin tükettiği, seçilen adayın tasarım görüntüsü (her zaman mevcuttur).
• composite — seçilen adayın tamamlanmış keycap görüntüleme render'ı (mevcut olduğunda bulunur).
• base_canvas — boyanmış keycap tabanı tuvali (mevcut olduğunda bulunur).

Anahtar kümesini açık uçlu olarak değerlendirin; yeni türler kırıcı bir değişiklik olmadan eklenebilir.