Creative Lab Keycap API

एक फोटो को दो चरणों में मैकेनिकल कीबोर्ड के लिए पूर्ण-रंगीन कस्टम कीकैप में बदलें। एक प्रोटोटाइप टास्क फोटो से तैयार कीकैप की एक इमेज जनरेट करता है। एक बिल्ड टास्क उस इमेज को एक टेक्सचर्ड 3D कीकैप मॉडल में बदल देता है। यह प्रोटोटाइप टास्क की ID को input_task_id के रूप में और इमेज की कैंडिडेट ID को candidate_id के रूप में लेता है।

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

दोनों POST endpoints को एक पेड प्लान की आवश्यकता होती है। फ्री-प्लान अकाउंट से की गई रिक्वेस्ट 402 रिटर्न करती है।

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

Keycap प्रोटोटाइप टास्क बनाएं

एक फोटो से तैयार keycap की एक इमेज जनरेट करता है। टास्क के image_urls में इमेज होती है, और candidate_ids में इसकी ID होती है, हर एक में एक एंट्री के साथ। अगर आपको डिज़ाइन पसंद नहीं आता, तो एक और प्रोटोटाइप टास्क बनाएं। Meshy हर प्रोटोटाइप टास्क के लिए अलग से चार्ज करता है।

3D keycap बनाने के लिए, इस टास्क की ID को build endpoint में input_task_id के रूप में पास करें, और candidate_ids की एंट्री को candidate_id के रूप में पास करें। टास्क के फील्ड्स के लिए, The Keycap prototype task object देखें।

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

पैरामीटर

Name
image_url
Type
string
आवश्यक
Description
keycap डिज़ाइन में बदलने के लिए फोटो, एक पब्लिक URL या data URI के रूप में (data:image/jpeg;base64,<your base64-encoded image data>)।
इमेज अधिकतम 20 MB (20,000,000 बाइट्स) की JPG, JPEG, PNG, या WebP फाइल होनी चाहिए। हर साइड कम से कम 32 पिक्सल की होनी चाहिए, और इमेज में कुल मिलाकर अधिकतम 178,956,970 पिक्सल हो सकते हैं। इन सीमाओं से बाहर की इमेज 400 रिटर्न करती है।
Meshy फॉर्मेट को इमेज डेटा से डिटेक्ट करता है, न कि URL में फाइल एक्सटेंशन से। बिना एक्सटेंशन वाला URL भी काम करता है, और Meshy HTTP रीडायरेक्ट्स को फॉलो करता है। Meshy EXIF ओरिएंटेशन लागू करता है, इसलिए घुमाई गई फोन फोटो उसी तरह आती है जैसी वह दिखती है।
एक data URI बेस64-एन्कोडेड होनी चाहिए और एक इमेज टाइप के साथ, जैसे data:image/png;base64,..., और डिकोड की गई इमेज JPEG, PNG, या WebP होनी चाहिए। 20 MB की सीमा डिकोड की गई इमेज पर लागू होती है, इसलिए base64 टेक्स्ट लगभग एक-तिहाई बड़ा हो सकता है।
Name
name
Type
string
Description
टास्क के लिए एक नाम, अधिकतम 100 कैरेक्टर तक। यह टास्क के name फील्ड में वापस आता है। इससे लंबा नाम 400 रिटर्न करता है।
Name
remove_background
Type
boolean
डिफ़ॉल्ट false
Description
क्या प्रोटोटाइप इमेज से बैकग्राउंड हटाना है। true एक ट्रांसपेरेंट RGBA PNG रिटर्न करता है, जिससे आप keycap को किसी भी बैकग्राउंड पर रख सकते हैं। अगर Meshy बैकग्राउंड नहीं हटा पाता, तो यह बैकग्राउंड के साथ इमेज रिटर्न करता है, और टास्क फिर भी सफल होता है।
हेड डिज़ाइन, जिसे build 3D में बदलता है, दोनों ही स्थितियों में अपना बैकग्राउंड बनाए रखता है। Build, image_urls की इमेज से keycap बेस पेंट करता है, अगर आपने true भेजा हो तो उसके बैकग्राउंड के बिना। Build उस इमेज को process_image_urls.composite के रूप में रिटर्न करता है।

रिटर्न वैल्यू

