lowpoly จะยุติการให้บริการในวันที่ 30 ต.ค. 2569 โปรดเปลี่ยนโมเดลก่อนวันที่เหล่านี้เพื่อหลีกเลี่ยงข้อผิดพลาดของคำขอ ดูการเลิกใช้งานทั้งหมด

Creative Lab Fidget Pixel API

แปลงรูปภาพให้เป็นแผ่นฟิดเจ็ตแบบพิกเซลอาร์ตหลายสีที่พิมพ์ 3 มิติได้ ผ่านสองขั้นตอน งาน prototype จะแปลงรูปภาพให้เป็นภาพพิกเซลอาร์ต ส่วนงาน build จะแปลงภาพนั้นให้เป็นชิ้นส่วนที่ประกอบเข้าด้วยกันได้ในไฟล์ 3MF ไฟล์เดียว โดยใช้ ID ของงาน prototype เป็น input_task_id

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

endpoint แบบ POST ทั้งสองตัวต้องใช้แพลนแบบชำระเงิน คำขอจากบัญชีแพลนฟรีจะได้รับผลลัพธ์เป็น 402

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

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

สร้างภาพพิกเซลอาร์ตหนึ่งภาพจากรูปถ่าย เพื่อสร้างชิ้นส่วน ให้ส่ง ID ของงานนี้ไปยัง build endpoint ในชื่อ input_task_id สำหรับฟิลด์ของงาน ดูที่ The Fidget Pixel prototype task object

หากคุณไม่ชอบภาพที่ได้ ให้สร้างงาน prototype ใหม่อีกครั้ง แต่ละงานจะถูกคิดเครดิตแยกกัน

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

พารามิเตอร์

  • Name
    image_url
    Type
    string
    จำเป็น
    Description

    รูปถ่ายที่จะแปลงเป็นพิกเซลอาร์ต ในรูปแบบ URL สาธารณะ หรือ data URI (data:image/jpeg;base64,<your base64-encoded image data>)

    รูปภาพต้องเป็นไฟล์ JPG, JPEG, PNG หรือ WebP ที่มีขนาดไม่เกิน 20 MB Meshy จะตรวจจับรูปแบบไฟล์จากข้อมูลภาพ ไม่ใช่จากนามสกุลไฟล์ใน URL URL ที่ไม่มีนามสกุลก็ใช้งานได้ และ Meshy จะติดตามการเปลี่ยนเส้นทาง (redirect)

  • Name
    type
    Type
    string
    จำเป็น
    Description

    สิ่งที่ปรากฏในรูปถ่าย ซึ่งจะกำหนดสไตล์ของพิกเซลอาร์ต ทั้งสองสไตล์มีความแตกต่างกันอย่างชัดเจน ค่าอื่นใดนอกเหนือจากนี้จะคืนค่า 400

    ค่าที่ใช้ได้:

    • person: บุคคล ในรูปถ่ายแบบครึ่งตัวหรือเต็มตัว Meshy จะวาดสไปรต์พิกเซลสไตล์ชิบิ
    • other: วัตถุอื่นใด เช่น สัตว์เลี้ยง สิ่งของ มาสคอต โลโก้ หรือภูมิทัศน์ Meshy จะวาดไอคอนพิกเซลสไตล์บีดอาร์ต
  • Name
    name
    Type
    string
    Description

    ชื่อสำหรับงาน ยาวได้สูงสุด 100 ตัวอักษร ชื่อนี้จะถูกส่งกลับมาในฟิลด์ name ของงาน ชื่อที่ยาวเกินไปจะคืนค่า 400

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

