Creative Lab Tuş Kapağı API'si

Bir fotoğrafı iki aşamada mekanik klavye için tam renkli özel bir tuş kapağına (keycap) dönüştürün. Bir prototip görevi, fotoğraftan tamamlanmış tuş kapağının bir görüntüsünü oluşturur. Bir build görevi ise bu görüntüyü dokulu bir 3D tuş kapağı modeline dönüştürür. Prototip görevinin ID'sini input_task_id olarak ve görüntünün aday ID'sini candidate_id olarak alır.

POST /openapi/creative-lab/keycap/v1/prototype
POST /openapi/creative-lab/keycap/v1/build

Her iki POST endpoint'i de ücretli bir plan gerektirir. Ücretsiz plana sahip bir hesaptan gelen istek 402 döndürür.

POST/openapi/creative-lab/keycap/v1/prototype

Keycap prototip görevi oluşturma

Bir fotoğraftan, tamamlanmış keycap'in bir görselini oluşturur. Görevin image_urls alanı görseli, candidate_ids alanı ise onun kimliğini tutar; her birinde tek bir girdi bulunur. Tasarımı beğenmezseniz başka bir prototip görevi oluşturun. Meshy, her prototip görevini ayrı ayrı ücretlendirir.

3D keycap'i oluşturmak için bu görevin kimliğini build uç noktasına input_task_id olarak, candidate_ids girdisini de candidate_id olarak geçirin. Görevin alanları için Keycap prototip görevi nesnesi bölümüne bakın.

Request

POST

/openapi/creative-lab/keycap/v1/prototype

# Stage 1: generate a finished-keycap design render
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype \
  -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": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef"
}

Parametreler

Name
image_url
Type
string
Zorunlu
Description
Keycap tasarımına dönüştürülecek fotoğraf; genel bir URL veya bir data URI (data:image/jpeg;base64,<base64 ile kodlanmış görsel verileriniz>) olarak verilir.
Görsel, en fazla 20 MB (20.000.000 bayt) boyutunda bir JPG, JPEG, PNG veya WebP dosyası olmalıdır. Her kenar en az 32 piksel olmalı ve görsel toplamda en fazla 178.956.970 piksel içerebilir. Bu sınırların dışındaki bir görsel 400 döndürür.
Meshy, biçimi URL'deki dosya uzantısından değil, görsel verisinden algılar. Uzantısı olmayan bir URL çalışır ve Meshy, HTTP yönlendirmelerini takip eder. Meshy, EXIF yönlendirmesini uygular, böylece döndürülmüş bir telefon fotoğrafı göründüğü gibi çıkar.
Bir data URI, data:image/png;base64,... gibi bir görsel türüyle base64 kodlanmış olmalıdır ve çözülen görsel JPEG, PNG veya WebP olmalıdır. 20 MB sınırı çözülen görsele uygulanır, bu nedenle base64 metni yaklaşık üçte bir oranında daha büyük olabilir.
Name
name
Type
string
Description
Görev için bir ad, en fazla 100 karakter. Görevin name alanında geri döner. Daha uzun bir ad 400 döndürür.
Name
remove_background
Type
boolean
varsayılan false
Description
Prototip görselinden arka planın kaldırılıp kaldırılmayacağı. true değeri, şeffaf bir RGBA PNG döndürür, böylece keycap'i herhangi bir arka plana yerleştirebilirsiniz. Meshy arka planı kaldıramazsa, görseli arka planıyla birlikte döndürür ve görev yine de başarılı olur.
Build'in 3D'ye dönüştürdüğü kapak tasarımı, her iki durumda da arka planını korur. Build, image_urls içindeki görselden keycap tabanını boyar; true gönderdiyseniz arka plan olmadan. Build bu görseli process_image_urls.composite olarak döndürür.

Dönüş Değerleri

result alanı, yeni prototip görevinin kimliğini tutar. status değeri SUCCEEDED olana kadar görevi alın veya akış olarak izleyin. Ardından kimliği, candidate_ids içindeki girdiyi candidate_id olarak kullanarak build uç noktasına input_task_id olarak geçirin.

