Creative Lab Keychain API

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

POST /openapi/creative-lab/keychain/v1/prototype
POST /openapi/creative-lab/keychain/v1/build

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

สร้างงาน Keychain prototype

สร้างภาพคอนเซปต์ที่มีสีสันหนึ่งภาพจากรูปถ่าย เพื่อสร้างโมเดล 3D ให้ส่ง ID ของงานนี้ไปยัง build endpoint เป็น input_task_id สำหรับฟิลด์ต่างๆ ของงาน ดูที่ The Keychain prototype task object

Request

POST

/openapi/creative-lab/keychain/v1/prototype

# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "name_text": "Luna"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Prototype example

Start with a source photo, then generate the prototype image used by the keychain build stage.

Source photo used as the Creative Lab Keychain input — Prototype input

Creative Lab Keychain prototype output generated from the source photo — Prototype output

พารามิเตอร์

Name
image_url
Type
string
จำเป็น
Description
รูปถ่ายที่จะแปลงเป็นภาพคอนเซปต์พวงกุญแจ โดยเป็น URL สาธารณะหรือ data URI (data:image/jpeg;base64,<your base64-encoded image data>)
รูปภาพต้องเป็นไฟล์ JPG, JPEG, PNG หรือ WebP ขนาดไม่เกิน 20 MB
Name
name
Type
string
Description
ชื่อสำหรับงานนี้ ยาวได้สูงสุด 100 ตัวอักษร ชื่อนี้จะถูกส่งกลับมาในฟิลด์ name ของงาน หากชื่อยาวเกินไปจะได้รับ 400
ใช้สำหรับติดป้ายงานในแดชบอร์ดและรายการงานของคุณ และจะไม่ปรากฏบนพวงกุญแจ หากต้องการใส่ชื่อบนพวงกุญแจ ให้ใช้ name_text
Name
name_text
Type
string
Description
ชื่อที่จะเพิ่มลงบนพวงกุญแจ เช่น ชื่อสัตว์เลี้ยงหรือชื่อบุคคล ยาวได้สูงสุด 10 ตัวอักษร Meshy นับจำนวนตัวอักษร ไม่ใช่ไบต์ ดังนั้นชื่อภาษาจีน ญี่ปุ่น หรือเกาหลีที่มี 10 ตัวอักษรจึงใส่ได้พอดี หากชื่อยาวเกินไปจะได้รับ 400 ละเว้นค่านี้ไว้หากต้องการพวงกุญแจที่ไม่มีชื่อ
ชื่อจะปรากฏบนหน้าพวงกุญแจเป็นรายละเอียดสีแบบแบน ไม่ใช่ตัวอักษรนูนหรือตัวอักษรตัด
Meshy จะตัดช่องว่างรอบข้อความออกและลบอักขระจัดรูปแบบที่มองไม่เห็น prototype task object จะส่งผลลัพธ์กลับมาเป็น name_text ดังนั้นคุณจึงสามารถตรวจสอบข้อความก่อนที่จะจ่ายเงินสำหรับการ build ได้
Meshy จะเพิ่มชื่อในขั้นตอน prototype การ build จะคงชื่อนี้ไว้ และจะไม่สนใจ name_text ที่ส่งไปยัง build endpoint
เมื่อข้อความไม่ใช่ ASCII ธรรมดา ให้ส่งเนื้อหาคำขอเป็น UTF-8 โดยใช้ Content-Type: application/json; charset=utf-8 ไคลเอนต์ HTTP บางตัว เช่น Invoke-RestMethod ของ Windows PowerShell จะเข้ารหัสเนื้อหาเป็น ISO-8859-1 โดยค่าเริ่มต้น ซึ่งจะเปลี่ยนอักขระที่ไม่ใช่ภาษาละตินทุกตัวให้เป็น ? ก่อนที่คำขอจะไปถึง Meshy และ Meshy ไม่สามารถแยกแยะได้ว่าแตกต่างจากชื่อที่คุณตั้งใจจะส่ง
Name
remove_background
Type
boolean
ค่าเริ่มต้น false
Description
กำหนดว่าจะลบพื้นหลังออกจากภาพ prototype หรือไม่ true จะส่งกลับไฟล์ PNG แบบ RGBA โปร่งใสที่คงเหรียญรูปวงรีทั้งหมดไว้ ทำให้คุณสามารถวางลงบนพื้นหลังใดก็ได้ การ build ก็จะเริ่มต้นจากภาพที่ไม่มีพื้นหลังเช่นกัน หาก Meshy ไม่สามารถลบพื้นหลังได้ จะส่งกลับภาพที่มีพื้นหลังอยู่ และงานยังคงสำเร็จ
ตัวเลือก remove_background ของการ build นั้นแยกต่างหาก

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

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

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

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถทำงานได้ ตัวอย่างเช่น:
- ไม่มี image_url
- รูปภาพไม่ใช่ไฟล์ JPG, JPEG, PNG หรือ WebP
- รูปภาพเล็กเกินไป ใหญ่กว่า 20 MB หรือเกินจำนวนพิกเซลสูงสุด
- Meshy ไม่สามารถดาวน์โหลดรูปภาพได้ เช่น เพราะ URL ส่งกลับ 404 หรือหมดเวลา
- data URI ไม่ใช่ base64 ที่ถูกต้อง
- name_text ยาวเกิน 10 ตัวอักษร Meshy จะปฏิเสธคำขอแทนที่จะตัดให้สั้นลง และไม่คิดเครดิตสำหรับคำขอนี้
- รูปภาพหรือ name_text ถูกตั้งค่าสถานะว่าเป็น NSFW
ข้อความแสดงข้อผิดพลาดจะระบุปัญหาที่พบ แก้ไขคำขอแล้วส่งอีกครั้ง
Name
401 - Unauthorized
Description
API คีย์หายไปหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
หนึ่งในกรณีต่อไปนี้เกิดขึ้น:
- บัญชีมีเครดิตไม่เพียงพอ
- API คีย์ พื้นที่ทำงาน หรือสมาชิกถึงขีดจำกัดเครดิตแล้ว
- บัญชีอยู่ในแผนฟรี
ตรวจสอบเครดิตและแผนของคุณ แล้วลองใหม่
Name
403 - Forbidden
Description
ทีมของคุณเปิดใช้งาน IP Filtering และ Meshy ตั้งค่าสถานะรูปภาพนี้ว่าเกี่ยวข้องกับทรัพย์สินทางปัญญาของบุคคลที่สาม ส่งรูปภาพที่คุณมีสิทธิ์ใช้งาน Meshy ตรวจสอบเฉพาะรูปภาพสำหรับทรัพย์สินทางปัญญาเท่านั้น ไม่ตรวจสอบ name_text
Name
429 - Too Many Requests
Description
หนึ่งในขีดจำกัดต่อไปนี้ถูกถึง:
- คุณส่งคำขอมากกว่าที่การจำกัดอัตราของคุณอนุญาต รอสักสองสามวินาทีแล้วลองใหม่ ดู Rate limits
- มีงานของคุณอยู่ในคิวหรือกำลังทำงานมากเกินไป รอให้บางงานเสร็จสิ้นแล้วลองใหม่
- หากอยู่ในแผนไม่จำกัดและไม่มีเครดิตเหลือ คุณถึงจำนวนงานสูงสุดที่สามารถทำงานได้โดยไม่ใช้เครดิตแล้ว รอให้งานหนึ่งเสร็จสิ้น หรือเพิ่มเครดิต
Name
500 - Internal Server Error
Description
Meshy พบข้อผิดพลาดของเซิร์ฟเวอร์ เช่น เพราะไม่สามารถรันการตรวจสอบทรัพย์สินทางปัญญาบนรูปภาพได้ Meshy จะไม่สร้างงาน และคืนเครดิตใดๆ ที่เรียกเก็บไปแล้ว ลองส่งคำขออีกครั้ง

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

