Creative Lab — Fidget Pixel API

किसी सोर्स फ़ोटो को दो चरणों में एक मल्टी-कलर 3D-प्रिंट करने योग्य पिक्सेल-आर्ट फ़िजेट बोर्ड में बदलें: prototype आपकी फ़ोटो को पिक्सेलाइज़ करके एक पिक्सेल-आर्ट इमेज बनाता है, फिर build उस इमेज को 16×16 या 32×32 ग्रिड पर सैंपल करता है और हर पिक्सेल को एक इंटरलॉकिंग स्क्वायर या हेक्सागोनल पीस में बदल देता है, जिसे एक ही 3MF के रूप में डिलीवर किया जाता है जिसके ऑब्जेक्ट्स अपने रंग साथ रखते हैं ताकि एक मल्टी-फ़िलामेंट स्लाइसर हर पीस को सही रंग में प्रिंट कर सके। दोनों चरण input_task_id के ज़रिए आपस में लिंक होते हैं।

POST /openapi/creative-lab/fidget-pixel/v1/prototype
POST /openapi/creative-lab/fidget-pixel/v1/build

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

POST/openapi/creative-lab/fidget-pixel/v1/prototype

Fidget Pixel Prototype टास्क बनाना

सोर्स फोटो से एक सिंगल पिक्सेल-आर्ट इमेज जनरेट करें। रिटर्न किया गया टास्क ID वही है जिसे आप build एंडपॉइंट को input_task_id के रूप में पास करते हैं। यदि परिणाम आपकी पसंद का न हो तो दूसरे प्रयास के लिए इस एंडपॉइंट को फिर से कॉल करें — हर कॉल की बिलिंग अलग से होती है। रिस्पॉन्स के स्वरूप के लिए The Fidget Pixel Prototype Task Object देखें।

पैरामीटर

Name
image_url
Type
string
आवश्यक
Description
Meshy के लिए पिक्सेलाइज़ करने हेतु सोर्स फोटो। हम फिलहाल .jpg, .jpeg, .png, और .webp फॉर्मैट सपोर्ट करते हैं।
फॉर्मैट का पता इमेज डेटा को डिकोड करके लगाया जाता है, URL के फाइल एक्सटेंशन से नहीं — बिना एक्सटेंशन वाला URL, या ऐसा URL जो रीडायरेक्ट करता हो, तब तक काम करेगा जब तक बाइट्स किसी सपोर्टेड फॉर्मैट में डिकोड होते हैं। HTTP रीडायरेक्ट्स को फॉलो किया जाता है।
इमेज प्रदान करने के दो तरीके हैं:
- सार्वजनिक रूप से एक्सेस योग्य URL: एक URL जो सार्वजनिक इंटरनेट से एक्सेस किया जा सके।
- Data URI: इमेज का base64-एन्कोडेड data URI। data URI का उदाहरण: data:image/jpeg;base64,<your base64-encoded image data>.
Name
type
Type
string
आवश्यक
Description
फोटो में क्या दिखाया गया है। यह पिक्सेलाइज़ेशन स्टाइल तय करता है, इसलिए सोच-समझकर चुनें — दोनों के परिणाम स्पष्ट रूप से भिन्न होते हैं। उपलब्ध वैल्यूज़:
- person — विषय एक व्यक्ति है (पोर्ट्रेट या फुल बॉडी)। विषय का chibi-स्टाइल पिक्सेल स्प्राइट प्रोड्यूस करता है।
- other — बाकी सब कुछ: पालतू जानवर, वस्तुएँ, मैस्कॉट, लोगो, लैंडस्केप। विषय का bead-art स्टाइल पिक्सेल आइकन प्रोड्यूस करता है।
Name
name
Type
string
Description
डिस्प्ले उद्देश्यों के लिए वैकल्पिक टास्क नाम। अधिकतम 100 अक्षर।

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

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

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