ฟิลด์ result จะเก็บ ID ของงาน prototype ใหม่ ดึงข้อมูลงาน หรือ สตรีมข้อมูลงาน จนกว่า status จะเป็น SUCCEEDED จากนั้นจึงส่ง ID ไปยัง build endpoint ในชื่อ input_task_id

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

  • Name
    400 - Bad Request
    Description

    คำขอนี้ไม่สามารถทำงานได้ ตัวอย่างเช่น:

    • ไม่มี image_url หรือ type
    • type ไม่ใช่ person หรือ other
    • รูปภาพไม่ใช่ไฟล์ JPG, JPEG, PNG หรือ WebP
    • รูปภาพมีขนาดเล็กเกินไป เกิน 20 MB หรือเกินจำนวนพิกเซลสูงสุด
    • Meshy ไม่สามารถดาวน์โหลดรูปภาพได้ เช่น เพราะ URL คืนค่า 404 หรือหมดเวลา
    • data URI ไม่ใช่ base64 ที่ถูกต้อง
    • รูปภาพถูกตั้งค่าสถานะว่าเป็นเนื้อหาไม่เหมาะสม (NSFW)

    ข้อความแสดงข้อผิดพลาดจะระบุว่าพบปัญหาใด แก้ไขคำขอแล้วส่งอีกครั้ง

  • Name
    401 - Unauthorized
    Description

    API คีย์หายไปหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization

  • Name
    402 - Payment Required
    Description

    เงื่อนไขอย่างใดอย่างหนึ่งต่อไปนี้เป็นจริง:

    • บัญชีมีเครดิตไม่เพียงพอ
    • API คีย์ พื้นที่ทำงาน หรือสมาชิกถึงขีดจำกัดเครดิตแล้ว
    • บัญชีอยู่บนแผนฟรี

    ตรวจสอบเครดิตและแผนของคุณ แล้วลองใหม่

  • Name
    403 - Forbidden
    Description

    ทีมของคุณเปิดใช้งาน IP Filtering และ Meshy ตั้งค่าสถานะรูปภาพนี้ว่าเกี่ยวข้องกับทรัพย์สินทางปัญญาของบุคคลที่สาม โปรดส่งรูปภาพที่คุณมีสิทธิ์ใช้งาน

  • Name
    429 - Too Many Requests
    Description

    ถึงขีดจำกัดข้อใดข้อหนึ่งต่อไปนี้:

    • คุณส่งคำขอมากกว่าที่การจำกัดอัตราของคุณอนุญาต รอสักครู่แล้วลองใหม่ ดู Rate limits
    • มีงานของคุณที่อยู่ในคิวหรือกำลังทำงานมากเกินไป รอให้บางงานเสร็จสิ้นแล้วลองใหม่
    • หากอยู่บนแผนไม่จำกัดแต่ไม่มีเครดิตเหลือ คุณถึงจำนวนงานสูงสุดที่สามารถทำงานได้โดยไม่ใช้เครดิตแล้ว รอให้งานเสร็จสิ้น หรือเติมเครดิต
  • Name
    500 - Internal Server Error
    Description

    Meshy พบข้อผิดพลาดของเซิร์ฟเวอร์ เช่น เนื่องจากไม่สามารถตรวจสอบทรัพย์สินทางปัญญาของรูปภาพได้ Meshy จะไม่สร้างงาน และคืนเครดิตใด ๆ ที่เรียกเก็บไปแล้ว โปรดลองคำขออีกครั้ง

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

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

สร้างชิ้นส่วนที่พิมพ์ 3 มิติได้จากงาน prototype ที่สำเร็จแล้ว Meshy จะสุ่มตัวอย่างภาพพิกเซลอาร์ตลงบนกริด และลดจำนวนสีลงเหลือไม่เกิน color_count สี แต่ละเซลล์ของตัวแบบจะกลายเป็นชิ้นส่วนที่ประกอบล็อกเข้ากันได้ และพื้นหลังจะไม่ถูกพิมพ์

ผลลัพธ์คือไฟล์ 3MF แบบหลายสีไฟล์เดียว พร้อมพิมพ์เป็นสีได้ทันที แต่ละชิ้นส่วนมีตัวสีเทาและส่วนบนเป็นสีของพิกเซลนั้น สำหรับฟิลด์ต่าง ๆ ดูที่ The Fidget Pixel build task object

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

พารามิเตอร์

  • Name
    input_task_id
    Type
    string
    จำเป็น
    Description

    ID ของงาน prototype ที่จะ build ต้องเป็นงานที่บัญชีของคุณสร้างด้วย POST /openapi/creative-lab/fidget-pixel/v1/prototype และมีสถานะเป็น SUCCEEDED

    ID ที่ไม่ใช่งาน prototype ของ Fidget Pixel จาก API ของบัญชีคุณจะคืนค่า 404 รวมถึง prototype ที่สร้างในเว็บแอปด้วย

  • Name
    name
    Type
    string
    Description

    ชื่อสำหรับงาน ได้สูงสุด 100 ตัวอักษร ชื่อนี้จะถูกส่งกลับมาในฟิลด์ name ของงาน หากชื่อยาวเกินไปจะคืนค่า 400

options