result फील्ड में नए प्रोटोटाइप टास्क की ID होती है। टास्क प्राप्त करें या इसे स्ट्रीम करें जब तक status, SUCCEEDED न हो जाए। फिर ID को build endpoint में input_task_id के रूप में पास करें, और candidate_ids की एंट्री को candidate_id के रूप में पास करें।

फेल्यर मोड्स

Name
400 - Bad Request
Description
रिक्वेस्ट नहीं चल सकती। उदाहरण के लिए:
- image_url गायब है।
- इमेज JPG, JPEG, PNG, या WebP फाइल नहीं है।
- इमेज बहुत छोटी है, 20 MB से ज़्यादा है, या अधिकतम पिक्सल काउंट से ज़्यादा है।
- Meshy इमेज डाउनलोड नहीं कर सकता, उदाहरण के लिए क्योंकि URL 404 रिटर्न करता है या टाइम आउट हो जाता है।
- data URI वैलिड base64 नहीं है।
- इमेज को NSFW के रूप में फ़्लैग किया गया था।
एरर मैसेज बताता है कि कौन सी समस्या मिली। रिक्वेस्ट ठीक करें, फिर इसे दोबारा भेजें।
Name
401 - Unauthorized
Description
API की गायब है या अमान्य है। Authorization हेडर जांचें।
Name
402 - Payment Required
Description
इनमें से कोई एक लागू होता है:
- अकाउंट में पर्याप्त क्रेडिट नहीं हैं।
- API की, वर्कस्पेस, या मेंबर अपनी क्रेडिट लिमिट तक पहुंच गया है।
- अकाउंट फ्री प्लान पर है।
अपने क्रेडिट और प्लान जांचें, फिर दोबारा कोशिश करें।
Name
403 - Forbidden
Description
आपकी टीम ने IP Filtering ऑन कर रखी है, और Meshy ने इमेज को थर्ड-पार्टी इंटेलेक्चुअल प्रॉपर्टी के लिए फ़्लैग किया है। ऐसी इमेज भेजें जिसे इस्तेमाल करने का आपको अधिकार है।
Name
429 - Too Many Requests
Description
इनमें से कोई एक लिमिट पूरी हो गई थी:
- आपने अपनी रेट लिमिट की अनुमति से ज़्यादा रिक्वेस्ट भेजीं। कुछ सेकंड रुकें, फिर दोबारा कोशिश करें। Rate limits देखें।
- आपके बहुत सारे टास्क क्यू में हैं या चल रहे हैं। कुछ के पूरा होने का इंतज़ार करें, फिर दोबारा कोशिश करें।
- अनलिमिटेड प्लान पर बिना किसी बचे क्रेडिट के, आप बिना क्रेडिट चल सकने वाले टास्क की संख्या तक पहुंच गए हैं। किसी टास्क के पूरा होने का इंतज़ार करें, या क्रेडिट जोड़ें।
Name
500 - Internal Server Error
Description
Meshy को एक सर्वर एरर मिला, उदाहरण के लिए क्योंकि कंटेंट moderation या इंटेलेक्चुअल प्रॉपर्टी जांच नहीं चल पाई, या Meshy इमेज को स्टोर नहीं कर पाया। Meshy टास्क नहीं बनाता, और उसने जो भी क्रेडिट चार्ज किए थे उन्हें रिफंड कर देता है। रिक्वेस्ट दोबारा कोशिश करें।

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

Keycap बिल्ड टास्क बनाएँ

यह एक सफल प्रोटोटाइप टास्क और उसके किसी एक कैंडिडेट से टेक्स्चर्ड 3D keycap जनरेट करता है। इसके फ़ील्ड के लिए, देखें The Keycap build task object.

एक बिल्ड टास्क हर चरण चलाता है। यह डिज़ाइन से 3D मॉडल जनरेट करता है और उसे रंग देता है। फिर यह मॉडल को एक कैलिब्रेटेड डिफ़ॉल्ट पोज़ में keycap बेस पर बैठाता और काटता है, ताकि आपको इसे हाथ से समायोजित न करना पड़े। अंत में, यह keycap को असेंबल करता है और फ़ाइलें एक्सपोर्ट करता है। एक बिल्ड में आमतौर पर 3 से 7 मिनट लगते हैं।

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

पैरामीटर