Name
400 - Bad Request
Description
रिक्वेस्ट स्वीकार्य नहीं थी। सामान्य कारण:
- पैरामीटर गायब: image_url और type दोनों आवश्यक हैं।
- अमान्य type: type का मान person या other होना चाहिए।
- अमान्य इमेज फॉर्मैट: प्रदान किया गया image_url किसी सपोर्टेड फॉर्मैट (.jpg, .jpeg, .png, .webp) में नहीं है।
- इमेज डाइमेंशन रेंज से बाहर: इमेज बहुत छोटी है, अधिकतम फाइल साइज़ से अधिक है, या अधिकतम पिक्सेल काउंट से अधिक है।
- अनपहुँच योग्य URL: image_url डाउनलोड नहीं किया जा सका (404 या timeout)।
- अमान्य Data URI: base64 स्ट्रिंग गलत ढंग से बनी हुई है।
- कंटेंट फ्लैग किया गया: इनपुट इमेज को NSFW moderation द्वारा फ्लैग किया गया था।
Name
401 - Unauthorized
Description
प्रमाणीकरण विफल रहा। कृपया अपनी API की जांचें।
Name
402 - Payment Required
Description
इस टास्क को पूरा करने के लिए अपर्याप्त क्रेडिट, या API की किसी फ्री-प्लान अकाउंट की है।
Name
403 - Forbidden
Description
इनपुट इमेज को intellectual property moderation द्वारा फ्लैग किया गया था (Content flagged for intellectual property violation)। केवल intellectual property filtering सक्षम किए गए Enterprise अकाउंट्स को ही ब्लॉक किया जाता है; कोई चार्ज नहीं लिया जाता।
Name
429 - Too Many Requests
Description
आपने अपनी रेट लिमिट पार कर ली है।
Name
500 - Internal Server Error
Description
intellectual property की जांच ही पूरी नहीं हो सकी (Unable to perform intellectual property check, please try again)। intellectual property filtering सक्षम किए गए Enterprise अकाउंट्स इस जांच पर फेल-क्लोज्ड होते हैं; कोई चार्ज नहीं लिया जाता — रिक्वेस्ट को फिर से करें।

Request

POST

/openapi/creative-lab/fidget-pixel/v1/prototype

# Stage 1: pixelize the source photo
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/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>",
    "type": "person"
  }'

Response

{
  "result": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7"
}

POST/openapi/creative-lab/fidget-pixel/v1/build

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

एक सफल प्रोटोटाइप टास्क से 3D-प्रिंट करने योग्य टुकड़े जनरेट करें। बिल्ड प्रोटोटाइप की पिक्सेल-आर्ट इमेज को अनुरोधित ग्रिड पर सैंपल करता है, इसे अधिकतम color_count रंगों में क्वांटाइज़ करता है, और प्रत्येक ग्रिड सेल के लिए एक इंटरलॉकिंग टुकड़ा जनरेट करता है। डिलिवरेबल एक ही 3MF है जिसमें हर टुकड़ा अपने रंग के साथ टैग किया गया एक अलग ऑब्जेक्ट है, जो मल्टी-फिलामेंट स्लाइसर के लिए तैयार है। रिस्पॉन्स के स्वरूप के लिए The Fidget Pixel Build Task Object देखें।

पैरामीटर

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

`options`

वैकल्पिक टुकड़ा ज्यामिति। हर फ़ील्ड का एक डिफ़ॉल्ट है — केवल वे भेजें जिन्हें आप ओवरराइड करना चाहते हैं। ये वही नियंत्रण हैं जो Creative Lab वेबऐप उपलब्ध कराता है; प्लग हाइट, कैप स्केल, और अन्य मैन्युफैक्चरिंग प्रीसेट shape और piece_size_mm से व्युत्पन्न होते हैं और उपलब्ध नहीं कराए जाते।

Name
shape
Type
string
डिफ़ॉल्ट square
Description
प्रत्येक टुकड़े का फुटप्रिंट। उपलब्ध मान:
- square (डिफ़ॉल्ट) — वर्गाकार ग्रिड पर वर्गाकार टुकड़े।
- hex — षट्कोणीय ग्रिड पर षट्कोणीय टुकड़े। हेक्स टुकड़े केवल 6 और 8 mm में उपलब्ध हैं।
Name
grid_size
Type
integer
डिफ़ॉल्ट 32
Description
बोर्ड के प्रत्येक साइड पर टुकड़ों की संख्या। उपलब्ध मान: 16 या 32। 32 ग्रिड अधिक विवरण बनाए रखता है; 16 ग्रिड का मतलब है समान विषय के लिए कम, बड़े टुकड़े।
Name
piece_size_mm
Type
integer
डिफ़ॉल्ट 8
Description
प्रत्येक टुकड़े की एज लंबाई, मिलीमीटर में। उपलब्ध मान: 6, 8, या 10। grid_size के साथ मिलकर यह प्रिंटेड बोर्ड का आकार निर्धारित करता है — उदाहरण के लिए 32 × 8 mm ≈ 26 cm प्रति साइड। shape: "hex" के लिए 10 उपलब्ध नहीं है (झुका हुआ हेक्स फेस अधिकांश उपभोक्ता FDM प्रिंटरों पर ओवरहैंग करता है)।
Name
color_count
Type
integer
डिफ़ॉल्ट 8
Description
उस पैलेट में रंगों की अधिकतम संख्या जिसमें इमेज को क्वांटाइज़ किया जाता है। रेंज: [1, 8]। प्रत्येक रंग आपके स्लाइसर में एक फिलामेंट बन जाता है।
Name
piece_height_mm
Type
integer
डिफ़ॉल्ट 15
Description
प्रत्येक टुकड़े की ऊँचाई, मिलीमीटर में। रेंज: [10, 80]।

