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 endpoint ต้องการแผนการสมัครสมาชิกที่ชำระเงิน คำขอจากบัญชีแผนฟรีจะถูกปฏิเสธด้วย 402 Payment Required.

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

สร้างงานต้นแบบ Keycap

สร้างภาพเรนเดอร์การออกแบบ keycap ที่เสร็จสมบูรณ์จากภาพต้นฉบับ ผลลัพธ์ของงานนี้จะมีอาร์เรย์ image_urls (ภาพเรนเดอร์ของ keycap ที่เสร็จสมบูรณ์) และอาร์เรย์ candidate_ids ที่คู่ขนานกัน; ทั้งสองมีเพียงรายการเดียว เรียกใช้ endpoint นี้อีกครั้งเพื่อสร้างภาพเรนเดอร์ใหม่หากผลลัพธ์ไม่เป็นที่พอใจ — การเรียกใช้แต่ละครั้งจะถูกคิดค่าบริการแยกต่างหาก ส่ง candidate_id พร้อมกับ ID งานต้นแบบไปยัง เอนด์พอยต์การสร้าง ดูที่ วัตถุงานต้นแบบ Keycap สำหรับรูปแบบการตอบกลับ

พารามิเตอร์

Name
image_url
Type
string
จำเป็น
Description
ภาพต้นฉบับสำหรับ Meshy เพื่อเปลี่ยนเป็นภาพการออกแบบ keycap เรารองรับรูปแบบ .jpg, .jpeg, .png, และ .webp
รูปแบบจะถูกตรวจจับโดยการถอดรหัสข้อมูลภาพ, ไม่ใช่ จากนามสกุลไฟล์ของ URL — URL ที่ไม่มีนามสกุลหรือที่เปลี่ยนเส้นทางจะทำงานได้ตราบใดที่ไบต์สามารถถอดรหัสเป็นรูปแบบที่รองรับได้ การเปลี่ยนเส้นทาง HTTP จะถูกติดตาม การจัดแนว EXIF จะถูกปรับให้เป็นปกติ ดังนั้นภาพถ่ายจากโทรศัพท์ที่หมุนจะถูกใช้ตามที่เห็น
ข้อจำกัด: อย่างน้อย 32 พิกเซลในแต่ละด้าน, สูงสุด 178,956,970 พิกเซลทั้งหมด, และสูงสุด 20,000,000 ไบต์เมื่อดาวน์โหลด สำหรับ Data URI ข้อจำกัดจะใช้กับไบต์ที่ถอดรหัสแล้ว ดังนั้นไฟล์ต้นฉบับอาจมีขนาดถึงขีดจำกัดนั้น — เป็นข้อความ base64 ที่ใหญ่กว่าประมาณหนึ่งในสาม ซึ่งสำคัญสำหรับเนื้อหาคำขอของคุณ ไม่ใช่สำหรับข้อจำกัดนี้ Data URI ต้องประกาศประเภทเนื้อหา image/* และ ;base64
มีสองวิธีในการให้ภาพ:
- URL ที่เข้าถึงได้สาธารณะ: URL ที่สามารถเข้าถึงได้จากอินเทอร์เน็ตสาธารณะ
- Data URI: Data URI ที่เข้ารหัส base64 ของภาพ ตัวอย่างของ Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Name
name
Type
string
Description
ชื่องานที่ไม่บังคับเพื่อวัตถุประสงค์ในการแสดงผล สูงสุด 100 ตัวอักษร
Name
remove_background
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อกำหนดเป็น true, ภาพเรนเดอร์ที่แสดงใน image_urls จะเป็น PNG แบบโปร่งใส RGBA ที่มีพื้นหลังถูกลบออก ดังนั้นคุณสามารถนำไปวางบนพื้นหลังใดก็ได้
สิ่งนี้ใช้กับภาพเรนเดอร์ที่แสดงเท่านั้น ผู้สมัครที่เอนด์พอยต์การสร้างใช้จะไม่ได้รับผลกระทบ ดังนั้นผลลัพธ์ 3D จะเหมือนกันไม่ว่าจะอย่างไรก็ตาม

การคืนค่า

คุณสมบัติ result ของการตอบกลับประกอบด้วย id ของงานต้นแบบ keycap ที่สร้างขึ้นใหม่ ตรวจสอบ รับงาน endpoint หรือสมัครรับ สตรีม จนกว่างานจะถึง SUCCEEDED, จากนั้นนำรายการจาก candidate_ids และส่งไปพร้อมกับ ID งานไปยัง เอนด์พอยต์การสร้าง

โหมดความล้มเหลว

Name
400 - Bad Request
Description
คำขอไม่เป็นที่ยอมรับ สาเหตุทั่วไป:
- พารามิเตอร์ที่ขาดหายไป: image_url เป็นสิ่งจำเป็น
- รูปแบบภาพไม่ถูกต้อง: image_url ที่ให้มาไม่ใช่รูปแบบที่รองรับ (.jpg, .jpeg, .png, .webp)
- ขนาดภาพเกินขอบเขต: ภาพเล็กเกินไป, เกินขนาดไฟล์สูงสุด, หรือเกินจำนวนพิกเซลสูงสุด
- URL ที่ไม่สามารถเข้าถึงได้: ไม่สามารถดาวน์โหลด image_url ได้ (404 หรือ timeout)
- Data URI ไม่ถูกต้อง: สตริง base64 ไม่ถูกต้อง
- เนื้อหาถูกตั้งค่าสถานะ: ภาพต้นฉบับถูกตั้งค่าสถานะโดย moderation NSFW
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว กรุณาตรวจสอบ API key ของคุณ
Name
402 - Payment Required
Description
บัญชีอยู่ในแผนฟรี (จำเป็นต้องมีแผนชำระเงินเพื่อสร้างงาน) หรือมีเครดิตไม่เพียงพอ
Name
403 - Forbidden
Description
ภาพต้นฉบับถูกตั้งค่าสถานะโดย moderation ทรัพย์สินทางปัญญา
Name
429 - Too Many Requests
Description
คุณได้เกินการจำกัดอัตราของคุณ
Name
500 - Internal Server Error
Description
เกิดข้อผิดพลาดที่ไม่คาดคิดในฝั่งเซิร์ฟเวอร์ — ตัวอย่างเช่น บริการ moderation เนื้อหาไม่พร้อมใช้งาน, การจัดเตรียมภาพต้นฉบับล้มเหลว, หรือไม่สามารถสร้างงานได้ ไม่มีการสร้างงานในกรณีนี้ ดังนั้นการลองใหม่จึงปลอดภัย

Request

POST

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

# Stage 1: generate a finished-keycap design render
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

Response

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

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

สร้างงานสร้าง Keycap

สร้างโมเดล 3D keycap ที่มีพื้นผิวสุดท้ายจากงานต้นแบบที่สำเร็จและหนึ่งในผู้สมัครของมัน งานสร้างเดียวจะดำเนินการทั้งกระบวนการตั้งแต่ต้นจนจบ — การสร้างโมเดลสีขาวจากการออกแบบที่เลือก, การวางและตัดอัตโนมัติบนฐาน keycap โดยใช้ท่าทางเริ่มต้นที่ปรับเทียบแล้ว (ไม่ต้องปรับแต่งแบบโต้ตอบ), การลงสีโมเดลเต็มรูปแบบ, และการประกอบและส่งออกสุดท้าย การสร้างมักใช้เวลา 3–7 นาที โดยใช้เวลานานขึ้นเมื่อมีการสร้างหลายงานพร้อมกัน ดูที่ The Keycap Build Task Object สำหรับรูปแบบการตอบกลับ

พารามิเตอร์

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
ฐาน keycap ที่จะสร้าง ปัจจุบันมีค่าเดียวที่ใช้ได้คือ cherry-mx-1x1-r1 — โปรไฟล์ Cherry MX มาตรฐาน 1u keycap ขนาดมาตรฐานหลัก 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 ของงานสร้าง keycap ที่สร้างใหม่ ตรวจสอบเอนด์พอยต์ Get a Task หรือสมัครสมาชิก stream จนกว่างานจะถึง SUCCEEDED, จากนั้นดาวน์โหลดสิ่งประดิษฐ์จาก model_urls.glb และ model_urls.obj_zip

ทั้ง GLB และ OBJ bundle ถูกส่งออกใน มาตราส่วนมิลลิเมตรในโลกจริง, ด้วยระบบพิกัด Y-up และด้านหน้าของ keycap หันหน้าไปทาง +Z

โหมดความล้มเหลว

Name
400 - Bad Request
Description
คำขอไม่สามารถยอมรับได้ สาเหตุทั่วไป:
- พารามิเตอร์ที่ขาดหายไป: input_task_id และ candidate_id เป็นสิ่งจำเป็น
- UUID ไม่ถูกต้อง: input_task_id ไม่ใช่ UUID ที่ถูกต้อง
- ต้นแบบไม่สำเร็จ: งานต้นแบบที่อ้างอิงยังไม่ถึง SUCCEEDED
- ไม่มีผู้สมัคร: งานต้นแบบสำเร็จแต่ไม่ได้สร้างผู้สมัคร
- ผู้สมัครที่ไม่รู้จัก: candidate_id ไม่ใช่หนึ่งในผู้สมัครของงานต้นแบบ
- ตัวเลือกนอกช่วง: หนึ่งในฟิลด์ options ตกอยู่นอกช่วงที่อนุญาตหรือชุด enum
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
เกิดข้อผิดพลาดที่ไม่คาดคิดในฝั่งเซิร์ฟเวอร์ — ตัวอย่างเช่นบริการ moderation เนื้อหาไม่พร้อมใช้งาน, การจัดเตรียมภาพอินพุตล้มเหลว, หรือไม่สามารถสร้างงานได้ ไม่มีการสร้างงานในกรณีนี้, ดังนั้นการลองใหม่จึงปลอดภัย

Request

POST

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

# Stage 2: build the chosen candidate into a 3D keycap
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "candidate_id": "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b",
    "options": {
      "base_model": "cherry-mx-1x1-r1",
      "head_size_mm": 23,
      "vertical_offset_mm": 0
    }
  }'

Response

{
  "result": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af"
}

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

ดึงข้อมูลงาน Keycap

ดึงข้อมูลงานต้นแบบหรือการสร้างที่กำหนดโดย id ของงานที่ถูกต้อง เส้นทาง URL ต้องตรงกับขั้นตอนของงาน — การดึงงานสร้างผ่าน /prototype/:id จะคืนค่า 404 และในทางกลับกัน

ดูเพิ่มเติมที่ The Keycap Prototype Task Object และ The Keycap Build Task Object สำหรับ รูปแบบการตอบกลับ

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน keycap ที่จะดึงข้อมูล

การคืนค่า

การตอบกลับจะประกอบด้วยวัตถุงาน keycap รูปแบบขึ้นอยู่กับขั้นตอนที่ร้องขอ

Request

GET

/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keycap/v1/build/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
  "type": "creative-lab-keycap-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142456000,
  "started_at": 1753142460000,
  "finished_at": 1753142516000,
  "expires_at": 1753401716000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 12,
  "image_urls": [
    "https://assets.meshy.ai/***/design-1.png?Expires=***"
  ],
  "candidate_ids": [
    "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
  ]
}

