Creative Lab — Keycap API

किसी स्रोत फ़ोटो को दो चरणों में एक पूर्ण-रंगीन कस्टम मैकेनिकल कीबोर्ड कीकैप में बदलें: prototype आपकी इनपुट फ़ोटो से एक "फ़िनिश्ड कीकैप" डिज़ाइन रेंडर जनरेट करता है। एक बार जब आप उस रेंडर की पुष्टि कर देते हैं, तो build उसे एकल रन में टेक्सचर्ड 3D कीकैप मॉडल में बदल देता है — व्हाइट-मॉडल जनरेशन, एक कैलिब्रेटेड डिफ़ॉल्ट पोज़ पर स्वचालित सीटिंग और कटिंग, पूर्ण-मॉडल कलरिंग, और अंतिम असेंबली यह सब एक ही बिल्ड टास्क के भीतर होता है। दोनों चरण input_task_id और candidate_id के माध्यम से जुड़े हुए हैं।

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

दोनों POST endpoints के लिए एक भुगतान किए गए सब्सक्रिप्शन प्लान की आवश्यकता है। फ्री-प्लान अकाउंट्स से किए गए अनुरोधों को 402 Payment Required के साथ अस्वीकार कर दिया जाता है।

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

एक Keycap Prototype टास्क बनाएँ

सोर्स फोटो से एक फिनिश्ड-कीकैप डिज़ाइन रेंडर जनरेट करें। टास्क परिणाम में एक image_urls array होता है (फिनिश्ड कीकैप का डिस्प्ले रेंडर) और एक समानांतर candidate_ids array होता है; दोनों में एक ही एंट्री होती है। यदि परिणाम आपकी अपेक्षा के अनुरूप नहीं है तो दूसरे रेंडर के लिए इस एंडपॉइंट को फिर से कॉल करें — प्रत्येक कॉल का बिल अलग से लिया जाता है। candidate_id को prototype टास्क ID के साथ build endpoint को पास करें। रिस्पॉन्स के स्वरूप के लिए The Keycap Prototype Task Object देखें।

पैरामीटर