`output`

वैकल्पिक वायर-फ़ॉर्मैट सिलेक्टर। डिफ़ॉल्ट 3mf है, जो वर्तमान में एकमात्र समर्थित मान है।

Name
format
Type
string
डिफ़ॉल्ट 3mf
Description
बिल्ड द्वारा लौटाया गया आर्टिफ़ैक्ट। उपलब्ध मान:
- 3mf (डिफ़ॉल्ट) — model_urls.3mf के तहत एक ही model.3mf लौटाता है, जिसमें प्रति टुकड़ा एक ऑब्जेक्ट होता है और टुकड़े का रंग प्रत्येक ऑब्जेक्ट से जुड़ा होता है।

रिटर्न्स

रिस्पॉन्स की result प्रॉपर्टी में नए बनाए गए fidget pixel बिल्ड टास्क का टास्क id होता है। Get a Task एंडपॉइंट को पोल करें या stream को सब्सक्राइब करें जब तक टास्क SUCCEEDED तक न पहुँच जाए, फिर model_urls.3mf से आर्टिफ़ैक्ट डाउनलोड करें।

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

Name
400 - Bad Request
Description
अनुरोध स्वीकार्य नहीं था। सामान्य कारण:
- पैरामीटर गायब: input_task_id आवश्यक है।
- अमान्य UUID: input_task_id एक मान्य UUID नहीं है।
- पैरेंट सफल नहीं हुआ: संदर्भित प्रोटोटाइप टास्क अभी तक SUCCEEDED तक नहीं पहुँचा है।
- कोई उम्मीदवार नहीं: प्रोटोटाइप टास्क सफल हुआ लेकिन इसने कोई पिक्सेल-आर्ट इमेज उत्पन्न नहीं की; एक नया प्रोटोटाइप बनाएँ।
- विकल्प सीमा से बाहर: options फ़ील्ड में से कोई एक अपने अनुमत सेट या रेंज से बाहर है — उदाहरण के लिए options.grid_size must be 16 or 32, या options.piece_size_mm=10 is not supported for shape=hex; hex pieces are available in 6 and 8 mm।
- असमर्थित फ़ॉर्मैट: output.format 3mf होना चाहिए।
Name
401 - Unauthorized
Description
प्रमाणीकरण विफल रहा। कृपया अपनी API की जाँच करें।
Name
402 - Payment Required
Description
इस टास्क को करने के लिए अपर्याप्त क्रेडिट, या API की एक फ्री-प्लान खाते से संबंधित है।
Name
403 - Forbidden
Description
संदर्भित प्रोटोटाइप की इमेज को इंटेलेक्चुअल प्रॉपर्टी moderation द्वारा फ़्लैग किया गया था। केवल इंटेलेक्चुअल प्रॉपर्टी फ़िल्टरिंग सक्षम वाले Enterprise खाते ही ब्लॉक किए जाते हैं; कुछ भी चार्ज नहीं किया जाता।
Name
404 - Not Found
Description
संदर्भित प्रोटोटाइप टास्क मौजूद नहीं है, किसी अलग यूज़र से संबंधित है, या वेबऐप के माध्यम से बनाया गया था (केवल API-mode प्रोटोटाइप टास्क ही बिल्ड में चेन होते हैं)।
Name
429 - Too Many Requests
Description
आपने अपनी रेट लिमिट पार कर ली है।
Name
500 - Internal Server Error
Description
संदर्भित प्रोटोटाइप का इंटेलेक्चुअल प्रॉपर्टी वर्डिक्ट स्थापित नहीं किया जा सका (Unable to perform intellectual property check, please try again)। इंटेलेक्चुअल प्रॉपर्टी फ़िल्टरिंग सक्षम वाले Enterprise खाते इस जाँच पर fail closed होते हैं; कुछ भी चार्ज नहीं किया जाता — अनुरोध पुनः प्रयास करें।