Name
input_task_id
Type
string
आवश्यक
Description
बनाए जाने वाले प्रोटोटाइप टास्क का ID। यह आपके अकाउंट द्वारा POST /openapi/creative-lab/keycap/v1/prototype से बनाया गया टास्क होना चाहिए, जिसका स्टेटस SUCCEEDED हो।
ऐसा ID जो API से बने आपके Keycap प्रोटोटाइप टास्क में से कोई नहीं है, 404 लौटाता है, जिसमें वेब ऐप में बना प्रोटोटाइप भी शामिल है।
Name
candidate_id
Type
string
आवश्यक
Description
बनाया जाने वाला कैंडिडेट, प्रोटोटाइप टास्क के candidate_ids array से। ऐसा वैल्यू जो उस array में नहीं है, 400 लौटाता है।
Name
name
Type
string
Description
टास्क के लिए एक नाम, 100 अक्षरों तक। यह टास्क के name फ़ील्ड में वापस आता है। इससे लंबा नाम 400 लौटाता है।

`options`

वैकल्पिक ज्यामिति सेटिंग्स। हर फ़ील्ड का एक कैलिब्रेटेड डिफ़ॉल्ट है, इसलिए केवल वही फ़ील्ड भेजें जिन्हें आप बदलना चाहते हैं।

Name
base_model
Type
string
डिफ़ॉल्ट cherry-mx-1x1-r1
Description
जिस keycap बेस पर बिल्ड करना है। एकमात्र वैल्यू cherry-mx-1x1-r1 है, जो एक स्टैंडर्ड Cherry MX प्रोफ़ाइल 1u keycap है। कस्टम साइज़ सपोर्टेड नहीं हैं, और कोई भी अन्य वैल्यू 400 लौटाती है।
Name
head_size_mm
Type
number
डिफ़ॉल्ट 23
Description
हेड का उसके सबसे लंबे आयाम के साथ साइज़, मिलीमीटर में, 10 से 40 तक। Meshy हेड को इस तरह स्केल करता है कि उसका सबसे लंबा आयाम इस वैल्यू से मेल खाए। रेंज से बाहर की वैल्यू 400 लौटाती है।
लगभग 32.9 से अधिक वैल्यू के लिए, Meshy साइज़ को कम कर सकता है ताकि हेड बेस की प्रोटेक्टिव फ़ुटप्रिंट सीमा में फ़िट हो सके। ऐसे में हेड आपके अनुरोध से छोटा निकल सकता है। टास्क ऑब्जेक्ट वह साइज़ नहीं लौटाता जो Meshy ने लागू किया। इसे जाँचने के लिए, मॉडल में keycap-head मेश का बाउंडिंग बॉक्स मापें।
Name
vertical_offset_mm
Type
number
डिफ़ॉल्ट 0
Description
वर्टिकल ऑफ़सेट जो Meshy द्वारा हेड को बेस पर बैठाने से पहले लागू किया जाता है, मिलीमीटर में, -5 से 5 तक। रेंज से बाहर की वैल्यू 400 लौटाती है।

रिटर्न

result फ़ील्ड में नए बिल्ड टास्क का ID होता है। टास्क प्राप्त करें या इसे स्ट्रीम करें जब तक status SUCCEEDED न हो जाए। फिर model_urls.glb से GLB फ़ाइल और model_urls.obj_zip से OBJ बंडल डाउनलोड करें।

Meshy GLB फ़ाइल और OBJ बंडल को वास्तविक-दुनिया के पैमाने पर, मिलीमीटर में एक्सपोर्ट करता है। दोनों एक Y-up कोऑर्डिनेट सिस्टम का उपयोग करते हैं, जिसमें keycap का अगला हिस्सा +Z की ओर होता है।

विफलता के मामले