Hata 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 NSFW olarak işaretlendi.
Hata mesajı hangi sorunu bulduğunu belirtir. İsteği düzeltip tekrar gönderin.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Şunlardan biri geçerlidir:
- Hesapta yeterli kredi yok.
- API anahtarı, çalışma alanı veya üye kredi sınırına ulaştı.
- Hesap ücretsiz plandadır.
Kredilerinizi ve planınızı kontrol edip tekrar deneyin.
Name
403 - Forbidden
Description
Ekibinizde IP Filtering 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
Şu 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ı.
- Kuyrukta bekleyen veya çalışan göreviniz çok fazla. Bazılarının bitmesini bekleyip tekrar deneyin.
- Kredisi kalmamış sınırsız bir plandaysanız, kredisiz çalışabilecek görev sayısına ulaştınız. Bir görevin bitmesini bekleyin veya kredi ekleyin.
Name
500 - Internal Server Error
Description
Meshy bir sunucu hatasıyla karşılaştı; örneğin içerik denetimi veya fikri mülkiyet kontrolü çalıştırılamadığı ya da Meshy görseli depolayamadığı için. Meshy görevi oluşturmaz ve varsa tahsil ettiği kredileri iade eder. İsteği tekrar deneyin.

POST/openapi/creative-lab/keycap/v1/build

Bir Keycap derleme görevi oluştur

Başarılı bir prototip görevinden ve onun adaylarından birinden dokulu 3D keycap oluşturur. Alanları için bkz. Keycap derleme görevi nesnesi.

Bir derleme görevi her adımı çalıştırır. Tasarımdan bir 3D model oluşturur ve onu renklendirir. Ardından modeli kalibre edilmiş varsayılan bir pozda keycap tabanına oturtur ve keser, böylece elle ayarlama yapmanıza gerek kalmaz. Son olarak keycap'i birleştirir ve dosyaları dışa aktarır. Bir derleme genellikle 3 ila 7 dakika sürer.

Request

POST

/openapi/creative-lab/keycap/v1/build

# Stage 2: build the chosen candidate into a 3D keycap
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "candidate_id": "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b",
    "options": {
      "base_model": "cherry-mx-1x1-r1",
      "head_size_mm": 23,
      "vertical_offset_mm": 0
    }
  }'

Response

{
  "result": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af"
}

Parametreler

Name
input_task_id
Type
string
Zorunlu
Description
Derlenecek prototip görevinin ID'si. Bu, hesabınızın POST /openapi/creative-lab/keycap/v1/prototype ile oluşturduğu, durumu SUCCEEDED olan bir görev olmalıdır.
API'den gelen Keycap prototip görevlerinizden biri olmayan bir ID, web uygulamasında yapılmış bir prototip dahil, 404 döndürür.
Name
candidate_id
Type
string
Zorunlu
Description
Prototip görevinin candidate_ids dizisinden derlenecek aday. Bu dizide bulunmayan bir değer 400 döndürür.
Name
name
Type
string
Description
Görev için en fazla 100 karakterlik bir ad. Görevin name alanında geri döner. Daha uzun bir ad 400 döndürür.

`options`

İsteğe bağlı geometri ayarları. Her alanın kalibre edilmiş bir varsayılanı vardır, bu yüzden yalnızca değiştirmek istediğiniz alanları gönderin.

