Creative Lab — Fidget Pixel API

แปลงภาพถ่ายต้นฉบับให้กลายเป็นบอร์ด fidget แบบพิกเซลอาร์ตหลายสีที่พิมพ์แบบ 3 มิติได้ ผ่านสองขั้นตอน: 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

ทั้งสอง endpoint แบบ POST นี้จำเป็นต้องมีการสมัครสมาชิกแบบเสียเงิน คำขอจากบัญชี แผนฟรีจะถูกปฏิเสธด้วย 402 Payment Required

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

สร้าง Fidget Pixel Prototype Task

สร้างภาพพิกเซลอาร์ตเดี่ยวจากภาพถ่ายต้นฉบับ ID ของ task ที่ได้กลับมาคือสิ่งที่คุณจะส่งเป็น input_task_id ไปยัง build endpoint หากผลลัพธ์ไม่ตรงตามที่ต้องการ ให้เรียก endpoint นี้อีกครั้งเพื่อลองใหม่อีกครั้ง — การเรียกแต่ละครั้งจะถูกคิดเครดิตแยกต่างหาก ดูรูปแบบของการตอบกลับได้ที่ The Fidget Pixel Prototype Task Object

พารามิเตอร์

Name
image_url
Type
string
จำเป็น
Description
ภาพถ่ายต้นฉบับสำหรับให้ Meshy แปลงเป็นพิกเซล ปัจจุบันรองรับรูปแบบ .jpg, .jpeg, .png, และ .webp
รูปแบบไฟล์จะถูกตรวจจับโดยการถอดรหัสข้อมูลภาพ ไม่ใช่ จากนามสกุลไฟล์ใน URL — URL ที่ไม่มีนามสกุล หรือที่มีการ redirect ก็ใช้งานได้ตราบใดที่ข้อมูลไบต์สามารถถอดรหัสเป็นรูปแบบที่รองรับได้ ระบบจะติดตาม HTTP redirect ให้
มีสองวิธีในการระบุภาพ:
- 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 — สิ่งอื่น ๆ ทั้งหมด: สัตว์เลี้ยง วัตถุ มาสคอต โลโก้ ทิวทัศน์ จะสร้างไอคอนพิกเซลสไตล์บีดอาร์ตของวัตถุนั้น
Name
name
Type
string
Description
ชื่อ task ที่ไม่บังคับ สำหรับใช้แสดงผล สูงสุด 100 ตัวอักษร

ค่าที่ส่งกลับ

พร็อพเพอร์ตี้ result ในการตอบกลับจะมี id ของ fidget pixel prototype task ที่เพิ่งสร้างขึ้น ให้ทำการ poll endpoint Get a Task หรือสมัครรับ stream จนกว่า task จะมีสถานะเป็น SUCCEEDED จากนั้นส่ง ID นั้นไปยัง build endpoint ในรูปแบบ input_task_id

รูปแบบความล้มเหลว

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 มีรูปแบบผิดพลาด
- เนื้อหาถูกตั้งค่าสถานะ: ภาพอินพุตถูกตั้งค่าสถานะโดยระบบ moderation สำหรับเนื้อหา NSFW
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับการทำงานนี้ หรือ API คีย์นี้เป็นของบัญชีแผนฟรี
Name
403 - Forbidden
Description
ภาพอินพุตถูกตั้งค่าสถานะโดยระบบ moderation ด้านทรัพย์สินทางปัญญา (Content flagged for intellectual property violation) เฉพาะบัญชี Enterprise ที่เปิดใช้งานการกรองทรัพย์สินทางปัญญาเท่านั้นที่จะถูกบล็อก และจะไม่มีการคิดเครดิตใด ๆ
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/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

สร้างงาน Build ของ Fidget Pixel

สร้างชิ้นส่วนที่พร้อมสำหรับการพิมพ์ 3D จากงาน prototype ที่สำเร็จแล้ว การ build จะสุ่มตัวอย่างภาพพิกเซลอาร์ตของ prototype ลงบนกริดที่ร้องขอ ทำการควอนไทซ์ให้เหลือสีไม่เกิน color_count สี และสร้างชิ้นส่วนที่ประกอบเข้ากันได้หนึ่งชิ้นต่อหนึ่งเซลล์ของกริด ผลลัพธ์ที่ได้คือไฟล์ 3MF เพียงไฟล์เดียวซึ่งแต่ละชิ้นส่วนเป็นวัตถุแยกกันที่ติดแท็กด้วยสีของมัน พร้อมสำหรับสไลเซอร์แบบหลายไส้พลาสติก โปรดดู The Fidget Pixel Build Task Object สำหรับรูปแบบของการตอบกลับ