Name
400 - Bad Request
Description
अनुरोध नहीं चल सकता। उदाहरण के लिए:
- input_task_id गायब है या मान्य टास्क ID नहीं है।
- प्रोटोटाइप टास्क का स्टेटस SUCCEEDED नहीं है। यदि यह अभी भी चल रहा है, तो प्रतीक्षा करें और पुनः प्रयास करें। यदि यह विफल हुआ या कैंसल हुआ, तो एक नया प्रोटोटाइप टास्क बनाएँ।
- प्रोटोटाइप टास्क सफल रहा लेकिन उसमें कोई कैंडिडेट नहीं है। एक नया प्रोटोटाइप टास्क बनाएँ।
- candidate_id गायब है, या प्रोटोटाइप टास्क के candidate_ids में नहीं है। उस array से एक वैल्यू भेजें।
- options में कोई फ़ील्ड रेंज से बाहर है, या base_model उपलब्ध वैल्यू नहीं है।
एरर मैसेज बताता है कि कौन-सी समस्या मिली।
Name
401 - Unauthorized
Description
API की गायब है या अमान्य है। Authorization हेडर जाँचें।
Name
402 - Payment Required
Description
इनमें से कोई एक लागू होता है:
- अकाउंट के पास पर्याप्त क्रेडिट नहीं हैं।
- API की, वर्कस्पेस, या सदस्य अपनी क्रेडिट सीमा तक पहुँच गया।
- अकाउंट फ़्री प्लान पर है।
अपने क्रेडिट और प्लान की जाँच करें, फिर पुनः प्रयास करें।
Name
404 - Not Found
Description
input_task_id आपके अकाउंट द्वारा API से बनाए गए किसी भी Keycap प्रोटोटाइप टास्क से मेल नहीं खाता। वेब ऐप में बनाया गया प्रोटोटाइप भी 404 लौटाता है। प्रोटोटाइप बनाने के रिस्पॉन्स से result ID भेजें।
Name
429 - Too Many Requests
Description
इनमें से कोई एक सीमा पहुँच गई:
- आपने अपनी रेट लिमिट से अधिक अनुरोध भेजे। कुछ सेकंड प्रतीक्षा करें, फिर पुनः प्रयास करें। देखें Rate limits.
- आपके बहुत अधिक टास्क कतार में हैं या चल रहे हैं। कुछ के पूरा होने की प्रतीक्षा करें, फिर पुनः प्रयास करें।
- किसी अनलिमिटेड प्लान पर जिसमें कोई क्रेडिट शेष नहीं है, आप बिना क्रेडिट के चल सकने वाले टास्क की संख्या तक पहुँच गए। किसी टास्क के पूरा होने की प्रतीक्षा करें, या क्रेडिट जोड़ें।
Name
500 - Internal Server Error
Description
सर्वर एरर के कारण Meshy टास्क नहीं बना सका। Meshy ने जो भी क्रेडिट चार्ज किए थे, उन्हें रिफ़ंड कर देता है। अनुरोध को पुनः प्रयास करें।

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

Keycap टास्क प्राप्त करें

यह एक prototype या build टास्क लौटाता है। पाथ, टास्क के स्टेज से मेल खाना चाहिए। /prototype/:id के माध्यम से अनुरोध किया गया build टास्क 404 लौटाता है, और इसी तरह /build/:id के माध्यम से अनुरोध किया गया prototype टास्क भी 404 लौटाता है।

फ़ील्ड के लिए, The Keycap prototype task object और The Keycap build task object देखें।

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

पैरामीटर

Name
id
Type
path
Description
क्रिएट रिस्पॉन्स से मिला टास्क ID।

रिटर्न

पाथ में दिए गए स्टेज से मेल खाता prototype task object या build task object।

विफलता मोड

Name
400 - Bad Request
Description
id एक वैध टास्क ID नहीं है। क्रिएट रिस्पॉन्स से मिला result ID भेजें।
Name
403 - Forbidden
Description
आपकी टीम पर IP Filtering चालू है, और Meshy ने prototype टास्क की इमेज को थर्ड-पार्टी इंटेलेक्चुअल प्रॉपर्टी के रूप में फ़्लैग किया है। build टास्क और Enterprise प्लान वाली टीमों को यह एरर नहीं मिलता। ऐसी इमेज से prototype टास्क बनाएं जिसका उपयोग करने का आपको अधिकार हो।
Name
404 - Not Found
Description
इस ID वाला कोई Keycap टास्क आपके अकाउंट से संबंधित नहीं है, या टास्क का स्टेज पाथ से मेल नहीं खाता। ID की जांच करें, और टास्क से मेल खाने के लिए /prototype या /build का उपयोग करें।
Name
500 - Internal Server Error
Description
Meshy इंटेलेक्चुअल प्रॉपर्टी जांच नहीं चला सका। अनुरोध को फिर से प्रयास करें।

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