สร้างงานสร้างพวงกุญแจ (Keychain build task)

สร้างพวงกุญแจที่พิมพ์แบบ 3 มิติได้จากงานต้นแบบ (prototype) ที่สำเร็จแล้ว Meshy จะแปลงภาพแนวคิดของต้นแบบให้เป็นภาพนูนแบบ depth-map relief และส่งคืนไฟล์โมเดลหนึ่งไฟล์ในรูปแบบที่คุณเลือก สำหรับฟิลด์ของงานนี้ ดูที่ The Keychain build task object

Request

POST

/openapi/creative-lab/keychain/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

The build task converts the selected prototype image into a 3D-printable keychain model.

Creative Lab Keychain build model preview — Build model preview

พารามิเตอร์

Name
input_task_id
Type
string
จำเป็น
Description
ID ของงานต้นแบบที่จะใช้สร้าง ต้องเป็นงานที่บัญชีของคุณสร้างด้วย POST /openapi/creative-lab/keychain/v1/prototype และมีสถานะเป็น SUCCEEDED
ID ที่ไม่ใช่งานต้นแบบ Keychain ของคุณจาก API จะส่งคืน 404 รวมถึงต้นแบบที่สร้างในเว็บแอปด้วย
Name
name
Type
string
Description
ชื่อสำหรับงานนี้ ความยาวไม่เกิน 100 ตัวอักษร ชื่อนี้จะถูกส่งกลับมาในฟิลด์ name ของงาน หากชื่อยาวเกินไปจะส่งคืน 400