การตั้งค่ารูปทรงและขนาดของชิ้นส่วน ทุกฟิลด์มีค่าเริ่มต้น ดังนั้นส่งเฉพาะฟิลด์ที่คุณต้องการเปลี่ยนเท่านั้น ค่า 0 จะใช้ค่าเริ่มต้นของฟิลด์นั้น การตั้งค่าเหล่านี้เหมือนกับในเว็บแอป Creative Lab การตั้งค่ารูปทรงอื่น ๆ ถูกกำหนดตายตัว และ Meshy จะตั้งค่าตามจาก shape และ piece_size_mm

  • Name
    shape
    Type
    string
    ค่าเริ่มต้น square
    Description

    รูปทรงฐานของแต่ละชิ้นส่วน ค่าอื่นใดนอกเหนือจากนี้จะคืนค่า 400

    ค่าที่ใช้ได้:

    • square: ชิ้นส่วนสี่เหลี่ยมบนกริดสี่เหลี่ยม
    • hex: ชิ้นส่วนหกเหลี่ยมบนกริดหกเหลี่ยม โดยตั้งค่า piece_size_mm เป็น 6 หรือ 8
  • Name
    grid_size
    Type
    integer
    ค่าเริ่มต้น 32
    Description

    จำนวนเซลล์กริดตามแต่ละด้านของบอร์ด 16 หรือ 32 ค่าอื่นใดนอกเหนือจากนี้จะคืนค่า 400 กริด 32 จะเก็บรายละเอียดได้มากกว่า ส่วนกริด 16 จะให้ชิ้นส่วนน้อยกว่าในขนาดเดียวกัน ทำให้บอร์ดมีความกว้างประมาณครึ่งหนึ่ง

  • Name
    piece_size_mm
    Type
    integer
    ค่าเริ่มต้น 8
    Description

    ความยาวขอบของแต่ละชิ้นส่วนในหน่วยมิลลิเมตร 6, 8, หรือ 10 ค่าอื่นใดนอกเหนือจากนี้จะคืนค่า 400 เมื่อใช้ร่วมกับ grid_size จะกำหนดขนาดของบอร์ดที่พิมพ์ ตัวอย่างเช่น กริด 32 ของชิ้นส่วนขนาด 8 มม. จะมีขนาดประมาณ 26.5 ซม. ต่อด้าน

    10 ใช้ไม่ได้กับ hex และจะคืนค่า 400 เนื่องจากหน้าหกเหลี่ยมที่เอียงจะยื่นเกินในเครื่องพิมพ์ FDM สำหรับผู้บริโภคส่วนใหญ่

  • Name
    color_count
    Type
    integer
    ค่าเริ่มต้น 8
    Description

    จำนวนสีสูงสุดในจานสีของพิกเซลอาร์ต ตั้งแต่ 1 ถึง 8 ค่าที่อยู่นอกช่วงนี้จะคืนค่า 400 ในการพิมพ์ คุณจะต้องใช้เส้นพลาสติกสูงสุด color_count บวกหนึ่งเส้น หนึ่งเส้นต่อหนึ่งสี และอีกหนึ่งเส้นสำหรับตัวชิ้นส่วนสีเทา

  • Name
    piece_height_mm
    Type
    integer
    ค่าเริ่มต้น 15
    Description

    ความสูงของแต่ละชิ้นส่วนในหน่วยมิลลิเมตร ตั้งแต่ 10 ถึง 80 ค่าที่อยู่นอกช่วงนี้จะคืนค่า 400

output

การตั้งค่าสำหรับไฟล์ผลลัพธ์

  • Name
    format
    Type
    string
    ค่าเริ่มต้น 3mf
    Description

    รูปแบบไฟล์ของผลลัพธ์ ค่าอื่นใดนอกเหนือจากนี้จะคืนค่า 400

    ค่าที่ใช้ได้:

    • 3mf: ไฟล์ model.3mf แบบหลายสีไฟล์เดียว ส่งกลับมาใน model_urls.3mf

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