एक Keycap टास्क को डिलीट करें

एक Keycap टास्क को कैंसिल करता है। किसी PENDING टास्क को कैंसिल करने पर उसके क्रेडिट रिफंड हो जाते हैं। एक IN_PROGRESS टास्क बिना रिफंड के कैंसिल होता है, क्योंकि कोई वर्कर पहले ही उसे शुरू कर चुका होता है। जिस टास्क की फाइनल स्टेटस (SUCCEEDED, FAILED, या CANCELED) हो, उसे कैंसिल नहीं किया जा सकता।

पाथ, टास्क के स्टेज से मेल खाना चाहिए। उदाहरण के लिए, किसी build टास्क की ID के साथ /prototype/:id पर DELETE करने पर 404 रिटर्न होता है।

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

Path parameters

Name
id
Type
path
Description
कैंसिल किए जाने वाले टास्क की ID।

रिटर्न वैल्यू

खाली बॉडी के साथ 204 No Content।

फेलियर मोड्स

Name
400 - Bad Request
Description
इनमें से कोई एक लागू होता है:
- id एक वैध टास्क ID नहीं है। क्रिएट रिस्पॉन्स से मिली result ID भेजें।
- टास्क की पहले से ही एक फाइनल स्टेटस है (SUCCEEDED, FAILED, या CANCELED), इसलिए इसे कैंसिल नहीं किया जा सकता।
Name
404 - Not Found
Description
आपके अकाउंट से जुड़ा इस ID का कोई Keycap टास्क नहीं है, या टास्क का स्टेज पाथ से मेल नहीं खाता। ID की जाँच करें, और टास्क से मेल खाने के लिए /prototype या /build का उपयोग करें।
Name
500 - Internal Server Error
Description
टास्क को कैंसिल करते समय Meshy को सर्वर एरर मिला, इसलिए हो सकता है कि टास्क कैंसिल हुआ हो या न हुआ हो। रिट्राई करने से पहले, उसकी status जाँचने के लिए टास्क को गेट करें।

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

एक Keycap टास्क को स्ट्रीम करें

किसी Keycap टास्क के अपडेट्स को Server-Sent Events (SSE) के रूप में स्ट्रीम करता है। पथ को टास्क के चरण (stage) से मेल खाना चाहिए। यदि यह मेल नहीं खाता, उदाहरण के लिए किसी build टास्क की ID को /prototype/:id/stream पर उपयोग करने पर, स्ट्रीम एक error इवेंट भेजती है जिसमें status_code: 404 होता है और फिर बंद हो जाती है।

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

पैरामीटर

Name
id
Type
path
Description
क्रिएट रिस्पॉन्स से मिली टास्क ID।

रिटर्न वैल्यू

prototype या build टास्क ऑब्जेक्ट्स की एक स्ट्रीम। हर इवेंट में पूरा टास्क ऑब्जेक्ट होता है, जैसा कि Get a Keycap task रिटर्न करता है। जब तक टास्क PENDING या IN_PROGRESS स्थिति में है, तब तक इसके आउटपुट फ़ील्ड्स खाली रहते हैं (null, [], या {}), और finished_at null होता है।

यदि IP Filtering टास्क के परिणाम को ब्लॉक करता है, तो स्ट्रीम उसकी जगह एक error इवेंट भेजती है, जिसमें वही status_code होता है जो एक get रिक्वेस्ट रिटर्न करती।

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

List Keycap tasks

एक बार में एक पेज, आपके एक स्टेज के Keycap tasks को रिटर्न करता है। पाथ स्टेज को चुनता है। /prototype केवल prototype tasks रिटर्न करता है, और /build केवल build tasks रिटर्न करता है।

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

Path parameters

Name
stage
Type
path
आवश्यक
Description
लिस्ट करने के लिए स्टेज, prototype या build।

Query parameters