Request

POST

/openapi/creative-lab/fidget-pixel/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "options": {
      "shape": "square",
      "grid_size": 32,
      "piece_size_mm": 8,
      "color_count": 8,
      "piece_height_mm": 15
    },
    "output": {
      "format": "3mf"
    }
  }'

Response

{
  "result": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98"
}

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

Fidget Pixel टास्क को प्राप्त करें

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

रिस्पॉन्स आकृतियों (shapes) के लिए The Fidget Pixel Prototype Task Object और The Fidget Pixel Build Task Object देखें।

पैरामीटर

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

रिटर्न मान

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

विफलता के तरीके (Failure Modes)

Name
400 - Bad Request
Description
id एक मान्य UUID नहीं है (Invalid ID)।
Name
403 - Forbidden
Description
टास्क की इमेज को बौद्धिक संपदा (intellectual property) moderation द्वारा फ़्लैग किया गया था। केवल बौद्धिक संपदा फ़िल्टरिंग सक्षम वाले Enterprise खाते ही ब्लॉक किए जाते हैं।
Name
404 - Not Found
Description
टास्क मौजूद नहीं है, किसी अन्य उपयोगकर्ता का है, या इसका चरण URL पथ से मेल नहीं खाता है।
Name
500 - Internal Server Error
Description
बौद्धिक संपदा जाँच पूरी नहीं की जा सकी (Unable to perform intellectual property check, please try again); बौद्धिक संपदा फ़िल्टरिंग सक्षम वाले Enterprise खाते fail closed होते हैं। अनुरोध को पुनः प्रयास करें।

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Build Response

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

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

एक Fidget Pixel टास्क डिलीट करें

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

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

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

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

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

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

फेलियर मोड्स

Name
400 - Bad Request
Description
रिक्वेस्ट स्वीकार्य नहीं थी। सामान्य कारण:
- अमान्य ID: id एक वैध UUID नहीं है।
- टर्मिनल स्टेट: टास्क पहले से ही SUCCEEDED, FAILED या CANCELED है और इसे कैंसल नहीं किया जा सकता।
Name
404 - Not Found
Description
टास्क मौजूद नहीं है, किसी अलग यूज़र का है, या इसका स्टेज URL पाथ से मेल नहीं खाता।

Request

DELETE

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

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

Fidget Pixel टास्क को स्ट्रीम करें

Server-Sent Events (SSE) के ज़रिए फ़िज़्जेट पिक्सेल टास्क के लिए रीयल-टाइम अपडेट स्ट्रीम करें। URL पथ टास्क के चरण से मेल खाना चाहिए — /prototype/:buildId/stream पर स्ट्रीम खोलने पर status_code: 404 के साथ एक सिंगल event: error पेलोड भेजा जाता है और स्ट्रीम बंद हो जाती है; एक अमान्य id भी status_code: 400 (Invalid ID) के साथ ऐसा ही करता है।

पैरामीटर

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

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

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

Request

GET

/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/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 for the stage; fields not yet populated are null / empty.
event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "PENDING",
  "progress": 0,
  "created_at": 1757001300000,
  "started_at": null,
  "finished_at": null,
  "expires_at": 1757260500000,
  "preceding_tasks": 2,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {}
}

event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

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

Fidget Pixel टास्क की सूची

एक ही स्टेज के लिए अपने fidget pixel टास्क की पेजिनेटेड सूची प्राप्त करें। 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: निर्माण समय के आधार पर अवरोही क्रम में सॉर्ट करें।

रिटर्न

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

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "type": "creative-lab-fidget-pixel-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1757001000000,
    "started_at": 1757001005000,
    "finished_at": 1757001178000,
    "expires_at": 1757260378000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
    ]
  }
]

द फिजेट पिक्सेल प्रोटोटाइप टास्क ऑब्जेक्ट

फिजेट पिक्सेल प्रोटोटाइप टास्क ऑब्जेक्ट एक वर्क यूनिट है जिसे Meshy किसी सोर्स फोटो को पिक्सेल-आर्ट इमेज में पिक्सलाइज़ करने के लिए ट्रैक करता है। इस स्टेज का आउटपुट input_task_id के माध्यम से बिल्ड स्टेज से चेन किया जाता है।