ฟิลด์ result เก็บ ID ของงาน build ใหม่ รับงาน หรือ สตรีมงาน จนกว่า status จะเป็น SUCCEEDED จากนั้นดาวน์โหลดไฟล์ 3MF จาก model_urls.3mf

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

  • Name
    400 - Bad Request
    Description

    คำขอไม่สามารถทำงานได้ ตัวอย่างเช่น:

    • input_task_id ขาดหายไปหรือไม่ใช่ ID งานที่ถูกต้อง
    • สถานะของงาน prototype ไม่ใช่ SUCCEEDED หากยังทำงานอยู่ ให้รอแล้วลองใหม่ หากล้มเหลวหรือถูกยกเลิก ให้สร้างงาน prototype ใหม่
    • งาน prototype สำเร็จแล้วแต่ไม่มีภาพ ให้สร้างงาน prototype ใหม่
    • ฟิลด์ options อยู่นอกค่าที่อนุญาต เช่น grid_size ที่ไม่ใช่ 16 หรือ 32
    • piece_size_mm เป็น 10 และ shape เป็น hex ชิ้นส่วนหกเหลี่ยมมีเฉพาะขนาด 6 และ 8 มม. เท่านั้น
    • output.format ไม่ใช่ 3mf

    ข้อความแสดงข้อผิดพลาดจะระบุว่าพบปัญหาใด

  • Name
    401 - Unauthorized
    Description

    API คีย์ขาดหายไปหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization

  • Name
    402 - Payment Required
    Description

    หนึ่งในกรณีต่อไปนี้:

    • บัญชีมีเครดิตไม่เพียงพอ
    • API คีย์ พื้นที่ทำงาน หรือสมาชิกถึงขีดจำกัดเครดิตแล้ว
    • บัญชีอยู่ในแผนฟรี

    ตรวจสอบเครดิตและแผนของคุณ แล้วลองใหม่

  • Name
    403 - Forbidden
    Description

    ทีมของคุณเปิดใช้งาน IP Filtering และ Meshy ตรวจพบว่าภาพในงาน prototype ละเมิดทรัพย์สินทางปัญญาของบุคคลที่สาม ให้สร้างงาน prototype จากภาพที่คุณมีสิทธิ์ใช้งาน

  • Name
    404 - Not Found
    Description

    input_task_id ไม่ตรงกับงาน prototype ของ Fidget Pixel ใด ๆ ที่บัญชีของคุณสร้างด้วย API prototype ที่สร้างในเว็บแอปก็จะคืนค่า 404 เช่นกัน ให้ส่ง ID ของ result จากการตอบกลับการสร้าง prototype

  • Name
    429 - Too Many Requests
    Description

    ถึงขีดจำกัดข้อใดข้อหนึ่งต่อไปนี้:

    • คุณส่งคำขอมากกว่าที่การจำกัดอัตราของคุณอนุญาต ให้รอสักครู่แล้วลองใหม่ ดู Rate limits
    • มีงานของคุณที่อยู่ในคิวหรือกำลังทำงานมากเกินไป ให้รอจนกว่างานบางส่วนจะเสร็จสิ้นแล้วลองใหม่
    • หากอยู่ในแผนไม่จำกัดและไม่มีเครดิตเหลือ คุณถึงจำนวนงานสูงสุดที่สามารถรันได้โดยไม่ใช้เครดิตแล้ว ให้รอจนกว่างานจะเสร็จสิ้น หรือเพิ่มเครดิต
  • Name
    500 - Internal Server Error
    Description

    Meshy พบข้อผิดพลาดของเซิร์ฟเวอร์ เช่น ไม่สามารถตรวจสอบทรัพย์สินทางปัญญาของภาพในงาน prototype ได้ Meshy จะไม่สร้างงานนี้ และคืนเครดิตใด ๆ ที่เรียกเก็บไปแล้ว ให้ลองส่งคำขอใหม่

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

ดึงข้อมูลงาน Fidget Pixel

ส่งคืนงาน prototype หรือ build พาธที่ใช้ต้องตรงกับขั้นตอน (stage) ของงานนั้น หากส่งคำของาน build ผ่าน /prototype/:id จะได้รับ 404 และในทำนองเดียวกัน หากส่งคำของาน prototype ผ่าน /build/:id ก็จะได้รับ 404 เช่นกัน

สำหรับฟิลด์ต่าง ๆ โปรดดู The Fidget Pixel prototype task object และ The Fidget Pixel build task object

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

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

    รหัสงานจากการตอบกลับตอนสร้าง

ค่าที่ส่งคืน

prototype task object หรือ build task object ขึ้นอยู่กับขั้นตอนที่ตรงกับพาธที่ใช้

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

  • Name
    400 - Bad Request
    Description

    id ไม่ใช่รหัสงานที่ถูกต้อง ให้ส่งรหัส result จากการตอบกลับตอนสร้าง

  • Name
    403 - Forbidden
    Description

    ทีมของคุณเปิดใช้งาน IP Filtering และ Meshy ตรวจพบว่ารูปภาพของงาน prototype มีการติดธงเรื่องทรัพย์สินทางปัญญาของบุคคลที่สาม งาน build และทีมที่ใช้แผน Enterprise จะไม่ได้รับข้อผิดพลาดนี้ ให้สร้างงาน prototype จากรูปภาพที่คุณมีสิทธิ์ใช้งาน

  • Name
    404 - Not Found
    Description

    ไม่พบงาน Fidget Pixel ที่มีรหัสนี้อยู่ในบัญชีของคุณ หรือขั้นตอนของงานไม่ตรงกับพาธที่ใช้ ตรวจสอบรหัส และใช้ /prototype หรือ /build ให้ตรงกับงานนั้น

  • Name
    500 - Internal Server Error
    Description

    Meshy ไม่สามารถตรวจสอบทรัพย์สินทางปัญญาได้ กรุณาลองส่งคำขออีกครั้ง

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