Name
base_model
Type
string
varsayılan cherry-mx-1x1-r1
Description
Üzerine inşa edilecek keycap tabanı. Tek değer cherry-mx-1x1-r1'dir, standart bir Cherry MX profil 1u keycap. Özel boyutlar desteklenmez ve başka herhangi bir değer 400 döndürür.
Name
head_size_mm
Type
number
varsayılan 23
Description
Kafanın en uzun boyutu boyunca ölçülen boyutu, milimetre cinsinden, 10 ile 40 arasında. Meshy, en uzun boyutu bu değerle eşleşecek şekilde kafayı ölçeklendirir. Aralık dışındaki bir değer 400 döndürür.
Yaklaşık 32.9'un üzerindeki bir değer için Meshy, kafanın tabanın koruyucu ayak izi sınırına sığması için boyutu küçültebilir. Kafa bu durumda istediğinizden daha küçük çıkabilir. Görev nesnesi, Meshy'nin uyguladığı boyutu döndürmez. Bunu kontrol etmek için, modeldeki keycap-head ağının sınırlayıcı kutusunu ölçün.
Name
vertical_offset_mm
Type
number
varsayılan 0
Description
Meshy kafayı tabana oturtmadan önce kafaya uygulanacak dikey ofset, milimetre cinsinden, -5 ile 5 arasında. Aralık dışındaki bir değer 400 döndürür.

Döndürülenler

result alanı, yeni derleme görevinin ID'sini tutar. status SUCCEEDED olana kadar görevi alın veya onu yayınlayın (stream). Ardından GLB dosyasını model_urls.glb'den ve OBJ paketini model_urls.obj_zip'den indirin.

Meshy, GLB dosyasını ve OBJ paketini milimetre cinsinden gerçek dünya ölçeğinde dışa aktarır. Her ikisi de Y-yukarı koordinat sistemi kullanır ve keycap'in ön yüzü +Z yönüne bakar.

Hata modları

Name
400 - Bad Request
Description
İstek çalıştırılamıyor. Örneğin:
- input_task_id eksik veya geçerli bir görev ID'si değil.
- Prototip görevinin durumu SUCCEEDED değil. Hâlâ çalışıyorsa bekleyip tekrar deneyin. Başarısız olduysa veya iptal edildiyse, yeni bir prototip görevi oluşturun.
- Prototip görevi başarılı oldu ancak hiç adayı yok. Yeni bir prototip görevi oluşturun.
- candidate_id eksik veya prototip görevinin candidate_ids dizisinde yok. O diziden bir değer gönderin.
- options içindeki bir alan aralık dışında veya base_model kullanılabilir bir değer değil.
Hata mesajı hangi sorunu bulduğunu belirtir.
Name
401 - Unauthorized
Description
API anahtarı eksik veya geçersiz. Authorization başlığını kontrol edin.
Name
402 - Payment Required
Description
Bunlardan biri geçerlidir:
- Hesapta yeterli kredi yok.
- API anahtarı, çalışma alanı veya üye kredi limitine ulaştı.
- Hesap ücretsiz plandadır.
Kredilerinizi ve planınızı kontrol edin, ardından tekrar deneyin.
Name
404 - Not Found
Description
input_task_id, hesabınızın API ile oluşturduğu herhangi bir Keycap prototip göreviyle eşleşmiyor. Web uygulamasında yapılmış bir prototip de 404 döndürür. Bir prototip oluşturma yanıtından gelen result ID'sini gönderin.
Name
429 - Too Many Requests
Description
Bu 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ı.
- Çok fazla göreviniz kuyruğa alınmış veya çalışıyor. Bazılarının bitmesini bekleyip tekrar deneyin.
- Kredisi kalmamış sınırsız bir planda, kredisiz çalıştırılabilecek görev sayısına ulaştınız. Bir görevin bitmesini bekleyin veya kredi ekleyin.
Name
500 - Internal Server Error
Description
Meshy, bir sunucu hatası nedeniyle görevi oluşturamadı. Meshy, tahsil ettiği kredileri iade eder. İsteği tekrar deneyin.

GET/openapi/creative-lab/keycap/v1/(prototype|build)/:id

Bir Keycap görevini al

Bir prototype veya build görevini döndürür. Yol, görevin aşamasıyla eşleşmelidir. /prototype/:id üzerinden istenen bir build görevi 404 döndürür ve /build/:id üzerinden istenen bir prototype görevi için de aynısı geçerlidir.