พารามิเตอร์

Name
input_task_id
Type
string
จำเป็น
Description
รหัสงาน (task ID) ของงาน prototype ที่สร้างขึ้นผ่านเอนด์พอยต์ OpenAPI เดียวกันนี้ prototype ดังกล่าวต้องถูกสร้างโดยบัญชี Meshy เดียวกัน และต้องมีสถานะถึง SUCCEEDED แล้ว
งาน prototype ที่สร้างผ่านเว็บแอป ไม่ได้รับการยอมรับ — เอนด์พอยต์ build ยอมรับเฉพาะงาน prototype ที่ผลิตโดย 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 มม. เท่านั้น
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 มม. ≈ 26 ซม. ต่อด้าน ค่า 10 ไม่สามารถใช้ได้กับ shape: "hex" (เนื่องจากด้านเอียงของหกเหลี่ยมจะยื่นล้ำเกินความสามารถของเครื่องพิมพ์ FDM สำหรับผู้บริโภคทั่วไปส่วนใหญ่)
Name
color_count
Type
integer
ค่าเริ่มต้น 8
Description
จำนวนสีสูงสุดในจานสีที่ภาพจะถูกควอนไทซ์ลงไป ช่วงค่า: [1, 8] แต่ละสีจะกลายเป็นไส้พลาสติกหนึ่งชนิดในสไลเซอร์ของคุณ
Name
piece_height_mm
Type
integer
ค่าเริ่มต้น 15
Description
ความสูงของแต่ละชิ้นส่วน หน่วยเป็นมิลลิเมตร ช่วงค่า: [10, 80]

`output`

ตัวเลือกรูปแบบไฟล์ผลลัพธ์ (wire-format) ที่เลือกกำหนดได้ ค่าเริ่มต้นคือ 3mf ซึ่งปัจจุบันเป็นค่าเดียวที่รองรับ

Name
format
Type
string
ค่าเริ่มต้น 3mf
Description
ไฟล์ผลลัพธ์ที่ส่งกลับมาจากการ build ค่าที่สามารถใช้ได้:
- 3mf (ค่าเริ่มต้น) — ส่งกลับไฟล์ model.3mf เพียงไฟล์เดียวภายใต้ model_urls.3mf โดยมีหนึ่งวัตถุต่อหนึ่งชิ้นส่วน และแต่ละวัตถุจะแนบข้อมูลสีของชิ้นส่วนนั้นไว้ด้วย

ค่าที่ส่งกลับ

พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของงานสำหรับ build ของ Fidget Pixel ที่สร้างขึ้นใหม่ ให้ทำการ poll เอนด์พอยต์ Get a Task หรือสมัครรับ stream จนกว่างานจะมีสถานะถึง SUCCEEDED จากนั้นดาวน์โหลดไฟล์ผลลัพธ์จาก model_urls.3mf

รูปแบบความล้มเหลว

Name
400 - Bad Request
Description
คำขอไม่สามารถยอมรับได้ สาเหตุที่พบได้บ่อย:
- พารามิเตอร์ขาดหาย: ต้องมี input_task_id
- UUID ไม่ถูกต้อง: input_task_id ไม่ใช่ UUID ที่ถูกต้อง
- งานต้นทางยังไม่สำเร็จ: งาน prototype ที่อ้างอิงยังไม่มีสถานะถึง SUCCEEDED
- ไม่มีตัวเลือก: งาน prototype สำเร็จแล้วแต่ไม่ได้สร้างภาพพิกเซลอาร์ตขึ้นมา กรุณาสร้าง prototype ใหม่
- ค่า options เกินขอบเขต: หนึ่งในฟิลด์ของ 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
ภาพของ prototype ที่อ้างอิงถูกตรวจพบโดยระบบ moderation ด้านทรัพย์สินทางปัญญา มีเพียงบัญชี Enterprise ที่เปิดใช้งานการกรองทรัพย์สินทางปัญญาเท่านั้นที่จะถูกบล็อก และจะไม่มีการเรียกเก็บเครดิตแต่อย่างใด
Name
404 - Not Found
Description
งาน prototype ที่อ้างอิงไม่มีอยู่จริง เป็นของผู้ใช้อื่น หรือถูกสร้างขึ้นผ่านเว็บแอป (มีเพียงงาน prototype ในโหมด API เท่านั้นที่สามารถต่อยอดไปเป็น build ได้)
Name
429 - Too Many Requests
Description
คุณได้เกินขีดจำกัดของการจำกัดอัตราแล้ว
Name
500 - Internal Server Error
Description
ไม่สามารถระบุผลการตรวจสอบทรัพย์สินทางปัญญาของ prototype ที่อ้างอิงได้ (Unable to perform intellectual property check, please try again) บัญชี Enterprise ที่เปิดใช้งานการกรองทรัพย์สินทางปัญญาจะถูกปฏิเสธการดำเนินการโดยอัตโนมัติเมื่อการตรวจสอบนี้ล้มเหลว และจะไม่มีการเรียกเก็บเครดิตแต่อย่างใด — กรุณาลองส่งคำขออีกครั้ง

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