ลบงาน Fidget Pixel

ยกเลิกงาน Fidget Pixel การยกเลิกงานที่มีสถานะ PENDING จะคืนเครดิตให้ ส่วนงานที่มีสถานะ IN_PROGRESS จะถูกยกเลิกโดยไม่มีการคืนเครดิต เนื่องจาก worker ได้เริ่มดำเนินการไปแล้ว งานที่มีสถานะสุดท้าย (SUCCEEDED, FAILED หรือ CANCELED) ไม่สามารถยกเลิกได้

พาธต้องตรงกับขั้นตอนของงานนั้น ตัวอย่างเช่น การเรียก DELETE ที่ /prototype/:id โดยใช้ ID ของงานในขั้นตอน build จะคืนค่า 404

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

Path parameters

  • Name
    id
    Type
    path
    Description

    ID ของงานที่ต้องการยกเลิก

Returns

204 No Content พร้อม body ว่างเปล่า

Failure modes

  • Name
    400 - Bad Request
    Description

    หนึ่งในกรณีต่อไปนี้:

    • id ไม่ใช่ ID งานที่ถูกต้อง ให้ส่ง ID result จากคำตอบของการสร้างงาน
    • งานนี้มีสถานะสุดท้ายอยู่แล้ว (SUCCEEDED, FAILED หรือ CANCELED) จึงไม่สามารถยกเลิกได้
  • Name
    404 - Not Found
    Description

    ไม่มีงาน Fidget Pixel ที่มี ID นี้อยู่ในบัญชีของคุณ หรือขั้นตอนของงานไม่ตรงกับพาธที่ใช้ ตรวจสอบ ID และใช้ /prototype หรือ /build ให้ตรงกับงานนั้น

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

Stream งานของ Fidget Pixel

สตรีมการอัปเดตของงาน Fidget Pixel ในรูปแบบ Server-Sent Events (SSE) พาธที่ใช้ต้องตรงกับขั้นตอนของงานนั้น ถ้าไม่ตรง เช่น ใช้ ID ของ build task ที่ /prototype/:id/stream สตรีมจะส่งอีเวนต์ error หนึ่งรายการด้วย status_code: 404 แล้วปิดการเชื่อมต่อ หาก id ไม่ใช่ task ID ที่ถูกต้อง ก็จะเกิดผลลัพธ์แบบเดียวกันแต่ด้วย status_code: 400

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

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

    Task ID จากการตอบกลับตอนสร้างงาน

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

สตรีมของอ็อบเจ็กต์งาน prototype หรือ build แต่ละอีเวนต์จะมีอ็อบเจ็กต์งานฉบับเต็ม เช่นเดียวกับที่ ดึงข้อมูลงานของ Fidget Pixel ส่งกลับมา ในขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ผลลัพธ์ของงานจะยังว่างอยู่ (null, [], หรือ {}) และ finished_at จะเป็น null

หาก IP Filtering บล็อกผลลัพธ์ของงาน สตรีมจะส่งอีเวนต์ error หนึ่งรายการแทน โดยมี status_code เดียวกับที่คำขอแบบ get จะส่งกลับ

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

List Fidget Pixel tasks

คืนค่างาน Fidget Pixel ของคุณในขั้นตอนใดขั้นตอนหนึ่ง ครั้งละหนึ่งหน้า พาธจะเป็นตัวกำหนดขั้นตอน /prototype จะคืนค่าเฉพาะงานในขั้นตอน prototype และ /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=***"
    ]
  }
]

พารามิเตอร์พาธ (Path parameters)

  • Name
    stage
    Type
    path
    จำเป็น
    Description

    ขั้นตอนที่ต้องการแสดงรายการ prototype หรือ build

พารามิเตอร์คิวรี (Query parameters)

  • Name
    page_num
    Type
    integer
    ค่าเริ่มต้น 1
    Description

    หน้าที่ต้องการคืนค่า ตั้งแต่ 1 ถึง 255 ค่า 0 จะคืนค่าหน้าแรก ค่าที่อยู่นอกช่วง 0 ถึง 255 จะคืนค่า 400

  • Name
    page_size
    Type
    integer
    ค่าเริ่มต้น 10
    Description

    จำนวนงานต่อหน้า สูงสุด 100 ค่าตั้งแต่ 101 ถึง 255 จะคืนค่า 100 งาน และค่า 0 จะใช้ค่าเริ่มต้น ค่าที่อยู่นอกช่วง 0 ถึง 255 จะคืนค่า 400

  • Name
    sort_by
    Type
    string
    ค่าเริ่มต้น -created_at
    Description

    ลำดับการเรียง

    ค่าที่ใช้ได้:

    • -created_at: ใหม่สุดก่อน
    • +created_at: เก่าสุดก่อน