`options`

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

Name
badge_shape
Type
string
ค่าเริ่มต้น circle
Description
เส้นขอบของพวงกุญแจเมื่อ Meshy ไม่ได้ลากเส้นจากตัวแบบ Meshy ใช้ค่านี้เมื่อ remove_background เป็น false หรือเมื่อไม่สามารถหาขอบของตัวแบบได้
ค่าที่ใช้ได้:
- circle
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
ค่าเริ่มต้น 40
Description
ความยาวขอบของกรอบสี่เหลี่ยมจัตุรัสที่ล้อมรอบพวงกุญแจ หน่วยเป็นมิลลิเมตร สูงสุด 400 ค่า 0 ใช้ค่าเริ่มต้น
Name
relief_height_mm
Type
number
ค่าเริ่มต้น 2.2
Description
ความสูงสูงสุดของภาพนูนเหนือฐาน หน่วยเป็นมิลลิเมตร ตั้งแต่ 0 ถึง 20
Name
relief_offset_mm
Type
number
ค่าเริ่มต้น 0
Description
ระยะที่จะลดภาพนูนลง หน่วยเป็นมิลลิเมตร ตั้งแต่ 0 ถึง 20 Meshy จะลบค่านี้ออกจากความสูงของภาพนูนทุกจุดจนถึงฐาน
Name
base_thickness_mm
Type
number
ค่าเริ่มต้น 0.1
Description
ความหนาของแผ่นฐานเรียบด้านหลังภาพนูน หน่วยเป็นมิลลิเมตร ตั้งแต่ 0 ถึง 20
Name
has_closed_back
Type
boolean
ค่าเริ่มต้น true
Description
กำหนดว่าจะปิดด้านหลังของพวงกุญแจหรือไม่ false จะปล่อยด้านหลังเปิดไว้ เป็นลักษณะเปลือกกลวง
Name
relief_curve
Type
string
ค่าเริ่มต้น linear
Description
เส้นโค้งที่ใช้แปลงค่าของ depth map เป็นความสูงของภาพนูน
ค่าที่ใช้ได้:
- linear
- gamma
- s-curve
Name
curve_param
Type
number
ค่าเริ่มต้น 1.0
Description
ความเข้มของเส้นโค้ง สูงสุด 10 ใช้กับเส้นโค้ง gamma และ s-curve เท่านั้น ส่วน linear จะไม่สนใจค่านี้ ค่า 0 ใช้ค่าเริ่มต้น
Name
invert_depth
Type
boolean
ค่าเริ่มต้น false
Description
กำหนดว่าจะกลับค่าของ depth map หรือไม่ เพื่อให้บริเวณที่มืดกว่ากลายเป็นภาพนูนที่สูงขึ้น
Name
smoothing
Type
number
ค่าเริ่มต้น 0.24
Description
ระดับการทำให้ depth map เรียบขึ้นก่อนที่ Meshy จะสร้างภาพนูน ตั้งแต่ 0 ถึง 10
Name
relief_scale
Type
number
ค่าเริ่มต้น 1.0
Description
ระดับการซูมภาพนูนและเท็กซ์เจอร์ของมันภายในเส้นขอบ โดยอ้างอิงจากจุดศูนย์กลาง สูงสุด 10 ค่าที่มากกว่า 1 จะขยายตัวแบบให้ใหญ่ขึ้น และค่าที่น้อยกว่า 1 จะทำให้เล็กลง ค่านี้ไม่เปลี่ยนความสูงของภาพนูน ค่า 0 ใช้ค่าเริ่มต้น
Name
depth_threshold
Type
number
ค่าเริ่มต้น 0.1
Description
ค่าของ depth map ที่ต่ำกว่านี้ Meshy จะกำหนดความลึกเป็นศูนย์ ตั้งแต่ 0 ถึง 1
Name
remove_background
Type
boolean
ค่าเริ่มต้น true
Description
กำหนดว่าจะลากเส้นขอบของพวงกุญแจจากตัวแบบหรือไม่ เพื่อให้พวงกุญแจมีรูปทรงตามตัวแบบ false จะใช้เส้นขอบจาก badge_shape แทน Meshy จะใช้ badge_shape เช่นกันเมื่อไม่สามารถหาขอบของตัวแบบได้
ค่านี้แยกจากพารามิเตอร์ remove_background ของต้นแบบ ซึ่งกำหนดว่าภาพต้นแบบมีพื้นหลังโปร่งใสหรือไม่
Name
export_resolution
Type
integer
ค่าเริ่มต้น 512
Description
ความละเอียดของเมชของโมเดลที่ส่งออก ตั้งแต่ 64 ถึง 512 Meshy สร้างจีออเมทรีจาก depth map ขนาด 512 พิกเซล ดังนั้นเมชที่ละเอียดกว่านี้จะเพิ่มจำนวนเหลี่ยมโดยไม่เพิ่มรายละเอียด ค่า 0 ใช้ค่าเริ่มต้น