Name
page_num
Type
integer
डिफ़ॉल्ट 1
Description
रिटर्न करने के लिए पेज, 1 से 255 तक। 0 पहला पेज रिटर्न करता है। 0 से 255 के बाहर का कोई वैल्यू 400 रिटर्न करता है।
Name
page_size
Type
integer
डिफ़ॉल्ट 10
Description
प्रति पेज tasks की संख्या, 100 तक। 101 से 255 तक का वैल्यू 100 tasks रिटर्न करता है, और 0 डिफ़ॉल्ट का उपयोग करता है। 0 से 255 के बाहर का कोई वैल्यू 400 रिटर्न करता है।
Name
sort_by
Type
string
डिफ़ॉल्ट -created_at
Description
सॉर्ट ऑर्डर।
उपलब्ध वैल्यूज़:
- -created_at: सबसे नया पहले
- +created_at: सबसे पुराना पहले

Returns

prototype task objects या build task objects का एक ऐरे, जो पाथ में दिए गए स्टेज से मेल खाता है।

कीकैप प्रोटोटाइप टास्क ऑब्जेक्ट

एक प्रोटोटाइप टास्क किसी फोटो से तैयार कीकैप की एक इमेज जनरेट करता है। डिज़ाइन को 3D कीकैप में बदलने के लिए, टास्क की ID को input_task_id के रूप में build एंडपॉइंट को पास करें, साथ ही इसकी candidate_ids एंट्री को candidate_id के रूप में पास करें।

Properties

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
टास्क ID। इसके फॉर्मैट पर निर्भर न रहें।
Name
type
Type
string
Description
टास्क टाइप, हमेशा creative-lab-keycap-prototype।
Name
name
Type
string
Description
वह name जो आपने टास्क बनाते समय भेजा था, या अगर आपने कोई नहीं भेजा तो ""।
Name
status
Type
string
Description
टास्क की स्थिति।
उपलब्ध मान:
- PENDING: कतार में प्रतीक्षारत
- IN_PROGRESS: परिणाम जनरेट किया जा रहा है
- SUCCEEDED: अंतिम, परिणाम के साथ
- FAILED: अंतिम, कारण task_error में है
- CANCELED: अंतिम, बिना किसी परिणाम के
Name
progress
Type
integer
Description
काम पूरा होने का प्रतिशत, 0 से 100 तक। जब तक टास्क शुरू नहीं होता यह 0 रहता है और सफल होने पर 100 हो जाता है।
Name
created_at
Type
timestamp
Description
टास्क बनाए जाने का समय, Unix मिलीसेकंड में।
Name
started_at
Type
timestamp
Description
जब किसी worker ने टास्क शुरू किया, वह समय, Unix मिलीसेकंड में। तब तक null रहता है।
Name
finished_at
Type
timestamp
Description
जिस समय टास्क अंतिम स्थिति पर पहुंचा, वह समय, Unix मिलीसेकंड में। तब तक null रहता है।
Name
expires_at
Type
timestamp
Description
जिस समय टास्क का परिणाम expire होता है, वह समय, Unix मिलीसेकंड में। यह finished_at के 3 दिन बाद होता है, या जब तक टास्क पूरा नहीं होता तब तक created_at के 3 दिन बाद। Enterprise अकाउंट्स के लिए, जो API परिणामों को अनिश्चित काल तक रखते हैं, यह लगभग 100 साल बाद होता है। देखें एसेट रिटेंशन।
Name
preceding_tasks
Type
integer
Description
PENDING रहते हुए कतार में टास्क की स्थिति। 1 का मतलब है कि यह अगला शुरू होगा। टास्क के कतार से निकलने के बाद 0, और लिस्ट परिणामों में हमेशा 0।
Name
task_error
Type
object
Description
टास्क क्यों विफल हुआ। जब तक status, FAILED न हो, तब तक null। देखें एरर।
Name
consumed_credits
Type
integer
Description
किसी भी रिफंड के बाद, टास्क के लिए चार्ज किए गए क्रेडिट की संख्या। एरर लौटाने वाले रिक्वेस्ट के लिए चार्ज नहीं लिया जाता। विफल टास्क के लिए यह 0 होता है, क्योंकि Meshy इसे रिफंड कर देता है। कैंसल करने पर टास्क केवल तब रिफंड होता है जब वह PENDING स्थिति में हो। अगर Meshy चार्ज नहीं पढ़ पाता, तो get या stream रिस्पॉन्स में यह फ़ील्ड छोड़ दी जाती है, और लिस्ट रिक्वेस्ट 500 लौटाता है। ऐसे में, रिक्वेस्ट को फिर से आज़माएं।
Name
image_urls
Type
array of strings
Description
तैयार कीकैप की इमेज के लिए डाउनलोड URLs। टास्क सफल होने के बाद array में एक URL होता है, और तब तक यह खाली रहता है। image_urls[i], candidate_ids[i] में मौजूद कैंडिडेट को दिखाता है।
ये URLs केवल डिस्प्ले के लिए हैं। build एंडपॉइंट, candidate_ids से एक एंट्री लेता है, न कि कोई URL। ये signed URLs हैं, इसलिए इन्हें बिना Authorization हेडर के fetch करें। ये expires_at तक वैध रहते हैं, और टास्क को फिर से प्राप्त करने पर वही URLs लौटाए जाते हैं।
Name
candidate_ids
Type
array of strings
Description
कैंडिडेट्स की IDs, image_urls जैसे ही क्रम में। किसी कैंडिडेट को बनाने के लिए, build रिक्वेस्ट में उसकी ID को candidate_id के रूप में भेजें। इन IDs के फॉर्मैट पर निर्भर न रहें।