ค่าที่คืนกลับ

อาร์เรย์ของ ออบเจ็กต์งาน prototype หรือ ออบเจ็กต์งาน build ตามขั้นตอนที่ระบุในพาธ

อ็อบเจกต์งาน prototype ของ Fidget Pixel

งาน prototype จะแปลงรูปภาพให้กลายเป็นภาพแบบพิกเซลอาร์ต (pixel-art) เพื่อแปลงภาพนั้นให้กลายเป็นชิ้นส่วนที่พิมพ์ 3 มิติได้ ให้ส่ง ID ของงานไปยัง build endpoint ในชื่อ input_task_id

คุณสมบัติ

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=***"
  ]
}
  • Name
    id
    Type
    string
    Description

    ID ของงาน อย่าอ้างอิงตามรูปแบบของมัน

  • Name
    type
    Type
    string
    Description

    ประเภทของงาน ซึ่งจะเป็น creative-lab-fidget-pixel-prototype เสมอ

  • Name
    name
    Type
    string
    Description

    ค่า name ที่คุณส่งมาตอนสร้างงาน หรือ "" หากคุณไม่ได้ส่งค่านี้มา

  • Name
    status
    Type
    string
    Description

    สถานะของงาน

    ค่าที่เป็นไปได้:

    • PENDING: กำลังรอในคิว
    • IN_PROGRESS: กำลังสร้างผลลัพธ์
    • SUCCEEDED: สถานะสุดท้าย พร้อมผลลัพธ์
    • FAILED: สถานะสุดท้าย พร้อมเหตุผลใน task_error
    • CANCELED: สถานะสุดท้าย โดยไม่มีผลลัพธ์
  • Name
    progress
    Type
    integer
    Description

    เปอร์เซ็นต์ของงานที่ทำเสร็จแล้ว ตั้งแต่ 0 ถึง 100 ค่านี้จะเป็น 0 จนกว่างานจะเริ่ม และเป็น 100 เมื่องานสำเร็จ

  • Name
    created_at
    Type
    timestamp
    Description

    เวลาที่สร้างงาน หน่วยเป็นมิลลิวินาทีแบบ Unix

  • Name
    started_at
    Type
    timestamp
    Description

    เวลาที่ worker เริ่มทำงานนี้ หน่วยเป็นมิลลิวินาทีแบบ Unix โดยจะเป็น null จนกว่าจะถึงเวลานั้น

  • Name
    finished_at
    Type
    timestamp
    Description

    เวลาที่งานถึงสถานะสุดท้าย หน่วยเป็นมิลลิวินาทีแบบ Unix โดยจะเป็น null จนกว่าจะถึงเวลานั้น

  • Name
    expires_at
    Type
    timestamp
    Description

    เวลาที่ผลลัพธ์ของงานจะหมดอายุ หน่วยเป็นมิลลิวินาทีแบบ Unix ซึ่งจะเป็น 3 วันหลังจาก finished_at หรือ 3 วันหลังจาก created_at จนกว่างานจะเสร็จสิ้น สำหรับบัญชี Enterprise ซึ่งจะเก็บผลลัพธ์ของ API ไว้อย่างไม่มีกำหนด ค่านี้จะเป็นประมาณ 100 ปีถัดไป ดูเพิ่มเติมที่ การเก็บรักษาแอสเซ็ต

  • Name
    preceding_tasks
    Type
    integer
    Description

    ตำแหน่งของงานในคิวขณะที่สถานะเป็น PENDING ค่า 1 หมายความว่างานนี้จะเริ่มเป็นลำดับถัดไป และเป็น 0 หลังจากงานออกจากคิวแล้ว และจะเป็น 0 เสมอในผลลัพธ์แบบรายการ

  • Name
    task_error
    Type
    object
    Description

    เหตุผลที่งานล้มเหลว จะเป็น null ยกเว้นเมื่อ status เป็น FAILED ดูเพิ่มเติมที่ ข้อผิดพลาด

  • Name
    consumed_credits
    Type
    integer
    Description

    จำนวนเครดิตที่ถูกเรียกเก็บสำหรับงานนี้ หลังหักการคืนเงินใด ๆ แล้ว คำขอที่คืนค่าข้อผิดพลาดจะไม่ถูกเรียกเก็บเครดิต งานที่ล้มเหลวจะมีค่าเป็น 0 เนื่องจาก Meshy จะคืนเครดิตให้ การยกเลิกงานจะคืนเครดิตให้ก็ต่อเมื่องานยังอยู่ในสถานะ PENDING เท่านั้น หาก Meshy ไม่สามารถอ่านค่าการเรียกเก็บเงินได้ การตอบกลับแบบ get หรือ stream จะไม่มีฟิลด์นี้ และคำขอแบบ list จะคืนค่า 500 ในกรณีนี้ ให้ลองส่งคำขอใหม่อีกครั้ง

  • Name
    image_urls
    Type
    array of strings
    Description

    URL สำหรับดาวน์โหลดภาพพิกเซลอาร์ต อาร์เรย์นี้จะมี URL หนึ่งรายการหลังจากงานสำเร็จ และจะว่างเปล่าจนกว่าจะถึงตอนนั้น

    URL เหล่านี้ถูกเซ็นไว้ จึงสามารถดึงข้อมูลได้โดยไม่ต้องใส่ header Authorization URL เหล่านี้จะใช้งานได้จนถึง expires_at การดึงข้อมูลงานนี้อีกครั้งก่อนถึงเวลานั้นจะคืนค่า URL ชุดเดิม ไม่ใช่ URL ที่เซ็นใหม่ URL ที่หมดอายุแล้วไม่สามารถรีเฟรชได้ ดังนั้นควรดาวน์โหลดและจัดเก็บไฟล์ไว้ก่อนที่จะถึงเวลานั้น