Properties

Name
id
Type
string
Description
टास्क के लिए यूनीक आइडेंटिफ़ायर। हालांकि हम इम्प्लीमेंटेशन डिटेल के रूप में टास्क आईडी के लिए k-sortable UUID का उपयोग करते हैं, आपको आईडी के फॉर्मेट के बारे में कोई धारणा नहीं बनानी चाहिए।
Name
type
Type
string
Description
टास्क का टाइप। इसका वैल्यू creative-lab-fidget-pixel-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 बजे GMT को 1693569600000 के रूप में दर्शाया जाता है। यह Meshy API के सभी टाइमस्टैंप पर लागू होता है।
Name
started_at
Type
timestamp
Description
टास्क शुरू होने का टाइमस्टैंप, मिलीसेकंड में। यदि टास्क अभी शुरू नहीं हुआ है, तो यह प्रॉपर्टी null होगी।
Name
finished_at
Type
timestamp
Description
टास्क पूरा होने का टाइमस्टैंप, मिलीसेकंड में। यदि टास्क अभी पूरा नहीं हुआ है, तो यह प्रॉपर्टी null होगी।
Name
expires_at
Type
timestamp
Description
टास्क का रिज़ल्ट कब एक्सपायर होगा इसका टाइमस्टैंप, मिलीसेकंड में — टास्क पूरा होने के 3 दिन बाद। एंटरप्राइज़ अकाउंट API रिज़ल्ट को अनिश्चित काल तक बनाए रखते हैं (देखें Asset Retention); उनके लिए यह टाइमस्टैंप लगभग 100 साल आगे सेट किया जाता है।
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 लौटाता है — चार्ज रिफंड कर दिया जाता है। DELETE के माध्यम से कैंसिल करने पर केवल तभी रिफंड मिलता है जब टास्क अभी भी PENDING हो; जो टास्क पहले से IN_PROGRESS है उससे चार्ज लिया जाता रहता है, क्योंकि काम पहले ही खर्च हो चुका है।
Name
image_urls
Type
array of strings
Description
इस प्रोटोटाइप टास्क द्वारा जनरेट की गई पिक्सेल-आर्ट इमेज के लिए डाउनलोड करने योग्य URL। वर्तमान में API हमेशा ठीक एक इमेज लौटाता है; यह फ़ील्ड एक ऐरे है ताकि भविष्य के रिविज़न बिना ब्रेकिंग चेंज के कई कैंडिडेट सामने ला सकें। टास्क के SUCCEEDED तक पहुंचने तक यह खाली रहता है।
ये साइन किए हुए URL हैं: इन्हें Authorization हेडर के बिना फ़ेच करें। ये expires_at तक वैध रहते हैं, जो finished_at के 3 दिन बाद है, और उस समय-सीमा के भीतर टास्क को फिर से पढ़ने पर नए सिरे से साइन किया गया URL नहीं बल्कि वही समान URL लौटता है। इससे पहले फ़ाइलों को स्वयं डाउनलोड करके सुरक्षित रख लें — एक्सपायर हो चुके लिंक को रिफ्रेश करने का कोई तरीका नहीं है।

Example Fidget Pixel Prototype Task Object

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

The Fidget Pixel Build Task Object

Fidget Pixel Build Task ऑब्जेक्ट एक कार्य इकाई है जिसे Meshy एक सफल हुए प्रोटोटाइप टास्क से प्रिंट करने योग्य टुकड़े जनरेट करने के लिए ट्रैक करता है। बिल्ड प्रोटोटाइप की पिक्सेल-आर्ट इमेज को अनुरोधित ग्रिड पर सैंपल करता है और एक कलर-टैग किया हुआ 3MF प्रकाशित करता है।

Properties