Build Response

{
  "id": "019c9a52-7d18-7e2b-9f01-6e3b98c4d2af",
  "type": "creative-lab-keycap-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1753142600000,
  "started_at": 1753142610000,
  "finished_at": 1753143050000,
  "expires_at": 1753402250000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 50,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model.glb?Expires=***",
    "obj_zip": "https://assets.meshy.ai/***/tasks/019c9a52-7d18-7e2b-9f01-6e3b98c4d2af/output/model-obj.zip?Expires=***"
  },
  "process_image_urls": {
    "head_design": "https://assets.meshy.ai/***/head-design.png?Expires=***",
    "composite": "https://assets.meshy.ai/***/composite.png?Expires=***",
    "base_canvas": "https://assets.meshy.ai/***/base-canvas.png?Expires=***"
  }
}

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

ลบงาน Keycap

ยกเลิกงาน keycap หากงานยังคงอยู่ในสถานะ PENDING เครดิตที่ใช้ไปในขณะสร้างจะถูกคืน งานที่อยู่ในสถานะ IN_PROGRESS จะถูกยกเลิกโดยไม่มีการคืนเงิน (เนื่องจากผู้ปฏิบัติงานอาจกำลังใช้แหล่งข้อมูลอยู่) งานที่ได้เข้าสู่สถานะสุดท้ายแล้ว (SUCCEEDED, FAILED, CANCELED) ไม่สามารถยกเลิกได้

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