ออบเจ็กต์ Fidget Pixel build task

build task จะสร้างชิ้นส่วนที่พิมพ์ 3 มิติได้จากงาน prototype ที่สำเร็จแล้ว Meshy จะสุ่มตัวอย่างภาพ pixel-art ลงบนกริด และส่งคืนชิ้นส่วนทั้งหมดในไฟล์ 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=***"
  }
}
  • Name
    id
    Type
    string
    Description

    รหัสของ task อย่าอ้างอิงตามรูปแบบของมัน

  • Name
    type
    Type
    string
    Description

    ประเภทของ task ซึ่งจะเป็น creative-lab-fidget-pixel-build เสมอ

  • Name
    name
    Type
    string
    Description

    ค่า name ที่คุณส่งมาตอนสร้าง task หรือเป็น "" หากคุณไม่ได้ส่งมา

  • Name
    status
    Type
    string
    Description

    สถานะของ task

    ค่าที่เป็นไปได้:

    • PENDING: กำลังรอในคิว
    • IN_PROGRESS: กำลังสร้างผลลัพธ์
    • SUCCEEDED: สถานะสุดท้าย พร้อมผลลัพธ์
    • FAILED: สถานะสุดท้าย พร้อมเหตุผลใน task_error
    • CANCELED: สถานะสุดท้าย โดยไม่มีผลลัพธ์
  • Name
    progress
    Type
    integer
    Description

    เปอร์เซ็นต์ของงานที่เสร็จแล้ว ตั้งแต่ 0 ถึง 100 ค่านี้จะเป็น 0 จนกว่า task จะเริ่มทำงาน และเป็น 100 เมื่อสำเร็จ

  • Name
    created_at
    Type
    timestamp
    Description

    เวลาที่สร้าง task เป็นหน่วยมิลลิวินาทีแบบ Unix

  • Name
    started_at
    Type
    timestamp
    Description

    เวลาที่ worker เริ่มทำ task เป็นหน่วยมิลลิวินาทีแบบ Unix จะเป็น null จนกว่าจะเริ่ม

  • Name
    finished_at
    Type
    timestamp
    Description

    เวลาที่ task ถึงสถานะสุดท้าย เป็นหน่วยมิลลิวินาทีแบบ Unix จะเป็น null จนกว่าจะถึง

  • Name
    expires_at
    Type
    timestamp
    Description

    เวลาที่ผลลัพธ์ของ task จะหมดอายุ เป็นหน่วยมิลลิวินาทีแบบ Unix ค่านี้คือ 3 วันหลังจาก finished_at หรือ 3 วันหลังจาก created_at จนกว่า task จะเสร็จสิ้น สำหรับบัญชี Enterprise ซึ่งเก็บผลลัพธ์ของ API ไว้ตลอดไป ค่านี้จะอยู่ที่ประมาณ 100 ปีให้หลัง ดู การเก็บรักษาแอสเซ็ต

  • Name
    preceding_tasks
    Type
    integer
    Description

    ตำแหน่งของ task ในคิวขณะที่มีสถานะเป็น PENDING ค่า 1 หมายความว่า task นี้จะเริ่มถัดไป และเป็น 0 หลังจาก task ออกจากคิวแล้ว และเป็น 0 เสมอในผลลัพธ์แบบรายการ

  • Name
    task_error
    Type
    object
    Description

    เหตุผลที่ task ล้มเหลว จะเป็น null ยกเว้นเมื่อ status เป็น FAILED ดู ข้อผิดพลาด

  • Name
    consumed_credits
    Type
    integer
    Description

    จำนวนเครดิตที่ถูกเรียกเก็บสำหรับ task นี้ หลังหักเงินคืนใดๆ แล้ว คำขอที่ส่งคืนข้อผิดพลาดจะไม่ถูกเรียกเก็บเครดิต task ที่ล้มเหลวจะมีค่าเป็น 0 เนื่องจาก Meshy จะคืนเครดิตให้ การยกเลิกจะคืนเครดิตให้กับ task ก็ต่อเมื่อยังอยู่ในสถานะ PENDING เท่านั้น หาก Meshy ไม่สามารถอ่านค่าที่เรียกเก็บได้ การตอบกลับแบบ get หรือ stream จะไม่มีฟิลด์นี้อยู่ และคำขอแบบ list จะส่งคืน 500 ในกรณีนี้ ให้ลองส่งคำขออีกครั้ง

  • Name
    model_urls
    Type
    object
    Description

    URL สำหรับดาวน์โหลดผลลัพธ์ แบ่งตามรูปแบบไฟล์ ออบเจ็กต์นี้มีหนึ่งรายการ สำหรับ output.format ที่คุณส่งมา และจะว่างเปล่าจนกว่า task จะสำเร็จ

    URL เหล่านี้มีการลงนามไว้แล้ว ดังนั้นให้เรียกใช้โดยไม่ต้องใส่ header Authorization URL เหล่านี้จะใช้งานได้จนถึง expires_at การดึงข้อมูล task อีกครั้งก่อนเวลานั้นจะส่งคืน URL ชุดเดิม ไม่ใช่ URL ที่ลงนามใหม่ URL ที่หมดอายุแล้วไม่สามารถรีเฟรชได้ ดังนั้นควรดาวน์โหลดและจัดเก็บไฟล์ไว้ก่อนที่จะหมดอายุ

    • Name
      3mf
      Type
      string
      Description

      URL สำหรับดาวน์โหลดไฟล์ 3MF หลายสี แต่ละชิ้นส่วนจะมีตัวเป็นสีเทาและด้านบนเป็นสีของพิกเซลนั้นๆ จะปรากฏเมื่อ output.format เป็น 3mf ซึ่งเป็นค่าเริ่มต้น