`output`

ไม่บังคับ ใช้กำหนดรูปแบบไฟล์ที่งานสร้างจะส่งคืน

Name
format
Type
string
ค่าเริ่มต้น glb
Description
รูปแบบไฟล์ที่งานสร้างจะส่งคืน
ค่าที่ใช้ได้:
- glb: ไฟล์ model.glb หนึ่งไฟล์ อยู่ใน model_urls.glb
- obj: ไฟล์ zip ที่มี model.obj, model.mtl และ texture.png อยู่ใน model_urls.obj
- zip: ไฟล์ zip ที่มีไฟล์ทุกไฟล์ที่ Meshy สร้างขึ้น อยู่ใน model_urls.bundle_zip

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

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

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

Name
400 - Bad Request
Description
คำขอไม่สามารถทำงานได้ ตัวอย่างเช่น:
- input_task_id ขาดหายไปหรือไม่ใช่ ID งานที่ถูกต้อง
- สถานะของงานต้นแบบไม่ใช่ SUCCEEDED หากยังทำงานอยู่ ให้รอแล้วลองใหม่ หากล้มเหลวหรือถูกยกเลิก ให้สร้างงานต้นแบบใหม่
- งานต้นแบบสำเร็จแล้วแต่ไม่มีภาพ ให้สร้างงานต้นแบบใหม่
- ฟิลด์ใน options อยู่นอกช่วงที่กำหนด หรือไม่ใช่ค่าที่ใช้ได้
ข้อความแสดงข้อผิดพลาดจะระบุว่าพบปัญหาใด
Name
401 - Unauthorized
Description
ไม่มี API คีย์หรือ API คีย์ไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
เกิดกรณีใดกรณีหนึ่งต่อไปนี้:
- บัญชีมีเครดิตไม่เพียงพอ
- API คีย์ พื้นที่ทำงาน หรือสมาชิกถึงขีดจำกัดเครดิตแล้ว
- บัญชีอยู่ในแพ็กเกจฟรี
ตรวจสอบเครดิตและแพ็กเกจของคุณ แล้วลองใหม่
Name
404 - Not Found
Description
input_task_id ไม่ตรงกับงานต้นแบบ Keychain ใด ๆ ที่บัญชีของคุณสร้างด้วย API ต้นแบบที่สร้างในเว็บแอปก็จะส่งคืน 404 เช่นกัน ให้ส่ง ID result จากการตอบกลับของการสร้างต้นแบบ
Name
429 - Too Many Requests
Description
ถึงขีดจำกัดอย่างใดอย่างหนึ่งต่อไปนี้:
- คุณส่งคำขอมากกว่าที่การจำกัดอัตราของคุณอนุญาต ให้รอสักครู่แล้วลองใหม่ ดู Rate limits
- มีงานของคุณที่อยู่ในคิวหรือกำลังทำงานมากเกินไป ให้รอจนกว่างานบางส่วนจะเสร็จสิ้น แล้วลองใหม่
- หากอยู่ในแพ็กเกจไม่จำกัดและไม่มีเครดิตเหลือ คุณถึงจำนวนงานสูงสุดที่สามารถทำงานได้โดยไม่ใช้เครดิตแล้ว ให้รอให้งานเสร็จสิ้น หรือเพิ่มเครดิต

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

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

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

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

Request

GET

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?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
ไม่มีงาน Keychain ที่มีรหัสนี้อยู่ในบัญชีของคุณ หรือขั้นตอนของงานไม่ตรงกับพาธ ตรวจสอบรหัส และใช้ /prototype หรือ /build ให้ตรงกับงานนั้น
Name
500 - Internal Server Error
Description
Meshy ไม่สามารถตรวจสอบทรัพย์สินทางปัญญาได้ ลองส่งคำขออีกครั้ง

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

ลบงาน Keychain

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

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

Request

DELETE

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

พารามิเตอร์ของ Path

Name
id
Type
path
Description
ID ของงานที่ต้องการยกเลิก

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

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

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