พารามิเตอร์เส้นทาง

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน keycap ที่จะยกเลิก

การคืนค่า

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

โหมดความล้มเหลว

Name
400 - Bad Request
Description
งานอยู่ในสถานะสุดท้ายแล้วและไม่สามารถยกเลิกได้
Name
404 - Not Found
Description
งานไม่อยู่, เป็นของผู้ใช้คนอื่น, หรือขั้นตอนไม่ตรงกับเส้นทาง URL
Name
500 - Internal Server Error
Description
เกิดข้อผิดพลาดที่ไม่คาดคิดจากฝั่งเซิร์ฟเวอร์ขณะยกเลิก งานอาจจะถูกยกเลิกหรือไม่ก็ได้ — อ่านใหม่เพื่อยืนยันก่อนลองอีกครั้ง

Request

DELETE

/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keycap/v1/prototype/019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

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

สตรีมงาน Keycap

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

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน keycap ที่จะสตรีม

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

ส่งคืนสตรีมของวัตถุงาน Keycap Prototype หรือ Keycap Build เป็น Server-Sent Events สำหรับงานที่มีสถานะ 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)

รายการงาน Keycap

ดึงรายการงาน keycap ที่มีการแบ่งหน้าสำหรับขั้นตอนเดียว 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: จัดเรียงตามเวลาสร้างในลำดับลดลง