The Keycap build task object

एक बिल्ड टास्क एक सफल प्रोटोटाइप टास्क और उसके किसी एक कैंडिडेट से टेक्सचर्ड 3D कीकैप जनरेट करता है। यह 3D मॉडल जनरेट करता है, उसे रंगता है, उसे कीकैप बेस पर बिठाता और काटता है, और फिर कीकैप को असेंबल करके एक्सपोर्ट करता है।

Properties

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
टास्क ID। इसके फॉर्मेट पर भरोसा न करें।
Name
type
Type
string
Description
टास्क का प्रकार, हमेशा creative-lab-keycap-build।
Name
name
Type
string
Description
वह name जो आपने टास्क बनाते समय भेजा था, या "" यदि आपने कोई नहीं भेजा।
Name
status
Type
string
Description
टास्क का स्टेटस।
उपलब्ध वैल्यूज़:
- PENDING: क्यू में प्रतीक्षा कर रहा है
- IN_PROGRESS: परिणाम जनरेट कर रहा है
- SUCCEEDED: अंतिम, परिणाम के साथ
- FAILED: अंतिम, कारण task_error में है
- CANCELED: अंतिम, बिना किसी परिणाम के
Name
progress
Type
integer
Description
कार्य का कितना प्रतिशत पूरा हुआ, 0 से 100 तक। जब तक टास्क शुरू नहीं होता यह 0 रहता है और सफल होने पर 100 हो जाता है।
Name
created_at
Type
timestamp
Description
टास्क बनाए जाने का समय, Unix मिलीसेकंड में।
Name
started_at
Type
timestamp
Description
जिस समय किसी वर्कर ने टास्क शुरू किया, Unix मिलीसेकंड में। तब तक null रहता है।
Name
finished_at
Type
timestamp
Description
जिस समय टास्क अंतिम स्टेटस पर पहुँचा, Unix मिलीसेकंड में। तब तक null रहता है।
Name
expires_at
Type
timestamp
Description
जिस समय टास्क का परिणाम समाप्त होता है, Unix मिलीसेकंड में। यह finished_at के 3 दिन बाद होता है, या जब तक टास्क पूरा नहीं होता तब तक created_at के 3 दिन बाद। Enterprise अकाउंट्स के लिए, जो API परिणामों को अनिश्चित काल तक रखते हैं, यह लगभग 100 वर्ष बाद होता है। देखें एसेट रिटेंशन।
Name
preceding_tasks
Type
integer
Description
जब टास्क PENDING होता है, तब क्यू में उसकी स्थिति। 1 का मतलब है कि यह अगली बार शुरू होगा। टास्क के क्यू छोड़ने के बाद 0, और लिस्ट रिजल्ट्स में हमेशा 0।
Name
task_error
Type
object
Description
टास्क क्यों विफल हुआ। जब तक status FAILED न हो, null। देखें एरर।
Name
consumed_credits
Type
integer
Description
किसी भी रिफंड के बाद, टास्क के लिए चार्ज किए गए क्रेडिट की संख्या। जो रिक्वेस्ट एरर लौटाती है उसके लिए चार्ज नहीं लिया जाता। विफल टास्क के लिए यह 0 होता है, क्योंकि Meshy उसे रिफंड कर देता है। कैंसल करने पर टास्क का रिफंड तभी होता है जब वह PENDING हो। यदि Meshy चार्ज नहीं पढ़ पाता, तो get या stream रिस्पॉन्स में यह फील्ड छोड़ दिया जाता है, और एक list रिक्वेस्ट 500 लौटाती है। ऐसी स्थिति में, रिक्वेस्ट को दोबारा करें।
Name
model_urls
Type
object
Description
3D मॉडल के लिए डाउनलोड URLs। Meshy GLB फ़ाइल और OBJ बंडल को वास्तविक दुनिया के स्केल पर मिलीमीटर में, Y-up, और कीकैप का अगला हिस्सा +Z की ओर रखते हुए एक्सपोर्ट करता है।
मॉडल में keycap-head और keycap-base नाम के मेश होते हैं। जब Meshy बेस के लिए पैटर्न फिल पर वापस जाता है, तो मॉडल में स्टेम कैविटी के लिए एक keycap-base-interior मेश भी होता है। यह न मानें कि मॉडल में ठीक दो ही मेश होंगे।
ये साइन किए गए URLs हैं, इसलिए इन्हें बिना Authorization हेडर के फ़ेच करें। ये expires_at तक वैध रहते हैं, और उससे पहले टास्क को दोबारा प्राप्त करने पर वही URLs लौटते हैं। एक्सपायर हो चुके URL को रिन्यू नहीं किया जा सकता, इसलिए उससे पहले फ़ाइलों को डाउनलोड करके सुरक्षित रख लें।
- Name
  glb
  Type
  string
  Description
  टेक्सचर्ड GLB फ़ाइल, model.glb के लिए डाउनलोड URL।