Alanlar için Keycap prototype görev nesnesi ve Keycap build görev nesnesi bölümlerine bakın.

Request

GET

/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}

Build Response

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?Expires=***"
  }
}

Parametreler

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

Dönüş Değerleri

Yoldaki aşamayla eşleşen prototype görev nesnesi veya build görev nesnesi.

Hata durumları

Name
400 - Bad Request
Description
id geçerli bir görev ID'si değil. Oluşturma yanıtındaki result ID'sini gönderin.
Name
403 - Forbidden
Description
Ekibinizde IP Filtering özelliği açık ve Meshy, prototype görevinin görselini üçüncü taraf fikri mülkiyeti ihlal ediyor olarak işaretledi. Build görevleri ve Enterprise plandaki ekipler bu hatayı almaz. Kullanım haklarına sahip olduğunuz bir görselden prototype görevi oluşturun.
Name
404 - Not Found
Description
Bu ID'ye sahip hiçbir Keycap görevi hesabınıza ait değil veya görevin aşaması yolla eşleşmiyor. ID'yi kontrol edin ve görevle eşleşmesi için /prototype veya /build kullanın.
Name
500 - Internal Server Error
Description
Meshy fikri mülkiyet kontrolünü çalıştıramadı. İsteği yeniden deneyin.

DELETE/openapi/creative-lab/keycap/v1/(prototype|build)/:id

Keycap görevini sil

Bir Keycap görevini iptal eder. PENDING durumundaki bir görevi iptal etmek, kredilerini iade eder. IN_PROGRESS durumundaki bir görev, bir işçi (worker) zaten başlatmış olduğundan, iade yapılmadan iptal edilir. Nihai bir durumdaki (SUCCEEDED, FAILED veya CANCELED) bir görev iptal edilemez.

Yol, görevin aşamasıyla eşleşmelidir. Örneğin, bir build görevinin ID'siyle /prototype/:id üzerinde DELETE çağırmak 404 döndürür.

Request

DELETE

/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -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 ID'si.

Dönüş değerleri

204 No Content, boş bir gövdeyle birlikte.

Hata modları

Name
400 - Bad Request
Description
Şunlardan biri geçerlidir:
- id geçerli bir görev ID'si değil. Oluşturma yanıtındaki result ID'sini gönderin.
- Görev zaten nihai bir duruma sahip (SUCCEEDED, FAILED veya CANCELED), bu yüzden iptal edilemez.
Name
404 - Not Found
Description
Bu ID'ye sahip bir Keycap görevi hesabınıza ait değil ya da görevin aşaması yolla eşleşmiyor. ID'yi kontrol edin ve görevle eşleşmesi için /prototype veya /build kullanın.
Name
500 - Internal Server Error
Description
Meshy, görevi iptal ederken bir sunucu hatasıyla karşılaştı, bu yüzden görev iptal edilmiş olabilir veya olmayabilir. Yeniden denemeden önce status değerini kontrol etmek için görevi alın.

GET/openapi/creative-lab/keycap/v1/(prototype|build)/:id/stream

Bir Keycap görevini akış olarak alma

Bir Keycap görevinin güncellemelerini Server-Sent Events (SSE) olarak akış halinde gönderir. Yol, görevin aşamasıyla eşleşmelidir. Eşleşmezse, örneğin bir build görevinin ID'si /prototype/:id/stream adresinde kullanılırsa, akış status_code: 404 ile bir error olayı gönderir ve kapanır.

Request

GET

/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/stream

curl -N https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
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": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***"
  }
}

Parametreler

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

Dönüş Değerleri

prototype veya build görev nesnelerinin bir akışı. Her olay, Bir Keycap görevini al tarafından döndürüldüğü ş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.

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

GET/openapi/creative-lab/keycap/v1/(prototype|build)

Keycap görevlerini listele

Tek bir aşamaya ait Keycap görevlerinizi, bir seferde bir sayfa olmak üzere döndürür. Yol (path), aşamayı seçer. /prototype yalnızca prototip görevlerini, /build ise yalnızca derleme (build) görevlerini döndürür.