เรียกข้อมูลงาน prototype หรือ build เมื่อระบุ id ของงานที่ถูกต้อง พาธ URL ต้องตรงกับสเตจของงานนั้น ๆ — หากเรียกงาน build ผ่าน /prototype/:id จะได้ผลลัพธ์เป็น 404 และในทางกลับกันก็เช่นเดียวกัน

ดูรูปแบบการตอบกลับได้ที่ The Fidget Pixel Prototype Task Object และ The Fidget Pixel Build Task Object

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน fidget pixel ที่ต้องการเรียกข้อมูล

ผลลัพธ์ที่ได้

การตอบกลับจะประกอบด้วยอ็อบเจกต์งาน fidget pixel โดยรูปแบบจะขึ้นอยู่กับ สเตจที่ร้องขอ

รูปแบบความล้มเหลว

Name
400 - Bad Request
Description
id ไม่ใช่ UUID ที่ถูกต้อง (Invalid ID)
Name
403 - Forbidden
Description
ภาพของงานนี้ถูกตรวจพบโดยระบบ moderation ด้านทรัพย์สินทางปัญญา มีเพียงบัญชี Enterprise ที่เปิดใช้งานการกรองทรัพย์สินทางปัญญาเท่านั้นที่จะถูกบล็อก
Name
404 - Not Found
Description
งานนี้ไม่มีอยู่ เป็นของผู้ใช้รายอื่น หรือสเตจของงานไม่ตรงกับพาธ URL
Name
500 - Internal Server Error
Description
ไม่สามารถดำเนินการตรวจสอบทรัพย์สินทางปัญญาได้ (Unable to perform intellectual property check, please try again); บัญชี Enterprise ที่เปิดใช้งานการกรองทรัพย์สินทางปัญญาจะถูกปฏิเสธการเข้าถึงโดยอัตโนมัติเมื่อเกิดข้อผิดพลาด กรุณาลองส่งคำขออีกครั้ง

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 แล้วจะถูกยกเลิกโดยไม่มีการคืนเงิน (เนื่องจาก worker อาจกำลังใช้ แหล่งข้อมูลไปแล้ว) งานที่ไปถึงสถานะสุดท้ายแล้ว (SUCCEEDED, FAILED, CANCELED) ไม่สามารถยกเลิกได้

เส้นทาง URL ต้องตรงกับขั้นตอนของงาน — การใช้ DELETE ที่ /prototype/:buildId จะคืนค่า 404

พารามิเตอร์พาธ

Name
id
Type
path
Description
รหัสเฉพาะสำหรับงาน fidget pixel ที่ต้องการยกเลิก

ค่าที่ส่งกลับ

ส่งกลับ 204 No Content เมื่อสำเร็จ พร้อมเนื้อหาที่เป็นค่าว่าง

รูปแบบความล้มเหลว

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถยอมรับได้ สาเหตุที่พบบ่อยได้แก่:
- รหัสไม่ถูกต้อง: 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 Task

สตรีมการอัปเดตแบบเรียลไทม์สำหรับงาน fidget pixel ผ่าน Server-Sent Events (SSE) เส้นทาง URL ต้องตรงกับขั้นตอนของงาน — การเปิดสตรีมที่ /prototype/:buildId/stream จะส่งเพย์โหลด event: error เดี่ยว ๆ พร้อม status_code: 404 แล้วปิดสตรีม ส่วน id ที่ผิดรูปแบบก็จะเป็นเช่นเดียวกันแต่ด้วย status_code: 400 (Invalid ID)

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน fidget pixel ที่ต้องการสตรีม

ค่าที่ส่งกลับ

ส่งกลับสตรีมของอ็อบเจ็กต์งาน Fidget Pixel Prototype หรือ Fidget Pixel Build ในรูปแบบ Server-Sent Events แต่ละเฟรมจะมีอ็อบเจ็กต์งานฉบับเต็มของขั้นตอนนั้น ๆ — รูปแบบเดียวกับที่ เอนด์พอยต์ 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)