Name
400 - Bad Request
Description
เป็นไปตามกรณีใดกรณีหนึ่งต่อไปนี้:
- id ไม่ใช่ ID งานที่ถูกต้อง ให้ส่ง ID จาก result ของการตอบกลับตอนสร้างงาน
- งานนั้นมีสถานะสุดท้ายอยู่แล้ว (SUCCEEDED, FAILED หรือ CANCELED) จึงไม่สามารถยกเลิกได้
Name
404 - Not Found
Description
ไม่มีงาน Keychain ที่มี ID นี้อยู่ในบัญชีของคุณ หรือขั้นตอน (stage) ของงานไม่ตรงกับ path ตรวจสอบ ID และใช้ /prototype หรือ /build ให้ตรงกับงานนั้น

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

Stream a Keychain task

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

Request

GET

/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/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; fields not yet populated are null / empty.
// The following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

พารามิเตอร์

Name
id
Type
path
Description
ID ของงานจากการตอบกลับตอนสร้าง

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

สตรีมของอ็อบเจ็กต์งาน prototype หรือ build แต่ละอีเวนต์จะมีอ็อบเจ็กต์งานฉบับเต็ม ตามที่ Get a Keychain task ส่งคืน ในขณะที่งานยังมีสถานะ PENDING หรือ IN_PROGRESS ฟิลด์เอาต์พุตของงานจะยังว่างอยู่ (null, [], หรือ {}) และ finished_at จะเป็น null

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

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

List Keychain tasks

ส่งคืนงาน Keychain ของคุณในขั้นตอนเดียว ครั้งละหนึ่งหน้า พาธจะเป็นตัวเลือกขั้นตอน /prototype จะส่งคืนเฉพาะงาน prototype และ /build จะส่งคืนเฉพาะงาน build

Request

GET

/openapi/creative-lab/keychain/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

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

Name
stage
Type
path
จำเป็น
Description
ขั้นตอนที่จะแสดงรายการ prototype หรือ build

พารามิเตอร์คิวรี

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 ตามขั้นตอนที่ระบุในพาธ

The Keychain prototype task object

งาน prototype จะสร้างภาพคอนเซ็ปต์ที่มีสีสันจากภาพถ่าย หากต้องการแปลงภาพให้เป็นโมเดล 3D ให้ส่ง ID ของงานนั้นไปยัง build endpoint โดยใช้เป็น input_task_id

คุณสมบัติ

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "name_text": "Luna",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Name
id
Type
string
Description
ID ของงาน อย่าอ้างอิงจากรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของงาน ซึ่งเป็น creative-lab-keychain-prototype เสมอ
Name
name
Type
string
Description
name ที่คุณส่งมาตอนสร้างงาน หรือ "" ถ้าคุณไม่ได้ส่งมา
Name
name_text
Type
string
Description
ชื่อที่ Meshy เพิ่มให้กับพวงกุญแจ หลังจากตัดช่องว่างและนำอักขระจัดรูปแบบที่มองไม่เห็นออกแล้ว จะไม่ปรากฏเมื่อคุณไม่ได้ส่ง name_text มา เพื่อตรวจสอบว่า HTTP client ของคุณเข้ารหัสข้อความถูกต้อง ให้เปรียบเทียบกับสิ่งที่คุณส่งไป
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 ปีถัดไป ดูเพิ่มเติมที่ Asset retention
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 หนึ่งรายการหลังจากงานสำเร็จ และจะว่างเปล่าจนกว่าจะถึงเวลานั้น

The Keychain build task object

งาน build จะสร้างพวงกุญแจ 3D จากงาน prototype ที่สำเร็จแล้ว โดยจะส่งคืนไฟล์โมเดลหนึ่งไฟล์ในรูปแบบที่คุณร้องขอ

คุณสมบัติ

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

Name
id
Type
string
Description
รหัสของงาน อย่าอ้างอิงจากรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของงาน ซึ่งจะเป็น creative-lab-keychain-build เสมอ
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
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดไฟล์โมเดล โดยจะมีหนึ่งรายการสำหรับ output.format ที่คุณร้องขอ และเป็น {} จนกว่างานจะสำเร็จ
- Name
  glb
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ GLB จะปรากฏเมื่อ output.format เป็น glb
- Name
  obj
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ zip ที่มี model.obj, model.mtl และ texture.png จะปรากฏเมื่อ output.format เป็น obj
- Name
  bundle_zip
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ zip ที่รวมทุกไฟล์ที่ Meshy สร้างขึ้น จะปรากฏเมื่อ output.format เป็น zip