Creative Lab — Keycap API

एक स्रोत फोटो को पूर्ण-रंग कस्टम मैकेनिकल कीबोर्ड कीकैप में दो चरणों में बदलें: प्रोटोटाइप आपके इनपुट फोटो से "समाप्त कीकैप" डिज़ाइन रेंडर उत्पन्न करता है। एक बार जब आप उस रेंडर की पुष्टि कर लेते हैं, तो बिल्ड इसे एक बनावटयुक्त 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

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

स्रोत फोटो से एक तैयार कीकैप डिज़ाइन रेंडर उत्पन्न करें। टास्क का परिणाम image_urls एरे (तैयार कीकैप का डिस्प्ले रेंडर) और एक समानांतर candidate_ids एरे को ले जाता है; दोनों में एक ही प्रविष्टि होती है। यदि परिणाम आपकी इच्छानुसार नहीं है, तो एक और रेंडर के लिए इस एंडपॉइंट को फिर से कॉल करें — प्रत्येक कॉल अलग से बिल किया जाता है। प्रोटोटाइप टास्क आईडी के साथ candidate_id को बिल्ड एंडपॉइंट पर पास करें। प्रतिक्रिया के आकार के लिए द कीकैप प्रोटोटाइप टास्क ऑब्जेक्ट देखें।

पैरामीटर