List Fidget Pixel Tasks

ดึงรายการ fidget pixel tasks ของคุณแบบแบ่งหน้าสำหรับสเตจเดียว พาธ URL เป็นตัวกำหนดสเตจ — /prototype จะคืนค่า prototype tasks; /build จะคืนค่า build tasks งานจากอีกสเตจหนึ่งจะไม่ถูกรวมอยู่ใน การตอบกลับใดๆ ทั้งสองแบบ

Path Parameters

Name
stage
Type
path
จำเป็น
Description
เป็นได้ทั้ง prototype หรือ build คอลเลกชันนี้จะคืนค่าเฉพาะงาน ที่มีสเตจตรงกับ URL เท่านั้น — การเรียก /prototype จะไม่มีทางคืนค่า build tasks และในทางกลับกันก็เช่นกัน

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

คืนค่ารายการแบบแบ่งหน้าของออบเจ็กต์งานในแต่ละสเตจ — ไม่ว่าจะเป็น ออบเจ็กต์งาน fidget pixel prototype เมื่อดึงรายการ /prototype หรือ ออบเจ็กต์งาน fidget pixel build เมื่อ ดึงรายการ /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=***"
    ]
  }
]

The Fidget Pixel Prototype Task Object

Fidget Pixel Prototype Task object คือหน่วยงานที่ Meshy ใช้ติดตามการแปลงภาพถ่ายต้นฉบับให้กลายเป็น ภาพพิกเซลอาร์ต (pixel-art image) ผลลัพธ์ของขั้นตอนนี้จะถูกส่งต่อไปยังขั้นตอนการสร้างผ่าน input_task_id

Properties

Name
id
Type
string
Description
ตัวระบุเฉพาะสำหรับ task แม้ว่าเราจะใช้ k-sortable UUID เป็นรายละเอียดการใช้งานสำหรับ task id แต่คุณไม่ควรตั้งสมมติฐานใดๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของ task ค่านี้คือ creative-lab-fidget-pixel-prototype
Name
name
Type
string
Description
ชื่อ task ที่ระบุไว้ตอนสร้าง task เป็นสตริงว่างหากไม่ได้ระบุชื่อ
Name
status
Type
string
Description
สถานะของ task ค่าที่เป็นไปได้คือค่าใดค่าหนึ่งจาก PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
progress
Type
integer
Description
progress ของ task หาก task ยังไม่เริ่มทำงาน ค่านี้จะเป็น 0 เมื่อ task สำเร็จแล้ว ค่านี้จะกลายเป็น 100
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่สร้าง task หน่วยเป็นมิลลิวินาที
ไทม์สแตมป์คือจำนวนมิลลิวินาทีที่ผ่านไปนับตั้งแต่วันที่ 1 มกราคม 1970 UTC ตามมาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 PM GMT จะแสดงเป็น 1693569600000 ซึ่งใช้กับ ไทม์สแตมป์ทั้งหมดใน Meshy API
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่เริ่ม task หน่วยเป็นมิลลิวินาที หาก task ยังไม่เริ่มทำงาน ค่านี้จะเป็น null
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น หน่วยเป็นมิลลิวินาที หาก task ยังไม่เสร็จสิ้น ค่านี้จะเป็น null
Name
expires_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ผลลัพธ์ของ task จะหมดอายุ หน่วยเป็นมิลลิวินาที — 3 วันหลังจากที่ task เสร็จสิ้น บัญชี Enterprise จะเก็บผลลัพธ์ของ API ไว้อย่างไม่มีกำหนด (ดู Asset Retention) สำหรับบัญชีเหล่านี้ ไทม์สแตมป์นี้จะถูกตั้งไว้ล่วงหน้าประมาณ 100 ปี
Name
preceding_tasks
Type
integer
Description
จำนวน task ที่อยู่ก่อนหน้า
ค่าของฟิลด์นี้มีความหมายก็ต่อเมื่อสถานะของ task เป็น PENDING
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับ task ที่ล้มเหลว ดู ข้อผิดพลาด สำหรับข้อมูลอ้างอิงแบบเต็มของออบเจ็กต์ task_error
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ใช้ไปโดย task นี้ task ที่มีสถานะถึง SUCCEEDED จะถูกเรียกเก็บเต็มจำนวนสำหรับขั้นตอนนั้น task ที่ไม่เคยถูกสร้างขึ้นเลย (เกิด 4xx ตอนที่ทำการร้องขอ รวมถึงการถูกปฏิเสธจาก moderation) จะไม่ถูกเรียกเก็บเงินเลย task ที่มีสถานะถึง FAILED จะคืนค่า 0 — ค่าใช้จ่ายจะถูกคืนเงิน การยกเลิกผ่าน DELETE จะคืนเงินได้เฉพาะเมื่อ task ยังอยู่ในสถานะ PENDING เท่านั้น ส่วน task ที่อยู่ในสถานะ IN_PROGRESS แล้วจะยังคงถูกเรียกเก็บเงิน เนื่องจากงานได้ถูกดำเนินการไปแล้ว
Name
image_urls
Type
array of strings
Description
URL สำหรับดาวน์โหลดภาพพิกเซลอาร์ตที่สร้างโดย prototype task นี้ ปัจจุบัน API จะคืนค่าภาพเพียงหนึ่งภาพเสมอ ฟิลด์นี้จึงเป็นอาร์เรย์เพื่อให้เวอร์ชันในอนาคตสามารถแสดงตัวเลือกหลายภาพได้โดยไม่ทำให้เกิดการเปลี่ยนแปลงที่ทำลายความเข้ากันได้ ฟิลด์นี้จะว่างเปล่าจนกว่า task จะมีสถานะถึง SUCCEEDED
URL เหล่านี้เป็น signed URL: ให้เรียกใช้งานโดยไม่ต้องใส่ header Authorization URL เหล่านี้จะยังคงใช้งานได้จนถึง expires_at ซึ่งคือ 3 วันหลังจาก finished_at และการอ่าน task ซ้ำภายในช่วงเวลานั้นจะได้ 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 Object คือหน่วยงานที่ Meshy ใช้ติดตามเพื่อสร้างชิ้นส่วนที่พิมพ์ได้จากงาน prototype ที่สำเร็จแล้ว การ build จะสุ่มตัวอย่างภาพพิกเซลอาร์ตของ prototype ลงบนกริดที่ร้องขอ และเผยแพร่ 3MF ที่ติดแท็กสีเดียว