End-to-end example

สคริปต์ cURL และ Python ต่อไปนี้รันขั้นตอนทั้งหมด แต่ละสคริปต์จะสร้างงาน prototype จากรูปภาพแล้วรอให้สำเร็จ จากนั้นจะสร้างงาน build รอให้งานนั้นเสร็จ แล้วดาวน์โหลดไฟล์ 3MF จาก model_urls.3mf

สคริปต์ cURL ต้องใช้ curl และ jq ส่วนสคริปต์ Python ต้องใช้แพ็กเกจ requests หากต้องการรันสคริปต์ ให้ทำตามขั้นตอนต่อไปนี้:

  1. ตั้งค่า MESHY_API_KEY เป็น API คีย์ของคุณ
  2. ตั้งค่า IMAGE_PATH เป็นพาธของรูปภาพในเครื่อง หรือตั้งค่า IMAGE_URL เป็น URL รูปภาพสาธารณะ
  3. ไม่บังคับ: หากต้องการแปลงเป็นพิกเซลสำหรับวัตถุอื่นที่ไม่ใช่คน ให้ตั้งค่า PIXEL_TYPE เป็น other
  4. รันสคริปต์

งาน prototype มักจะเสร็จภายในไม่กี่นาที งาน build มักจะเสร็จภายในเวลาไม่ถึงหนึ่งนาที

ในแอปของคุณ ให้แสดงรูปภาพจาก image_urls ให้ผู้ใช้เห็นก่อนที่คุณจะสร้างงาน build หากพวกเขาไม่ชอบรูปภาพนั้น ให้สร้างงาน prototype ใหม่แทน วิธีนี้จะทำให้คุณใช้เครดิตในการ build เฉพาะกับรูปภาพที่พวกเขายอมรับเท่านั้น

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"