Name
image_url
Type
string
आवश्यक
Description
Meshy के लिए स्रोत फोटो को कीकैप डिज़ाइन छवियों में बदलने के लिए। हम वर्तमान में .jpg, .jpeg, .png, और .webp प्रारूपों का समर्थन करते हैं।
प्रारूप को छवि डेटा को डिकोड करके पहचाना जाता है, URL के फ़ाइल एक्सटेंशन से नहीं — एक URL जिसमें कोई एक्सटेंशन नहीं है, या जो रीडायरेक्ट करता है, तब तक काम करता है जब तक कि बाइट्स समर्थित प्रारूप में डिकोड हो जाते हैं। HTTP रीडायरेक्ट का पालन किया जाता है। EXIF ओरिएंटेशन सामान्यीकृत होता है, इसलिए एक घुमाई गई फोन फोटो उसी तरह उपयोग की जाती है जैसे वह दिखती है।
सीमाएँ: प्रत्येक तरफ कम से कम 32 पिक्सल, कुल मिलाकर अधिकतम 178,956,970 पिक्सल, और डाउनलोड होने पर अधिकतम 20,000,000 बाइट्स। एक डेटा URI के लिए सीमा डिकोडेड बाइट्स पर लागू होती है, इसलिए स्रोत फ़ाइल स्वयं उस आकार तक हो सकती है — यह बेस64 टेक्स्ट है जो लगभग एक तिहाई बड़ा होता है, जो आपके अनुरोध बॉडी के लिए महत्वपूर्ण है, इस सीमा के लिए नहीं। एक डेटा URI को image/* सामग्री प्रकार और ;base64 घोषित करना चाहिए।
छवि प्रदान करने के दो तरीके हैं:
- सार्वजनिक रूप से सुलभ URL: एक URL जो सार्वजनिक इंटरनेट से सुलभ है।
- डेटा URI: छवि का बेस64-एन्कोडेड डेटा URI। डेटा 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 होता है जिसमें पृष्ठभूमि हटा दी जाती है, ताकि आप इसे किसी भी पृष्ठभूमि पर संयोजित कर सकें।
यह केवल डिस्प्ले रेंडर पर लागू होता है। बिल्ड एंडपॉइंट द्वारा उपभोग किया गया उम्मीदवार अप्रभावित रहता है, इसलिए 3D परिणाम समान होता है।

रिटर्न्स

प्रतिक्रिया की result प्रॉपर्टी में नए बनाए गए कीकैप प्रोटोटाइप टास्क का टास्क id होता है। एक टास्क प्राप्त करें एंडपॉइंट को पोल करें या स्ट्रीम की सदस्यता लें जब तक कि टास्क SUCCEEDED तक नहीं पहुंच जाता, फिर candidate_ids से प्रविष्टि लें और इसे टास्क आईडी के साथ बिल्ड एंडपॉइंट पर पास करें।

विफलता मोड

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

अनुरोध

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

प्रतिक्रिया

{
  "result": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef"
}

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

एक कीकैप बिल्ड टास्क बनाएं

एक सफल प्रोटोटाइप टास्क और उसके उम्मीदवारों में से एक से अंतिम टेक्सचर्ड 3D कीकैप मॉडल उत्पन्न करें। एकल बिल्ड टास्क पूरे पाइपलाइन को शुरू से अंत तक चलाता है — चुने गए डिज़ाइन से सफेद-मॉडल उत्पन्न करना, कीकैप बेस पर स्वचालित सीटिंग और कटिंग एक कैलिब्रेटेड डिफ़ॉल्ट पोज़ का उपयोग करके (कोई इंटरैक्टिव समायोजन आवश्यक नहीं), पूर्ण-मॉडल रंगाई, और अंतिम असेंबली और निर्यात। एक बिल्ड आमतौर पर 3–7 मिनट लेता है, जब कई बिल्ड एक साथ चलते हैं तो ऊपरी सीमा की ओर। प्रतिक्रिया आकार के लिए द कीकैप बिल्ड टास्क ऑब्जेक्ट देखें।

पैरामीटर

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

`options`

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

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

रिटर्न्स

प्रतिक्रिया की result प्रॉपर्टी में नए बनाए गए कीकैप बिल्ड टास्क का टास्क id होता है। एक टास्क प्राप्त करें एंडपॉइंट को पोल करें या स्ट्रीम की सदस्यता लें जब तक कि टास्क SUCCEEDED तक न पहुंच जाए, फिर model_urls.glb और model_urls.obj_zip से कलाकृतियों को डाउनलोड करें।

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

विफलता मोड्स

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

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

एक कीकैप कार्य प्राप्त करें

एक मान्य कार्य id दिए जाने पर एक प्रोटोटाइप या निर्माण कार्य प्राप्त करें। URL पथ को कार्य के चरण से मेल खाना चाहिए — /prototype/:id के माध्यम से प्राप्त एक निर्माण कार्य 404 लौटाता है, और इसके विपरीत।

प्रतिक्रिया संरचनाओं के लिए कीकैप प्रोटोटाइप कार्य ऑब्जेक्ट और कीकैप निर्माण कार्य ऑब्जेक्ट देखें।

पैरामीटर्स

Name
id
Type
path
Description
प्राप्त करने के लिए कीकैप कार्य का अद्वितीय पहचानकर्ता।

रिटर्न्स

प्रतिक्रिया में कीकैप कार्य ऑब्जेक्ट शामिल होता है। संरचना इस पर निर्भर करती है कि कौन सा चरण अनुरोधित था।

अनुरोध

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

प्रोटोटाइप प्रतिक्रिया

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

निर्माण प्रतिक्रिया

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

एक कीकैप कार्य हटाएं

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

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

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

Name
id
Type
path
Description
रद्द करने के लिए कीकैप कार्य का अद्वितीय पहचानकर्ता।

रिटर्न्स

सफल होने पर 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

एक कीकैप कार्य को स्ट्रीम करें

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

पैरामीटर्स

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

रिटर्न्स

Keycap Prototype या Keycap Build कार्य वस्तुओं की एक स्ट्रीम को सर्वर-सेंट इवेंट्स के रूप में लौटाता है। PENDING या IN_PROGRESS कार्यों के लिए, प्रतिक्रिया स्ट्रीम में केवल आवश्यक progress और status फ़ील्ड शामिल होंगे।

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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)

कीकैप कार्यों की सूची

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

पथ पैरामीटर

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

क्वेरी पैरामीटर

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: निर्माण समय के अनुसार अवरोही क्रम में क्रमबद्ध करें।

रिटर्न्स

प्रति-चरण कार्य वस्तु की पेजिनेशन की गई सूची लौटाता है — या तो कीकैप प्रोटोटाइप कार्य वस्तु जब /prototype सूचीबद्ध करते हैं या कीकैप निर्माण कार्य वस्तु जब /build सूचीबद्ध करते हैं।

अनुरोध

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

प्रतिक्रिया (प्रोटोटाइप कार्यों की सूची)

[
  {
    "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 एक स्रोत फोटो से एक समाप्त कीकैप डिज़ाइन छवि उत्पन्न करने के लिए ट्रैक करता है। इस चरण का आउटपुट input_task_id प्लस candidate_id के माध्यम से निर्माण चरण में जोड़ा जाता है।

गुण

Name
id
Type
string
Description
कार्य के लिए अद्वितीय पहचानकर्ता। जबकि हम कार्य आईडी के लिए k-sortable UUID का उपयोग करते हैं, आपको आईडी के प्रारूप के बारे में कोई धारणा नहीं बनानी चाहिए।
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
कार्य की प्रगति। यदि कार्य अभी तक शुरू नहीं हुआ है, तो यह गुण 0 होगा। एक बार कार्य सफल हो जाने पर, यह 100 हो जाएगा।
Name
created_at
Type
timestamp
Description
कार्य के निर्माण का टाइमस्टैंप, मिलीसेकंड में।
एक टाइमस्टैंप 1 जनवरी, 1970 UTC से बीते हुए मिलीसेकंड की संख्या का प्रतिनिधित्व करता है, जो RFC 3339 मानक का पालन करता है। उदाहरण के लिए, शुक्रवार, 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
कार्य परिणाम के समाप्त होने का टाइमस्टैंप, मिलीसेकंड में।
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 लौटाता है — चार्ज वापस कर दिया जाता है, जिसमें एक असिंक्रोनस moderation ब्लॉक शामिल है। DELETE के माध्यम से रद्द करना केवल तभी वापस किया जाता है जब कार्य अभी भी PENDING हो; एक कार्य जो पहले से IN_PROGRESS है, चार्ज रहता है, क्योंकि काम खर्च हो चुका है।
Name
image_urls
Type
array of strings
Description
समाप्त कीकैप डिज़ाइन रेंडर का डाउनलोड करने योग्य URL — जो उम्मीदवार समाप्त कीकैप के रूप में दिखता है। एकल प्रविष्टि रखता है; image_urls[i] candidate_ids[i] के अनुरूप है। जब तक कार्य SUCCEEDED तक नहीं पहुँचता, तब तक खाली। URL केवल प्रदर्शन के लिए है; निर्माण एंडपॉइंट candidate_ids का उपभोग करता है, न कि इन URL का। model_urls के समान URL जीवनचक्र: हस्ताक्षरित, कोई Authorization हेडर नहीं, expires_at तक मान्य, और जब कार्य को पुनः पढ़ा जाता है तब स्थिर।
Name
candidate_ids
Type
array of strings
Description
अपारदर्शी उम्मीदवार पहचानकर्ता, image_urls के समानांतर। अपने चुने हुए डिज़ाइन से मेल खाने वाली प्रविष्टि को निर्माण अनुरोध के candidate_id के रूप में पास करें। इन आईडी के प्रारूप के बारे में कोई धारणा नहीं बनाएं।

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
कार्य की प्रगति। यदि कार्य अभी तक शुरू नहीं हुआ है, तो यह गुण 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
पूर्ववर्ती कार्यों की गणना। केवल तब अर्थपूर्ण जब स्थिति PENDING हो।
Name
task_error
Type
object
Description
असफल कार्यों के लिए एरर विवरण। पूर्ण task_error ऑब्जेक्ट संदर्भ के लिए Errors देखें।
Name
consumed_credits
Type
integer
Description
इस कार्य द्वारा उपभोग किए गए क्रेडिट की संख्या। एक कार्य जो SUCCEEDED तक पहुँचता है, उसके चरण के लिए पूरी राशि चार्ज की जाती है। एक कार्य जो कभी नहीं बनता (अनुरोध समय पर 4xx, जिसमें moderation अस्वीकृति शामिल है) को बिल्कुल भी चार्ज नहीं किया जाता। एक कार्य जो FAILED तक पहुँचता है 0 लौटाता है — चार्ज वापस कर दिया जाता है, जिसमें एक असिंक्रोनस moderation ब्लॉक शामिल है। DELETE के माध्यम से रद्द करना केवल तभी वापस करता है जब कार्य अभी भी PENDING हो; एक कार्य जो पहले से IN_PROGRESS है, चार्ज रहता है, क्योंकि कार्य किया जा चुका है।
Name
model_urls
Type
object
Description
उत्पन्न मॉडल आर्टिफैक्ट्स के लिए डाउनलोड करने योग्य URLs। दोनों GLB और OBJ बंडल वास्तविक-दुनिया मिलीमीटर स्केल, Y-up, के साथ एक्सपोर्ट किए जाते हैं, जिसमें कीकैप का सामने +Z की ओर होता है। मेशेस का नाम keycap-head और keycap-base होता है; जब बेस पैटर्न फिल पर वापस जाता है, तो एक तीसरा मेश keycap-base-interior भी स्टेम कैविटी के लिए मौजूद होता है। ठीक दो मेशेस मान कर न चलें।
ये साइन किए गए URLs हैं: इन्हें बिना Authorization हेडर के प्राप्त करें। वे expires_at तक वैध रहते हैं, जो finished_at के 3 दिन बाद होता है, और उस विंडो के अंदर कार्य को फिर से पढ़ने पर समान URL लौटाता है बजाय एक नए साइन किए गए के। तब तक फाइलें स्वयं डाउनलोड और स्टोर करें — एक समाप्त लिंक को ताज़ा करने का कोई तरीका नहीं है।
- Name
  glb
  Type
  string
  Description
  अंतिम टेक्सचरयुक्त model.glb के लिए डाउनलोड करने योग्य URL।
- Name
  obj_zip
  Type
  string
  Description
  एक ज़िप बंडल के लिए डाउनलोड करने योग्य URL जिसमें model.obj, model.mtl, और टेक्सचर PNGs शामिल हैं जिनका MTL वास्तव में संदर्भित करता है। एक ठोस-रंग बेस केवल keycap-head.png भेजता है; एक पैटर्नयुक्त बेस भी keycap-base.png भेजता है।
Name
process_image_urls
Type
object
Description
मध्यवर्ती प्रक्रिया छवियों के लिए डाउनलोड करने योग्य URLs, प्रकार के आधार पर। model_urls के समान URL जीवनचक्र: साइन किए गए, कोई Authorization हेडर नहीं, expires_at तक वैध, और जब कार्य को फिर से पढ़ा जाता है तो स्थिर। वर्तमान में उत्पन्न प्रकार:
- head_design — चुने गए उम्मीदवार की डिज़ाइन छवि जो बिल्ड ने उपभोग की (हमेशा मौजूद)।
- composite — चुने गए उम्मीदवार की समाप्त-कीकैप डिस्प्ले रेंडर (उपलब्ध होने पर मौजूद)।
- base_canvas — पेंटेड कीकैप-बेस कैनवास (उपलब्ध होने पर मौजूद)।
कुंजी सेट को ओपन-एंडेड मानें; बिना किसी ब्रेकिंग परिवर्तन के नए प्रकार जोड़े जा सकते हैं।

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 मैप करता है।

पूरा प्रवाह

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"