คุณสมบัติ

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
ไทม์สแตมป์ของเวลาที่ผลลัพธ์ของงานจะหมดอายุ หน่วยเป็นมิลลิวินาที — 3 วันหลังจากที่งานเสร็จสิ้น บัญชี Enterprise จะเก็บผลลัพธ์ของ API ไว้อย่างไม่มีกำหนด (ดู การเก็บรักษาแอสเซ็ต) สำหรับบัญชีเหล่านี้ ไทม์สแตมป์นี้จะถูกตั้งค่าไว้ล่วงหน้าประมาณ 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 ของคำขอ build ว่างเปล่าจนกว่างานจะมีสถานะถึง SUCCEEDED
URL เหล่านี้เป็น URL ที่มีการเซ็นชื่อ: ดึงข้อมูลโดยไม่ต้องใช้ส่วนหัว Authorization URL เหล่านี้จะยังคงใช้งานได้จนถึง expires_at ซึ่งคือ 3 วันหลังจาก finished_at และการอ่านงานซ้ำภายในช่วงเวลานั้นจะคืนค่า URL เดิมแทนที่จะเป็น URL ที่เซ็นชื่อใหม่ ดังนั้นควรดาวน์โหลดและจัดเก็บไฟล์ด้วยตัวเองก่อนถึงเวลานั้น — ไม่มีวิธีใดที่จะรีเฟรชลิงก์ที่หมดอายุแล้วได้
- Name
  3mf
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ 3MF หนึ่งอ็อบเจ็กต์ต่อหนึ่งชิ้นส่วน แต่ละชิ้นถูกติดแท็กด้วยสีจากพาเลตของมัน ดังนั้นสไลเซอร์แบบหลายฟิลาเมนต์จะกำหนดฟิลาเมนต์ตามสีให้ มีค่าเมื่อ 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=***"
  }
}

ตัวอย่างแบบครบวงจร

ขั้นตอนที่สมบูรณ์: สร้างต้นแบบ (prototype) จากภาพถ่าย, poll จนกว่าจะได้สถานะ SUCCEEDED, สร้างงานประกอบ (build) จากต้นแบบนั้น, poll งานประกอบจนกว่าจะได้สถานะ SUCCEEDED แล้วจึงดาวน์โหลดไฟล์ 3MF จาก model_urls

โดยทั่วไปต้นแบบจะเสร็จภายในไม่กี่นาที ส่วนงานประกอบมักจะเสร็จภายในเวลาไม่ถึงหนึ่งนาที ในการเชื่อมต่อจริง คุณควรแสดงรายการ 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"