Name
image_url
Type
string
आवश्यक
Description
Meshy को कीकैप डिज़ाइन इमेज में बदलने के लिए सोर्स फोटो। हम फिलहाल .jpg, .jpeg, .png, और .webp फॉर्मेट सपोर्ट करते हैं।
फॉर्मेट का पता इमेज डेटा को डिकोड करके लगाया जाता है, URL के फाइल एक्सटेंशन से नहीं — बिना एक्सटेंशन वाला URL, या एक जो रीडायरेक्ट करता है, तब तक काम करता है जब तक बाइट्स किसी सपोर्टेड फॉर्मेट में डिकोड होती हैं। HTTP रीडायरेक्ट को फॉलो किया जाता है। EXIF ओरिएंटेशन को नॉर्मलाइज़ किया जाता है, ताकि घुमाई हुई फोन फोटो वैसी ही इस्तेमाल हो जैसी वह दिखती है।
सीमाएँ: प्रत्येक साइड पर कम से कम 32 पिक्सेल, कुल मिलाकर अधिकतम 178,956,970 पिक्सेल, और डाउनलोड होने के बाद अधिकतम 20,000,000 बाइट्स। Data URI के लिए यह सीमा डिकोड की गई बाइट्स पर लागू होती है, इसलिए सोर्स फाइल स्वयं उस आकार तक हो सकती है — यह base64 टेक्स्ट है जो लगभग एक तिहाई बड़ा होता है, जो आपके रिक्वेस्ट बॉडी के लिए मायने रखता है, इस सीमा के लिए नहीं। एक Data URI में image/* कंटेंट टाइप और ;base64 घोषित होना चाहिए।
इमेज देने के दो तरीके हैं:
- सार्वजनिक रूप से एक्सेस किया जा सकने वाला URL: एक URL जो सार्वजनिक इंटरनेट से एक्सेस किया जा सकता है।
- Data URI: इमेज का base64-एन्कोडेड data URI। data URI का उदाहरण: data:image/jpeg;base64,<your base64-encoded image data>.
Name
name
Type
string
Description
डिस्प्ले उद्देश्यों के लिए वैकल्पिक टास्क नाम। अधिकतम 100 अक्षर।
Name
remove_background
Type
boolean
डिफ़ॉल्ट false
Description
जब इसे true सेट किया जाता है, तो image_urls में लौटाया गया डिस्प्ले रेंडर एक पारदर्शी RGBA PNG होता है जिसमें बैकग्राउंड हटा दिया गया है, ताकि आप इसे किसी भी बैकग्राउंड पर कंपोज़िट कर सकें।
यह केवल डिस्प्ले रेंडर पर लागू होता है। build endpoint द्वारा उपयोग किया जाने वाला candidate इससे प्रभावित नहीं होता, इसलिए 3D परिणाम किसी भी स्थिति में समान रहता है।

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

रिस्पॉन्स की result प्रॉपर्टी में नए बनाए गए keycap prototype टास्क का टास्क id होता है। Get a Task एंडपॉइंट को पोल करें या stream को सब्सक्राइब करें जब तक टास्क SUCCEEDED तक न पहुँच जाए, फिर candidate_ids से एंट्री लें और उसे टास्क ID के साथ build endpoint को पास करें।

फेलियर मोड

Name
400 - Bad Request
Description
रिक्वेस्ट स्वीकार्य नहीं थी। सामान्य कारण:
- मिसिंग पैरामीटर: image_url आवश्यक है।
- अमान्य इमेज फॉर्मेट: दिया गया image_url समर्थित फॉर्मेट में नहीं है (.jpg, .jpeg, .png, .webp)।
- इमेज डाइमेंशन रेंज से बाहर: इमेज बहुत छोटी है, अधिकतम फाइल साइज़ से अधिक है, या अधिकतम पिक्सेल काउंट से अधिक है।
- अनपहुँच योग्य URL: image_url को डाउनलोड नहीं किया जा सका (404 या timeout)।
- अमान्य Data URI: base64 स्ट्रिंग malformed है।
- कंटेंट फ्लैग किया गया: इनपुट इमेज को NSFW moderation द्वारा फ्लैग किया गया था।
Name
401 - Unauthorized
Description
प्रमाणीकरण विफल रहा। कृपया अपनी API की जाँचें।
Name
402 - Payment Required
Description
खाता फ्री प्लान पर है (टास्क बनाने के लिए पेड प्लान आवश्यक है) या पर्याप्त क्रेडिट नहीं हैं।
Name
403 - Forbidden
Description
इनपुट इमेज को intellectual property moderation द्वारा फ्लैग किया गया था।
Name
429 - Too Many Requests
Description
आपने अपनी रेट लिमिट पार कर ली है।
Name
500 - Internal Server Error
Description
एक अप्रत्याशित सर्वर-साइड त्रुटि हुई — उदाहरण के लिए content-moderation सेवा अनुपलब्ध थी, इनपुट इमेज को स्टेज करना विफल रहा, या टास्क नहीं बनाया जा सका। इस स्थिति में कोई टास्क नहीं बनाया जाता, इसलिए पुनः प्रयास करना सुरक्षित है।

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

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

Create a Keycap Build Task

सफल हुए एक prototype task और उसके किसी कैंडिडेट से फाइनल टेक्सचर्ड 3D keycap मॉडल जनरेट करें। एक सिंगल build task पूरी पाइपलाइन को एंड टू एंड चलाता है — चुने गए डिज़ाइन से white-model जनरेशन, एक कैलिब्रेटेड डिफॉल्ट पोज़ का उपयोग करके keycap बेस पर ऑटोमैटिक seating और cutting (इंटरैक्टिव एडजस्टमेंट की आवश्यकता नहीं), फुल-मॉडल कलरिंग, और फाइनल असेंबली व एक्सपोर्ट। एक build आम तौर पर 3–7 मिनट लेता है, जब कई builds एक साथ चल रहे हों तो यह ऊपरी सीमा के करीब होता है। रिस्पॉन्स शेप के लिए The Keycap Build Task Object देखें।

पैरामीटर

Name
input_task_id
Type
string
आवश्यक
Description
इस्सी OpenAPI एंडपॉइंट के माध्यम से बनाए गए एक prototype task का task ID। यह prototype इसी Meshy अकाउंट द्वारा बनाया गया होना चाहिए, SUCCEEDED तक पहुँचा होना चाहिए, और कम से कम एक कैंडिडेट प्रोड्यूस किया होना चाहिए।
वेबऐप के माध्यम से बनाए गए prototype tasks स्वीकार नहीं किए जाते — build एंडपॉइंट केवल POST /openapi/creative-lab/keycap/v1/prototype द्वारा प्रोड्यूस किए गए prototype tasks को स्वीकार करता है और किसी भी अन्य स्रोत को 404 के साथ रिजेक्ट कर देता है।
Name
candidate_id
Type
string
आवश्यक
Description
बनाया जाने वाला कैंडिडेट, सफल हुए prototype task के candidate_ids array से लिया गया है। यह उस task से संबंधित होना चाहिए; कोई भी अन्य वैल्यू 400 के साथ रिजेक्ट कर दी जाती है।
Name
name
Type
string
Description
प्रदर्शन उद्देश्यों के लिए वैकल्पिक task नाम। अधिकतम 100 अक्षर।

`options`

वैकल्पिक ज्यामिति ट्यूनिंग। हर फील्ड की एक कैलिब्रेटेड डिफॉल्ट वैल्यू है — केवल उन्हीं फील्ड्स को भेजें जिन्हें आप ओवरराइड करना चाहते हैं।

Name
base_model
Type
string
डिफ़ॉल्ट cherry-mx-1x1-r1
Description
जिस keycap बेस पर बनाना है। फिलहाल उपलब्ध एकमात्र वैल्यू cherry-mx-1x1-r1 है — एक स्टैंडर्ड Cherry MX प्रोफाइल 1u keycap। 3–5 अतिरिक्त मेनस्ट्रीम स्टैंडर्ड साइज़ की योजना है; कस्टम साइज़ सपोर्टेड नहीं हैं।
Name
head_size_mm
Type
number
डिफ़ॉल्ट 23
Description
sculpted head का टारगेट साइज़, मिलीमीटर में: इसका सबसे लंबा आयाम इस वैल्यू पर स्केल किया जाता है। रेंज: [10, 40]। लगभग 32.9 से ऊपर की वैल्यूज़ को घटाया जा सकता है ताकि head अभी भी बेस की प्रोटेक्टिव फुटप्रिंट सीमा में फिट हो, इसलिए डिलिवर किया गया सबसे लंबा आयाम रिक्वेस्ट की गई वैल्यू से छोटा हो सकता है। लागू की गई वैल्यू आज task ऑब्जेक्ट पर वापस इको नहीं होती — यदि आपको यह पुष्टि करने की आवश्यकता है कि आपको वास्तव में कौन सी साइज़ मिली, तो डाउनलोड किए गए मॉडल में keycap-head मेश का बाउंडिंग बॉक्स मापें।
Name
vertical_offset_mm
Type
number
डिफ़ॉल्ट 0
Description
बेस पर बैठाए जाने से पहले head पर लागू किया गया वर्टिकल ऑफ़सेट, मिलीमीटर में। रेंज: [-5, 5]।

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

रिस्पॉन्स की result प्रॉपर्टी में नए बनाए गए keycap build task का task id होता है। Get a Task एंडपॉइंट को पोल करें या stream को सब्सक्राइब करें जब तक task SUCCEEDED तक न पहुँच जाए, फिर model_urls.glb और model_urls.obj_zip से आर्टिफैक्ट्स डाउनलोड करें।

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

फेल्योर मोड्स

Name
400 - Bad Request
Description
रिक्वेस्ट स्वीकार्य नहीं थी। सामान्य कारण:
- पैरामीटर मिसिंग: input_task_id और candidate_id आवश्यक हैं।
- अमान्य UUID: input_task_id एक वैलिड UUID नहीं है।
- पेरेंट सफल नहीं हुआ: संदर्भित prototype task अभी तक SUCCEEDED तक नहीं पहुँचा है।
- कोई कैंडिडेट नहीं: prototype task सफल हुआ लेकिन इसने कोई कैंडिडेट प्रोड्यूस नहीं किया।
- अज्ञात कैंडिडेट: candidate_id इनपुट task के कैंडिडेट्स में से एक नहीं है।
- विकल्प रेंज से बाहर: options की किसी फील्ड की वैल्यू इसकी अनुमत रेंज या enum सेट से बाहर थी।
Name
401 - Unauthorized
Description
प्रमाणीकरण विफल रहा। कृपया अपनी API की जांचें।
Name
402 - Payment Required
Description
अकाउंट फ्री प्लान पर है (tasks बनाने के लिए पेड प्लान आवश्यक है) या इसमें अपर्याप्त क्रेडिट हैं।
Name
404 - Not Found
Description
संदर्भित prototype task मौजूद नहीं है, किसी अन्य यूज़र से संबंधित है, या वेबऐप के माध्यम से बनाया गया था (केवल API-mode prototype tasks ही build में chain होते हैं)।
Name
429 - Too Many Requests
Description
आपने अपनी रेट लिमिट पार कर ली है।
Name
500 - Internal Server Error
Description
एक अनपेक्षित सर्वर-साइड एरर हुई — उदाहरण के लिए content-moderation सेवा उपलब्ध नहीं थी, इनपुट इमेज को स्टेज करना विफल रहा, या task बनाया नहीं जा सका। इस मामले में कोई task नहीं बनाया जाता, इसलिए फिर से प्रयास करना सुरक्षित है।

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

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

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

किसी वैध टास्क id के आधार पर prototype या build टास्क प्राप्त करें। URL पथ टास्क के चरण (stage) से मेल खाना चाहिए — /prototype/:id के माध्यम से लाया गया कोई build टास्क 404 लौटाता है, और इसी तरह इसका उल्टा भी सही है।

रेस्पॉन्स के आकार (shapes) के लिए The Keycap Prototype Task Object और The Keycap Build Task Object देखें।

पैरामीटर

Name
id
Type
path
Description
प्राप्त करने के लिए keycap टास्क का यूनीक आइडेंटिफ़ायर।

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

रेस्पॉन्स में keycap टास्क ऑब्जेक्ट होता है। इसका आकार (shape) इस बात पर निर्भर करता है कि किस चरण (stage) का अनुरोध किया गया था।

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

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

Delete a Keycap Task

किसी keycap टास्क को कैंसिल करें। यदि टास्क अभी भी PENDING है, तो क्रिएट करते समय इस्तेमाल किए गए क्रेडिट रिफंड कर दिए जाते हैं। जो टास्क पहले से IN_PROGRESS हैं, उन्हें बिना रिफंड के कैंसिल किया जाता है (हो सकता है वर्कर पहले से ही रिसोर्सेज़ का उपयोग कर रहा हो)। जो टास्क पहले से ही किसी अंतिम स्थिति (SUCCEEDED, FAILED, CANCELED) पर पहुँच चुके हैं, उन्हें कैंसिल नहीं किया जा सकता।

URL पथ टास्क के चरण से मेल खाना चाहिए — /prototype/:buildId पर DELETE करने से 404 मिलता है।

पथ पैरामीटर्स

Name
id
Type
path
Description
कैंसिल किए जाने वाले keycap टास्क के लिए यूनीक आइडेंटिफायर।

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

सफलता पर खाली बॉडी के साथ 204 No Content रिटर्न करता है।

विफलता के तरीके

Name
400 - Bad Request
Description
टास्क पहले से ही अंतिम स्थिति में है और इसे कैंसिल नहीं किया जा सकता।
Name
404 - Not Found
Description
टास्क मौजूद नहीं है, किसी अन्य यूज़र का है, या इसका चरण URL पथ से मेल नहीं खाता।
Name
500 - Internal Server Error
Description
कैंसिल करते समय एक अप्रत्याशित सर्वर-साइड त्रुटि हुई। हो सकता है टास्क कैंसिल हुआ हो या न हुआ हो — दोबारा प्रयास करने से पहले इसे फिर से पढ़कर पुष्टि करें।

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

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

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

Server-Sent Events (SSE) के माध्यम से keycap कार्य के लिए रीयल-टाइम अपडेट स्ट्रीम करें। URL पथ कार्य के चरण से मेल खाना चाहिए — /prototype/:buildId/stream पर स्ट्रीम खोलने पर status_code: 404 के साथ एक ही event: error पेलोड उत्सर्जित होता है और स्ट्रीम बंद हो जाती है।

पैरामीटर

Name
id
Type
path
Description
स्ट्रीम करने के लिए keycap कार्य का यूनीक पहचानकर्ता।

रिटर्न

Server-Sent Events के रूप में Keycap Prototype या Keycap Build कार्य ऑब्जेक्ट्स की एक स्ट्रीम लौटाता है। हर फ्रेम उस चरण के लिए पूरा कार्य ऑब्जेक्ट वहन करता है — वही आकार जो Get एंडपॉइंट लौटाता है — इसलिए जब तक कार्य PENDING या IN_PROGRESS में रहता है, तब तक आउटपुट फ़ील्ड्स बस भरे नहीं जाते (null, [] या {}) और finished_at null रहता है।

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 PENDING frame below is abbreviated 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=***"
  }
}

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

List Keycap Tasks

एक ही स्टेज के लिए अपने keycap टास्क की पेजिनेटेड सूची प्राप्त करें। URL पथ स्टेज का चयन करता है — /prototype प्रोटोटाइप टास्क लौटाता है; /build बिल्ड टास्क लौटाता है। दूसरे स्टेज के टास्क दोनों में से किसी भी रिस्पॉन्स में शामिल नहीं किए जाते।

Path Parameters

Name
stage
Type
path
आवश्यक
Description
या तो prototype या build। कलेक्शन केवल उन्हीं टास्क को लौटाता है जिनका स्टेज URL से मेल खाता है — /prototype फ़ेच करने पर कभी भी बिल्ड टास्क नहीं मिलते और इसका उल्टा भी सच है।

Query Parameters

Name
page_num
Type
integer
डिफ़ॉल्ट 1
Description
पेजिनेशन के लिए पेज नंबर।
Name
page_size
Type
integer
डिफ़ॉल्ट 10
Description
पेज साइज़ लिमिट। अधिकतम अनुमत 100 आइटम है।
Name
sort_by
Type
string
डिफ़ॉल्ट -created_at
Description
सॉर्ट करने के लिए फ़ील्ड। उपलब्ध मान:
- +created_at: निर्माण समय के अनुसार आरोही क्रम में सॉर्ट करें।
- -created_at: निर्माण समय के अनुसार अवरोही क्रम में सॉर्ट करें।

Returns

प्रति-स्टेज टास्क ऑब्जेक्ट की एक पेजिनेटेड सूची लौटाता है — या तो the keycap prototype task object जब /prototype की सूची बनाई जाती है, या the keycap build task object जब /build की सूची बनाई जाती है।

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

The Keycap Prototype Task Object

Keycap Prototype Task ऑब्जेक्ट एक कार्य इकाई है जिसे Meshy एक सोर्स फ़ोटो से एक फ़िनिश्ड-कीकैप डिज़ाइन इमेज जनरेट करने के लिए ट्रैक करता है। इस चरण का आउटपुट input_task_id और candidate_id के माध्यम से बिल्ड चरण में चेन किया जाता है।

Properties

Name
id
Type
string
Description
टास्क के लिए यूनीक आइडेंटिफ़ायर। हालांकि हम इम्प्लीमेंटेशन डिटेल के रूप में टास्क आईडी के लिए k-sortable UUID का उपयोग करते हैं, आपको id के फ़ॉर्मैट के बारे में कोई धारणा नहीं बनानी चाहिए।
Name
type
Type
string
Description
टास्क का प्रकार। मान creative-lab-keycap-prototype है।
Name
name
Type
string
Description
टास्क बनाते समय दिया गया टास्क नाम। यदि कोई नाम प्रदान नहीं किया गया था तो यह खाली स्ट्रिंग होगी।
Name
status
Type
string
Description
टास्क की स्थिति। संभावित मान PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED में से एक हैं।
Name
progress
Type
integer
Description
टास्क का progress। यदि टास्क अभी शुरू नहीं हुआ है, तो यह प्रॉपर्टी 0 होगी। एक बार टास्क सफल हो जाने पर, यह 100 हो जाएगी।
Name
created_at
Type
timestamp
Description
मिलीसेकंड में टास्क बनाए जाने के समय का टाइमस्टैंप।
टाइमस्टैंप RFC 3339 स्टैंडर्ड के अनुसार, 1 जनवरी, 1970 UTC से बीते मिलीसेकंड की संख्या को दर्शाता है। उदाहरण के लिए, शुक्रवार, 1 सितंबर, 2023 12:00:00 PM GMT को 1693569600000 के रूप में दर्शाया जाता है। यह Meshy API में सभी टाइमस्टैंप पर लागू होता है।
Name
started_at
Type
timestamp
Description
मिलीसेकंड में टास्क शुरू होने के समय का टाइमस्टैंप। यदि टास्क अभी शुरू नहीं हुआ है, तो यह प्रॉपर्टी 0 होगी।
Name
finished_at
Type
timestamp
Description
मिलीसेकंड में टास्क समाप्त होने के समय का टाइमस्टैंप। यदि टास्क अभी समाप्त नहीं हुआ है, तो यह प्रॉपर्टी 0 होगी।
Name
expires_at
Type
timestamp
Description
मिलीसेकंड में टास्क का रिज़ल्ट expire होने के समय का टाइमस्टैंप।
Name
preceding_tasks
Type
integer
Description
पूर्ववर्ती टास्कों की संख्या।
इस फ़ील्ड का मान केवल तभी सार्थक है जब टास्क की स्थिति PENDING हो।
Name
task_error
Type
object
Description
असफल टास्कों के लिए एरर विवरण। पूर्ण task_error ऑब्जेक्ट संदर्भ के लिए एरर देखें।
Name
consumed_credits
Type
integer
Description
इस टास्क द्वारा उपयोग किए गए क्रेडिट की संख्या। जो टास्क SUCCEEDED तक पहुँचता है, उससे उसके चरण की पूरी राशि चार्ज की जाती है। जो टास्क कभी नहीं बनाया जाता (रिक्वेस्ट के समय 4xx, जिसमें moderation रिजेक्शन भी शामिल है) उससे कोई चार्ज नहीं लिया जाता। जो टास्क FAILED तक पहुँचता है वह 0 लौटाता है — चार्ज रिफ़ंड किया जाता है, जिसमें एक asynchronous moderation ब्लॉक भी शामिल है। DELETE के माध्यम से कैंसिल करने पर केवल तभी रिफ़ंड मिलता है जब टास्क अभी भी PENDING हो; जो टास्क पहले से IN_PROGRESS है उसका चार्ज बना रहता है, क्योंकि काम पहले ही खर्च हो चुका है।
Name
image_urls
Type
array of strings
Description
फ़िनिश्ड-कीकैप डिज़ाइन रेंडर का डाउनलोड करने योग्य URL — कि candidate फ़िनिश्ड कीकैप के रूप में कैसा दिखता है। इसमें एक ही एंट्री होती है; image_urls[i] candidate_ids[i] के अनुरूप होता है। टास्क SUCCEEDED तक पहुँचने तक यह खाली रहता है। यह URL केवल डिस्प्ले के लिए है; बिल्ड एंडपॉइंट इन URL का नहीं बल्कि candidate_ids का उपयोग करता है। model_urls के समान ही URL लाइफ़साइकल: signed, कोई Authorization हेडर नहीं, expires_at तक वैलिड, और टास्क को फिर से पढ़ने पर स्थिर।
Name
candidate_ids
Type
array of strings
Description
Opaque candidate आइडेंटिफ़ायर, image_urls के समानांतर। अपने चुने हुए डिज़ाइन से मेल खाने वाली एंट्री को बिल्ड रिक्वेस्ट के candidate_id के रूप में पास करें। इन ids के फ़ॉर्मैट के बारे में कोई धारणा नहीं बनाएं।

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

द कीकैप बिल्ड टास्क ऑब्जेक्ट

कीकैप बिल्ड टास्क ऑब्जेक्ट एक वर्क यूनिट है जिसे Meshy एक सफल प्रोटोटाइप टास्क और एक चुने गए कैंडिडेट से अंतिम टेक्सचर्ड 3D कीकैप जनरेट करने के लिए ट्रैक करता है। एक सिंगल बिल्ड पूरी पाइपलाइन चलाता है — व्हाइट-मॉडल जनरेशन, ऑटोमैटिक सीटिंग और कटिंग, कलरिंग, असेंबली, और एक्सपोर्ट।

प्रॉपर्टीज़

Name
id
Type
string
Description
टास्क के लिए यूनीक आइडेंटिफ़ायर।
Name
type
Type
string
Description
टास्क का प्रकार। इसका वैल्यू creative-lab-keycap-build है।
Name
name
Type
string
Description
टास्क बनाते समय दिया गया टास्क नाम। यदि कोई नाम नहीं दिया गया था तो यह खाली स्ट्रिंग होगी।
Name
status
Type
string
Description
टास्क की स्थिति। संभावित वैल्यू PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED में से कोई एक है।
Name
progress
Type
integer
Description
टास्क की progress। यदि टास्क अभी शुरू नहीं हुआ है, तो यह प्रॉपर्टी 0 होगी। एक बार टास्क सफल हो जाने पर, यह 100 हो जाएगी।
Name
created_at
Type
timestamp
Description
टास्क बनाए जाने का टाइमस्टैंप, मिलीसेकंड में।
Name
started_at
Type
timestamp
Description
टास्क शुरू होने का टाइमस्टैंप, मिलीसेकंड में।
Name
finished_at
Type
timestamp
Description
टास्क पूरा होने का टाइमस्टैंप, मिलीसेकंड में।
Name
expires_at
Type
timestamp
Description
टास्क का रिज़ल्ट कब एक्सपायर होगा, इसका टाइमस्टैंप, मिलीसेकंड में।
Name
preceding_tasks
Type
integer
Description
पूर्ववर्ती टास्क की गिनती। यह केवल तब मायने रखती है जब status PENDING हो।
Name
task_error
Type
object
Description
विफल टास्क के लिए एरर विवरण। पूर्ण task_error ऑब्जेक्ट संदर्भ के लिए एरर देखें।
Name
consumed_credits
Type
integer
Description
इस टास्क द्वारा उपयोग किए गए क्रेडिट की संख्या। जो टास्क SUCCEEDED तक पहुँचता है, उससे उसके चरण के लिए पूरी राशि चार्ज की जाती है। जो टास्क कभी बना ही नहीं (रिक्वेस्ट के समय 4xx, जिसमें moderation अस्वीकृति भी शामिल है), उससे बिल्कुल भी चार्ज नहीं लिया जाता। जो टास्क FAILED तक पहुँचता है वह 0 लौटाता है — चार्ज रिफंड कर दिया जाता है, जिसमें एक असिंक्रोनस moderation ब्लॉक भी शामिल है। DELETE के माध्यम से कैंसिल करने पर रिफंड तभी मिलता है जब टास्क अभी भी PENDING हो; पहले से IN_PROGRESS टास्क चार्ज्ड ही रहता है, क्योंकि काम पहले ही खर्च हो चुका होता है।
Name
model_urls
Type
object
Description
जनरेट किए गए मॉडल आर्टिफ़ैक्ट्स के लिए डाउनलोड करने योग्य URL। GLB और OBJ बंडल दोनों वास्तविक-दुनिया के मिलीमीटर स्केल में, Y-up के साथ, कीकैप के सामने वाले भाग को +Z की ओर रखते हुए एक्सपोर्ट किए जाते हैं। मेश का नाम keycap-head और keycap-base रखा जाता है; जब बेस पैटर्न फ़िल पर फ़ॉलबैक होता है, तो स्टेम कैविटी के लिए एक तीसरा मेश keycap-base-interior भी मौजूद होता है। यह न मान लें कि हमेशा बिल्कुल दो ही मेश होंगे।
ये साइन किए गए URL हैं: इन्हें Authorization हेडर के बिना फ़ेच करें। ये expires_at तक वैध रहते हैं, जो finished_at के 3 दिन बाद है, और उस समय-सीमा के भीतर टास्क को फिर से पढ़ने पर एक नए साइन किए गए URL के बजाय वही समान URL लौटता है। उससे पहले फ़ाइलों को खुद डाउनलोड करके सहेज लें — एक्सपायर हो चुके लिंक को रिफ्रेश करने का कोई तरीका नहीं है।
- Name
  glb
  Type
  string
  Description
  अंतिम टेक्सचर्ड model.glb का डाउनलोड करने योग्य URL।
- Name
  obj_zip
  Type
  string
  Description
  एक zip बंडल का डाउनलोड करने योग्य URL, जिसमें model.obj, model.mtl, और उसके MTL द्वारा वास्तव में संदर्भित टेक्सचर PNG शामिल हैं। सॉलिड-कलर बेस में केवल keycap-head.png शामिल होती है; पैटर्न वाले बेस में keycap-base.png भी शामिल होती है।
Name
process_image_urls
Type
object
Description
इंटरमीडिएट प्रोसेस इमेज के लिए डाउनलोड करने योग्य URL, जो प्रकार के अनुसार की (key) से बंधे होते हैं। model_urls जैसा ही URL लाइफ़साइकल: साइन किए हुए, बिना Authorization हेडर के, expires_at तक वैध, और टास्क को फिर से पढ़ने पर स्थिर। वर्तमान में उत्पन्न होने वाले प्रकार:
- head_design — चुने गए कैंडिडेट की डिज़ाइन इमेज जिसका उपयोग बिल्ड में किया गया (हमेशा मौजूद रहती है)।
- composite — चुने गए कैंडिडेट का फ़िनिश्ड-कीकैप डिस्प्ले रेंडर (जब उपलब्ध हो तो मौजूद रहता है)।
- base_canvas — पेंट किया गया कीकैप-बेस कैनवास (जब उपलब्ध हो तो मौजूद रहता है)।
की (key) सेट को खुला-अंत माना जाए; बिना किसी ब्रेकिंग चेंज के नए प्रकार जोड़े जा सकते हैं।

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

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

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

यह उदाहरण प्रोग्रामेटिक रूप से पहला कैंडिडेट चुनता है। एक वास्तविक इंटीग्रेशन में आप image_urls एंट्री को अंतिम उपयोगकर्ता को दिखाएंगे और उन्हें चुनने देंगे; चुना गया इंडेक्स candidate_ids पर 1:1 मैप होता है।

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"