Request

GET

/openapi/creative-lab/keycap/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "type": "creative-lab-keycap-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1753142456000,
    "started_at": 1753142460000,
    "finished_at": 1753142516000,
    "expires_at": 1753401716000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 12,
    "image_urls": [
      "https://assets.meshy.ai/***/design-1.png?Expires=***"
    ],
    "candidate_ids": [
      "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
    ]
  }
]

Yol parametreleri

Name
stage
Type
path
Zorunlu
Description
Listelenecek aşama, prototype veya build.

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: önce en yeni
- +created_at: önce en eski

Döndürülenler

Yoldaki aşamaya karşılık gelen bir prototip görev nesnesi veya derleme görev nesnesi dizisi.

Keycap prototip görev nesnesi

Bir prototip görevi, bir fotoğraftan tamamlanmış keycap'in tek bir görüntüsünü üretir. Tasarımı 3D bir keycap'e dönüştürmek için görevin kimliğini build uç noktasına input_task_id olarak, candidate_ids girdisini de candidate_id olarak geçirin.

Özellikler

Example Keycap Prototype Task Object

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}

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-keycap-prototype.
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: sırada bekliyor
- IN_PROGRESS: sonuç oluşturuluyor
- 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 değerindedir.
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 görevi başlattığı zaman, Unix milisaniye cinsinden. O zamana kadar null.
Name
finished_at
Type
timestamp
Description
Görevin kesin bir duruma ulaştığı zaman, Unix milisaniye cinsinden. O zamana kadar null.
Name
expires_at
Type
timestamp
Description
Görevin sonucunun süresinin dolduğu zaman, Unix milisaniye cinsinden. Bu, finished_at'ten 3 gün sonrası veya görev bitene kadar created_at'ten 3 gün sonrasıdır. API sonuçlarını süresiz olarak saklayan Kurumsal 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 sıradaki konumu. 1, bir sonraki sırada başlayacağı anlamına gelir. Görev sıradan çıktı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
Herhangi bir iade sonrasında görev için tahsil edilen kredi sayısı. Hata döndüren bir istekten ücret alınmaz. 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 ücreti 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
image_urls
Type
array of strings
Description
Tamamlanmış keycap'in görüntüsü için indirme URL'leri. Görev başarılı olduktan sonra dizide bir URL bulunur, o zamana kadar boştur. image_urls[i], candidate_ids[i] içindeki adayı gösterir.
Bu URL'ler görüntüleme amaçlıdır. Build uç noktası bir URL değil, candidate_ids içinden bir girdi alır. Bunlar imzalı URL'lerdir, bu nedenle bunları bir Authorization başlığı olmadan alın. expires_at'e kadar geçerli kalırlar ve görevi tekrar almak aynı URL'leri döndürür.
Name
candidate_ids
Type
array of strings
Description
image_urls ile aynı sırada adayların kimlikleri. Bir adayı oluşturmak için, kimliğini build isteğinde candidate_id olarak gönderin. Bu kimliklerin biçimine güvenmeyin.

Keycap build görevi nesnesi

Bir build görevi, başarılı olmuş bir prototip görevinden ve onun adaylarından birinden dokulu 3D keycap üretir. 3D modeli oluşturur, renklendirir, keycap tabanına oturtup keser, ardından keycap'i birleştirip dışa aktarır.

Özellikler