- Name
  obj_zip
  Type
  string
  Description
  OBJ बंडल के लिए डाउनलोड URL, एक ZIP फ़ाइल जिसमें model.obj, model.mtl, और वे PNG टेक्सचर होते हैं जिन्हें model.mtl उपयोग करता है। सॉलिड-कलर बेस के साथ, एकमात्र टेक्सचर keycap-head.png होता है। पैटर्न वाले बेस के साथ, ZIP फ़ाइल में keycap-base.png भी होता है।
Name
process_image_urls
Type
object
Description
बिल्ड के चरणों से प्राप्त इमेजेज़ के लिए डाउनलोड URLs, जो प्रकार (kind) के अनुसार की गई हैं। model_urls की तरह, ये साइन किए गए URLs हैं, इसलिए इन्हें बिना Authorization हेडर के फ़ेच करें। ये expires_at तक वैध रहते हैं, और टास्क को दोबारा प्राप्त करने पर वही URLs लौटते हैं।
इसमें ये keys हो सकती हैं:
- head_design: चुने गए कैंडिडेट की डिज़ाइन इमेज, जिसे बिल्ड ने 3D में बदला। यह हमेशा मौजूद होती है।
- composite: चुने गए कैंडिडेट के लिए पूरी हो चुकी कीकैप की इमेज, जिससे बिल्ड ने बेस को पेंट किया। यह न हो सकती है।
- base_canvas: पेंट किया गया कीकैप बेस। यह न हो सकती है।
Meshy keys जोड़ सकता है, इसलिए जिस key को आप नहीं पहचानते उसे नज़रअंदाज़ करें।

एंड-टू-एंड उदाहरण

यह उदाहरण पूरे फ़्लो को चलाता है:

एक फ़ोटो से प्रोटोटाइप टास्क बनाएं।
टास्क को तब तक प्राप्त करें जब तक उसका status, SUCCEEDED न हो जाए।
candidate_ids में से एक कैंडिडेट चुनें।
उस कैंडिडेट के साथ एक बिल्ड टास्क बनाएं।
बिल्ड टास्क को तब तक प्राप्त करें जब तक उसका status, SUCCEEDED न हो जाए।
model_urls से GLB फ़ाइल और OBJ बंडल डाउनलोड करें।

यह उदाहरण पहला कैंडिडेट चुनता है। आपके ऐप में, image_urls की एंट्रीज़ को अपने उपयोगकर्ताओं को दिखाएं और उन्हें चुनने दें। image_urls में चुनी गई किसी इमेज का इंडेक्स, candidate_ids में उसकी ID के इंडेक्स के बराबर होता है।

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"