การคืนค่า

คืนค่ารายการงานตามขั้นตอนที่มีการแบ่งหน้า — ไม่ว่าจะเป็น วัตถุงานต้นแบบ keycap เมื่อทำรายการ /prototype หรือ วัตถุงานสร้าง keycap เมื่อ ทำรายการ /build

Request

GET

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

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

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

Response (List Prototype Tasks)

[
  {
    "id": "019c9a4e-2b31-7f6a-8c44-5d2a87b3c1ef",
    "type": "creative-lab-keycap-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1753142456000,
    "started_at": 1753142460000,
    "finished_at": 1753142516000,
    "expires_at": 1753401716000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 12,
    "image_urls": [
      "https://assets.meshy.ai/***/design-1.png?Expires=***"
    ],
    "candidate_ids": [
      "0198c1b2-33f5-7d21-a4b7-8e9d0c1f2a3b"
    ]
  }
]

วัตถุงานต้นแบบ Keycap

วัตถุงานต้นแบบ Keycap เป็นหน่วยงานที่ Meshy ใช้ติดตามเพื่อสร้างภาพการออกแบบคีย์แคปที่เสร็จสมบูรณ์จากภาพต้นฉบับ ผลลัพธ์ของขั้นตอนนี้จะถูกเชื่อมโยงไปยัง ขั้นตอนการสร้าง ผ่าน input_task_id และ candidate_id

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุเฉพาะสำหรับงานนี้ แม้ว่าเราจะใช้ UUID ที่สามารถเรียงลำดับได้สำหรับ id ของงานเป็นรายละเอียดการใช้งาน แต่คุณไม่ควรทำการคาดเดาใด ๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของงาน ค่านี้คือ creative-lab-keycap-prototype
Name
name
Type
string
Description
ชื่องานที่ให้เมื่อสร้างงาน ถ้าไม่มีการให้ชื่อจะเป็นสตริงว่าง
Name
status
Type
string
Description
สถานะของงาน ค่าที่เป็นไปได้คือหนึ่งใน PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
progress
Type
integer
Description
ความคืบหน้าของงาน ถ้างานยังไม่เริ่ม คุณสมบัตินี้จะเป็น 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 ในเวลาขอ รวมถึงการปฏิเสธการตรวจสอบ) จะไม่ถูกเรียกเก็บเงินเลย งานที่ถึง FAILED จะคืนค่า 0 — การเรียกเก็บเงินจะถูกคืนเงิน รวมถึงการบล็อกการตรวจสอบแบบอะซิงโครนัส การยกเลิกผ่าน DELETE จะคืนเงินเฉพาะในขณะที่งานยังอยู่ในสถานะ PENDING; งานที่อยู่ในสถานะ IN_PROGRESS แล้วจะยังคงถูกเรียกเก็บเงินเพราะงานได้ถูกใช้ไปแล้ว
Name
image_urls
Type
array of strings
Description
URL ที่สามารถดาวน์โหลดได้ของการเรนเดอร์การออกแบบคีย์แคปที่เสร็จสมบูรณ์ — สิ่งที่ผู้สมัครดูเหมือนเป็นคีย์แคปที่เสร็จสมบูรณ์ มีเพียงรายการเดียว; image_urls[i] สอดคล้องกับ candidate_ids[i] ว่างเปล่าจนกว่างานจะถึง SUCCEEDED URL นี้ใช้สำหรับการแสดงผลเท่านั้น; เอนด์พอยต์การสร้างใช้ candidate_ids ไม่ใช่ URL เหล่านี้ วงจรชีวิตของ URL เดียวกันกับ model_urls: ลงนาม, ไม่มีหัวข้อ Authorization, ใช้ได้จนถึง expires_at, และเสถียรเมื่ออ่านงานใหม่
Name
candidate_ids
Type
array of strings
Description
ตัวระบุผู้สมัครที่ไม่โปร่งใส ขนานกับ image_urls ส่งรายการที่ตรงกับการออกแบบที่คุณเลือกเป็น candidate_id ของคำขอสร้าง อย่าทำการคาดเดาใด ๆ เกี่ยวกับรูปแบบของ 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 ทั้งหมด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ใช้ไปกับงานนี้ งานที่ถึง SUCCEEDED จะถูกคิดค่าใช้จ่ายเต็มจำนวนสำหรับขั้นตอนของมัน งานที่ไม่เคยถูกสร้าง (เช่น 4xx ในเวลาที่ร้องขอ รวมถึงการปฏิเสธการตรวจสอบ) จะไม่ถูกคิดค่าใช้จ่ายเลย งานที่ถึง FAILED จะคืนค่า 0 — การคิดค่าใช้จ่ายจะถูกคืนเงิน รวมถึงการบล็อกการตรวจสอบแบบอะซิงโครนัส การยกเลิกผ่าน DELETE จะคืนเงินเฉพาะเมื่อยังอยู่ในสถานะ PENDING; งานที่อยู่ในสถานะ IN_PROGRESS แล้วจะยังคงถูกคิดค่าใช้จ่าย เพราะงานได้ถูกใช้ไปแล้ว
Name
model_urls
Type
object
Description
URL ที่สามารถดาวน์โหลดได้สำหรับโมเดลที่สร้างขึ้น ทั้ง GLB และชุด OBJ จะถูกส่งออกใน มาตราส่วนมิลลิเมตรในโลกจริง, Y-up, โดยด้านหน้าของคีย์แคปหันไปทาง +Z เมชถูกตั้งชื่อว่า keycap-head และ keycap-base; เมื่อฐานกลับไปใช้การเติมลวดลาย เมชที่สาม keycap-base-interior จะมีอยู่ด้วยสำหรับช่องแกน อย่าคาดหวังว่าจะมีเพียงสองเมช
เหล่านี้เป็น URL ที่ลงนาม: ดึงข้อมูล โดยไม่ต้อง มี Authorization header พวกมันจะยังคงใช้ได้จนถึง expires_at ซึ่งคือ 3 วันหลังจาก finished_at และการอ่านงานอีกครั้งในช่วงเวลานั้นจะคืน URL เดิมแทนที่จะเป็น URL ที่ลงนามใหม่ ดาวน์โหลดและจัดเก็บไฟล์ด้วยตัวคุณเองก่อนหน้านั้น — ไม่มีวิธีการรีเฟรชลิงก์ที่หมดอายุ
- Name
  glb
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับ model.glb ที่มีเท็กซ์เจอร์สุดท้าย
- Name
  obj_zip
  Type
  string
  Description
  URL ที่สามารถดาวน์โหลดได้สำหรับชุดซิปที่มี model.obj, model.mtl, และไฟล์ PNG ของเท็กซ์เจอร์ที่ MTL อ้างอิงจริง ฐานสีทึบจะส่งเฉพาะ keycap-head.png; ฐานที่มีลวดลายจะส่ง keycap-base.png ด้วย
Name
process_image_urls
Type
object
Description
URL ที่สามารถดาวน์โหลดได้สำหรับภาพกระบวนการกลางๆ ที่มีคีย์ตามชนิด วงจรชีวิต URL เดียวกันกับ model_urls: ลงนาม, ไม่มี Authorization header, ใช้ได้จนถึง 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, จากนั้นดาวน์โหลด GLB และชุด OBJ จาก model_urls

ตัวอย่างนี้เลือกผู้สมัคร คนแรก โดยอัตโนมัติ ในการผสานรวมจริง คุณจะแสดงรายการ image_urls ให้ผู้ใช้ปลายทางและให้พวกเขาเลือก; ดัชนีที่เลือกจะจับคู่ 1:1 กับ candidate_ids

กระบวนการครบวงจร

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"