Example Keycap Build Task Object

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?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-keycap-build.
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: nihai, sonuçla birlikte
- FAILED: nihai, nedeni task_error içinde
- CANCELED: nihai, sonuç yok
Name
progress
Type
integer
Description
Yapılan 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 görevi başlattığı zaman, Unix milisaniye cinsinden. O ana kadar null.
Name
finished_at
Type
timestamp
Description
Görevin nihai duruma ulaştığı zaman, Unix milisaniye cinsinden. O ana kadar null.
Name
expires_at
Type
timestamp
Description
Görevin sonucunun süresinin dolacağı zaman, Unix milisaniye cinsinden. Bu, finished_at değerinden 3 gün sonrası veya görev bitene kadar created_at değerinden 3 gün sonrasıdır. API sonuçlarını süresiz olarak saklayan Enterprise hesaplar için bu, yaklaşık 100 yıl sonrasıdır. Bkz. Varlık saklama.
Name
preceding_tasks
Type
integer
Description
Görevin PENDING durumundayken kuyruktaki konumu. 1, bir sonraki sırada başlayacağı anlamına gelir. Görev kuyruktan çıktıktan sonra 0, liste sonuçlarında ise her zaman 0.
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
Olası bir iade sonrasında görev için tahsil edilen kredi sayısı. Hata döndüren bir istekten ücret alınmaz. Başarısız bir görev 0 değerindedir, çünkü Meshy bunu iade eder. İptal etme, bir görevi yalnızca PENDING durumundayken iade eder. Meshy tahsilatı okuyamazsa, bir get ya da 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 tekrar deneyin.
Name
model_urls
Type
object
Description
3D model için indirme URL'leri. Meshy, GLB dosyasını ve OBJ paketini gerçek dünya ölçeğinde milimetre cinsinden, Y yukarı eksenli ve keycap'in önü +Z'ye bakacak şekilde dışa aktarır.
Modelde keycap-head ve keycap-base adlı ağlar bulunur. Meshy taban için bir desen doldurmaya geri döndüğünde, modelde stem boşluğu için bir keycap-base-interior ağı da bulunur. Modelin tam olarak iki ağa sahip olduğunu varsaymayın.
Bunlar imzalı URL'lerdir, bu yüzden bunları bir Authorization başlığı olmadan alın. expires_at değerine kadar geçerli kalırlar ve o zamandan önce görevi tekrar almak aynı URL'leri döndürür. Süresi dolmuş bir URL yenilenemez, bu yüzden dosyaları süresi dolmadan indirip saklayın.
- Name
  glb
  Type
  string
  Description
  Dokulu GLB dosyası için indirme URL'si, model.glb.
- Name
  obj_zip
  Type
  string
  Description
  OBJ paketi için indirme URL'si; model.obj, model.mtl ve model.mtl'in kullandığı PNG dokularını içeren bir ZIP dosyası. Düz renkli bir tabanla, tek doku keycap-head.png'dir. Desenli bir tabanla, ZIP dosyasında ayrıca keycap-base.png de bulunur.
Name
process_image_urls
Type
object
Description
Build'in adımlarından elde edilen görüntüler için türe göre anahtarlanmış indirme URL'leri. model_urls gibi, bunlar da imzalı URL'lerdir, bu yüzden bunları bir Authorization başlığı olmadan alın. expires_at değerine kadar geçerli kalırlar ve görevi tekrar almak aynı URL'leri döndürür.
Şu anahtarlara sahip olabilir:
- head_design: build'in 3D'ye dönüştürdüğü, seçilen adayın tasarım görüntüsü. Her zaman mevcuttur.
- composite: build'in tabanı boyadığı, seçilen aday için tamamlanmış keycap'in görüntüsü. Eksik olabilir.
- base_canvas: boyanmış keycap tabanı. Eksik olabilir.
Meshy anahtarlar ekleyebilir, bu yüzden tanımadığınız bir anahtarı yok sayın.

Uçtan uca örnek

Bu örnek tüm akışı çalıştırır:

Bir fotoğraftan prototip görevi oluşturun.
status değeri SUCCEEDED olana kadar görevi sorgulayın.
candidate_ids içinden bir aday seçin.
Bu adayla bir build görevi oluşturun.
status değeri SUCCEEDED olana kadar build görevini sorgulayın.
GLB dosyasını ve OBJ paketini model_urls üzerinden indirin.

Bu örnek ilk adayı seçer. Uygulamanızda, image_urls girişlerini kullanıcılarınıza gösterin ve seçim yapmalarına izin verin. Seçilen bir görüntünün image_urls içindeki indeksi, candidate_ids içindeki kimliğinin indeksidir.