Name
id
Type
string
Description
टास्क के लिए यूनिक आइडेंटिफ़ायर।
Name
type
Type
string
Description
टास्क का प्रकार। मान creative-lab-fidget-pixel-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
टास्क कब शुरू हुआ था, इसका टाइमस्टैंप, मिलीसेकंड में। टास्क शुरू होने तक यह null रहता है।
Name
finished_at
Type
timestamp
Description
टास्क कब समाप्त हुआ था, इसका टाइमस्टैंप, मिलीसेकंड में। टास्क समाप्त होने तक यह null रहता है।
Name
expires_at
Type
timestamp
Description
टास्क का परिणाम कब समाप्त (expire) होता है, इसका टाइमस्टैंप, मिलीसेकंड में — टास्क समाप्त होने के 3 दिन बाद। एंटरप्राइज़ खाते API परिणामों को अनिश्चित काल तक बनाए रखते हैं (देखें Asset Retention); उनके लिए यह टाइमस्टैंप लगभग 100 वर्ष आगे सेट होता है।
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 लौटाता है — चार्ज वापस कर दिया जाता है। DELETE के माध्यम से रद्द करने पर केवल तभी वापसी होती है जब टास्क अभी भी PENDING हो; जो टास्क पहले से ही IN_PROGRESS है उससे चार्ज लिया ही रहता है, क्योंकि काम खर्च हो चुका है।
Name
model_urls
Type
object
Description
फ़ॉर्मैट के अनुसार कुंजीबद्ध, जनरेट किए गए आर्टिफ़ैक्ट के लिए डाउनलोड करने योग्य URL। इसमें बिल्कुल एक ही एंट्री होती है — वह फ़ॉर्मैट जो बिल्ड अनुरोध के output.format के माध्यम से अनुरोधित किया गया था। टास्क के SUCCEEDED तक पहुँचने तक यह खाली रहता है।
ये साइन किए गए URL हैं: इन्हें बिना किसी Authorization हेडर के फ़ेच करें। ये expires_at तक मान्य रहते हैं, जो finished_at के 3 दिन बाद होता है, और उस अवधि के भीतर टास्क को फिर से पढ़ने पर नए सिरे से साइन किए गए URL के बजाय वही समान URL लौटता है। उससे पहले फ़ाइलों को स्वयं डाउनलोड करके संग्रहित कर लें — समाप्त हो चुके लिंक को रीफ़्रेश करने का कोई तरीका नहीं है।
- Name
  3mf
  Type
  string
  Description
  3MF फ़ाइल का डाउनलोड करने योग्य URL। प्रति टुकड़ा एक ऑब्जेक्ट, प्रत्येक को उसके पैलेट रंग के साथ टैग किया गया, ताकि मल्टी-फिलामेंट स्लाइसर प्रति रंग फिलामेंट असाइन करे। यह तब मौजूद होता है जब output.format, 3mf (डिफ़ॉल्ट) था।

Example Fidget Pixel Build Task Object

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

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

पूरा फ्लो: किसी फ़ोटो से एक प्रोटोटाइप बनाएं, उसे SUCCEEDED तक पोल करें, उससे एक बिल्ड बनाएं, बिल्ड को SUCCEEDED तक पोल करें, फिर model_urls से 3MF डाउनलोड करें।

एक प्रोटोटाइप आमतौर पर कुछ ही मिनटों में पूरा हो जाता है; एक बिल्ड आमतौर पर एक मिनट से काफी कम समय में पूरा होता है। किसी वास्तविक इंटीग्रेशन में आप प्रोटोटाइप की image_urls एंट्री एंड यूज़र को दिखाएंगे और बिल्ड पर क्रेडिट खर्च करने से पहले उन्हें पुष्टि करने दें (या प्रोटोटाइप को फिर से चलाने दें)।

Complete flow

POST

/openapi/creative-lab/fidget-pixel/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://...
#   export PIXEL_TYPE=person                  # or: other
: "${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
PIXEL_TYPE=${PIXEL_TYPE:-person}

BASE="https://api.meshy.ai/openapi/creative-lab/fidget-pixel/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 '{"type":"%s","image_url":"data:%s;base64,' "$PIXEL_TYPE" "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  jq -n --arg t "$PIXEL_TYPE" --arg u "$IMAGE_URL" \
    '{type: $t, image_url: $u}' >"$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 pixel-art image (show image_urls[0] to a user in production)
poll prototype "$PROTO_ID"

# 3. Create the build task (defaults: square pieces, 32x32 grid, 8 mm, 8 colors, 15 mm tall)
jq -n --arg p "$PROTO_ID" \
  '{input_task_id: $p, options: {shape: "square", grid_size: 32, piece_size_mm: 8, color_count: 8, piece_height_mm: 15}, output: {format: "3mf"}}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 4. Wait for the pieces
poll build "$BUILD_ID"

# 5. Download the 3MF. This is a signed URL: no Authorization header,
#    and it stays valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o fidget-pixel.3mf "$(jq -r '.model_urls["3mf"]' <<<"$TASK")"
echo "Done: fidget-pixel.3mf"