Complete flow

POST

/openapi/creative-lab/keycap/v1

#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Point IMAGE_PATH at a local photo, or IMAGE_URL at a public one:
#   export MESHY_API_KEY=msy_...
#   export IMAGE_PATH=./portrait.jpg          # or: export IMAGE_URL=https://...
: "${MESHY_API_KEY:?export MESHY_API_KEY first}"
if [[ -z "${IMAGE_PATH:-}" && -z "${IMAGE_URL:-}" ]]; then
  echo "export IMAGE_PATH (local file) or IMAGE_URL (public url) first" >&2
  exit 1
fi

BASE="https://api.meshy.ai/openapi/creative-lab/keycap/v1"
AUTH="Authorization: Bearer $MESHY_API_KEY"

# api METHOD URL [curl args...] -> prints the response body, non-zero on failure.
# Note we do not use -f/--fail: it discards the body, and the body is the only
# place the reason appears.
api() {
  local method=$1 url=$2 out http_code body
  shift 2
  out=$(curl --silent --show-error --max-time 60 --write-out $'\n%{http_code}' \
    -X "$method" "$url" -H "$AUTH" "$@") || return 1
  http_code=${out##*$'\n'}
  body=${out%$'\n'*}
  if ((http_code >= 400)); then
    echo "HTTP $http_code for $url: $body" >&2
    return 1
  fi
  printf '%s' "$body"
}

# Each task gets its own 40-minute budget.
poll() {
  local kind=$1 id=$2 delay=5 task_status deadline
  deadline=$(($(date +%s) + 2400))
  while :; do
    if (($(date +%s) >= deadline)); then
      echo "gave up waiting for $kind $id" >&2
      return 1
    fi
    task_status=$(api GET "$BASE/$kind/$id" | jq -r '.status')
    echo "$kind: $task_status"
    case "$task_status" in
    SUCCEEDED) return 0 ;;
    FAILED | CANCELED) return 1 ;;
    esac
    sleep "$delay"
    delay=$((delay * 2 > 30 ? 30 : delay * 2))
  done
}

# Build the request body in a file. A base64 data URI must never go on the
# command line or into an exported variable - a photo of any real size will
# exceed the OS argument limit.
BODY=$(mktemp)
trap 'rm -f "$BODY"' EXIT
if [[ -n "${IMAGE_PATH:-}" ]]; then
  # Declare the real type: the API accepts JPEG, PNG and WebP.
  case "$(printf '%s' "${IMAGE_PATH##*.}" | tr 'A-Z' 'a-z')" in
    png) MIME=image/png ;;
    webp) MIME=image/webp ;;
    *) MIME=image/jpeg ;;
  esac
  {
    printf '{"image_url":"data:%s;base64,' "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  printf '{"image_url":"%s"}' "$IMAGE_URL" >"$BODY"
fi

# 1. Create the prototype task
PROTO_ID=$(api POST "$BASE/prototype" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 2. Wait for the design render
poll prototype "$PROTO_ID"

# 3. Pick a candidate (first one here; show image_urls to a user in production)
CANDIDATE_ID=$(api GET "$BASE/prototype/$PROTO_ID" | jq -r '.candidate_ids[0]')

# 4. Create the build task
jq -n --arg p "$PROTO_ID" --arg c "$CANDIDATE_ID" \
  '{input_task_id: $p, candidate_id: $c}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 5. Wait for the model (a build usually takes 3-7 minutes)
poll build "$BUILD_ID"

# 6. Download the artifacts. These are signed URLs: no Authorization header,
#    and they stay valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o keycap.glb "$(jq -r '.model_urls.glb' <<<"$TASK")"
curl --silent --show-error --fail --max-time 900 \
  -o keycap-obj.zip "$(jq -r '.model_urls.obj_zip' <<<"$TASK")"
echo "Done: keycap.glb + keycap-obj.zip"