Creative Lab — API พวงกุญแจ

เปลี่ยนภาพถ่ายต้นฉบับให้กลายเป็นเหรียญพวงกุญแจที่พิมพ์ 3 มิติได้ — ภาพนูนต่ำแบบมีสีในรูปทรงตราสัญลักษณ์ — ผ่านสองขั้นตอน: prototype จะสร้างภาพคอนเซ็ปต์แบบมีสีจากภาพต้นฉบับที่คุณป้อนเข้ามา จากนั้น build จะแปลงภาพคอนเซ็ปต์นั้นให้กลายเป็นโมเดล 3 มิติแบบนูนต่ำ ทั้งสองขั้นตอนเชื่อมโยงกันผ่าน 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

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

พารามิเตอร์

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

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

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

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

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

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

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

สร้างงาน Keychain Build

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

พารามิเตอร์

Name
input_task_id
Type
string
จำเป็น
Description
ไอดีงานของงานต้นแบบ (prototype task) ที่สร้างผ่านเอนด์พอยต์ OpenAPI เดียวกันนี้ ต้นแบบนี้ต้องถูกสร้างด้วย API คีย์เดียวกัน ต้องมีสถานะถึง SUCCEEDED แล้ว และต้องสร้างภาพผู้สมัคร (candidate image) ได้เพียงหนึ่งภาพเท่านั้น
งานต้นแบบที่สร้างผ่าน webapp จะไม่ได้รับการยอมรับ — เอนด์พอยต์ build ยอมรับเฉพาะงานต้นแบบที่สร้างโดย POST /openapi/creative-lab/keychain/v1/prototype เท่านั้น และจะปฏิเสธแหล่งที่มาอื่นใดด้วย 404
Name
name
Type
string
Description
ชื่องานที่ไม่บังคับสำหรับการแสดงผล ยาวได้สูงสุด 100 อักขระ

`options`

พารามิเตอร์ปรับแต่งที่ไม่บังคับสำหรับจีออเมทรีของ relief ทุกฟิลด์มีค่าเริ่มต้นที่เหมาะสมอยู่แล้ว — ส่งเฉพาะฟิลด์ที่คุณต้องการเปลี่ยนแปลงเท่านั้น

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

`output`

ตัวเลือกรูปแบบไฟล์ที่ไม่บังคับ ค่าเริ่มต้นคือ glb

Name
format
Type
string
ค่าเริ่มต้น glb
Description
ชุดไฟล์ผลลัพธ์ที่ส่งกลับโดยการ build ค่าที่ใช้ได้:
- glb (ค่าเริ่มต้น) — ส่งกลับไฟล์ model.glb เดียวภายใต้ model_urls.glb
- obj — บีบอัด model.obj + model.mtl + texture.png และส่งกลับชุดไฟล์ภายใต้ model_urls.obj
- zip — บีบอัดทุกไฟล์ผลลัพธ์ที่ตัวสร้างสร้างขึ้นและส่งกลับชุดไฟล์ภายใต้ model_urls.bundle_zip

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

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

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

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

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

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

ดึงข้อมูลงานพวงกุญแจ

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

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

พารามิเตอร์

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

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

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

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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

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

Delete a Keychain Task

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

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

Path Parameters

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

Returns

คืนค่า 204 No Content เมื่อสำเร็จ โดยมี body ว่างเปล่า

Failure Modes

Name
400 - Bad Request
Description
งานนี้อยู่ในสถานะสุดท้ายแล้วและไม่สามารถยกเลิกได้
Name
404 - Not Found
Description
ไม่พบงานนี้ เป็นของผู้ใช้คนอื่น หรือ stage ของงานไม่ตรงกับ URL path

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

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

Stream a Keychain Task

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

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงานพวงกุญแจที่ต้องการสตรีม

สิ่งที่ได้รับกลับมา

ส่งคืนสตรีมของออบเจ็กต์งาน Keychain Prototype หรือ Keychain Build ในรูปแบบ Server-Sent Events ทุกเฟรมจะบรรจุออบเจ็กต์งานฉบับเต็มของขั้นตอนนั้น ๆ — รูปแบบเดียวกับที่ เอนด์พอยต์ Get ส่งคืน — ดังนั้นในขณะที่งานยังอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ผลลัพธ์ต่าง ๆ จะยังไม่มีข้อมูล (null, [] หรือ {}) และ finished_at จะเป็น null

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 PENDING frame below is abbreviated 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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

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

List Keychain Tasks

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

Path Parameters

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

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

คืนรายการแบบแบ่งหน้าของออบเจ็กต์งานตามแต่ละสเตจ — อาจเป็น ออบเจ็กต์งานต้นแบบพวงกุญแจ เมื่อดูรายการ /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=***"
    ]
  }
]

The Keychain Prototype Task Object

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

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงาน แม้ว่าเราจะใช้ k-sortable UUID สำหรับ task id เป็นรายละเอียดในการนำไปใช้งาน แต่คุณไม่ควรตั้งสมมติฐานใดๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของงาน ค่านี้คือ creative-lab-keychain-prototype
Name
name
Type
string
Description
ชื่องานที่ระบุไว้ตอนสร้างงาน จะเป็นสตริงว่างหากไม่ได้ระบุชื่อไว้
Name
name_text
Type
string
Description
ข้อความที่จะสลักลงบนพวงกุญแจนี้ หลังจากตัดช่องว่างและอักขระจัดรูปแบบที่มองไม่เห็นออกแล้ว จะไม่มีค่านี้หากสร้างงานโดยไม่ได้ระบุ name_text เปรียบเทียบค่านี้กับสิ่งที่คุณส่งไปเพื่อยืนยันว่าข้อความยังคงอยู่ครบถ้วนหลังจากผ่านการเข้ารหัสของ HTTP client ของคุณ
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
ไทม์สแตมป์ของเวลาที่สร้างงาน หน่วยเป็นมิลลิวินาที
ไทม์สแตมป์แสดงถึงจำนวนมิลลิวินาทีที่ผ่านไปนับตั้งแต่วันที่ 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
จำนวนเครดิตที่ใช้ไปสำหรับงานนี้ จะมีค่านี้เมื่อสถานะของงานเป็น PENDING, IN_PROGRESS, หรือ SUCCEEDED จะคืนค่า 0 สำหรับงานที่ FAILED (เครดิตจะถูกคืนเมื่อล้มเหลว)
Name
image_urls
Type
array of strings
Description
URL สำหรับดาวน์โหลดตัวเลือกภาพคอนเซ็ปต์ที่สร้างขึ้นโดยงานต้นแบบนี้ ปัจจุบัน API จะส่งคืนตัวเลือกเดียวเสมอ ฟิลด์นี้เป็นอาร์เรย์เพื่อให้เวอร์ชันในอนาคตสามารถแสดงตัวเลือกหลายรายการได้โดยไม่ต้องเปลี่ยนแปลงแบบ breaking change

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

The Keychain Build Task Object

Keychain Build Task object คือหน่วยงานที่ Meshy ใช้ติดตามเพื่อสร้างเมช 3D ของพวงกุญแจขั้นสุดท้ายจาก prototype task ที่สำเร็จแล้ว การ build จะรัน pipeline การสร้างรูปนูนด้วยแผนที่ความลึก (depth-map relief) บนภาพคอนเซ็ปต์ของ prototype และเผยแพร่ artifact เมชเดียวในรูปแบบที่ผู้เรียกใช้งานร้องขอ

Properties

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับ task
Name
type
Type
string
Description
ประเภทของ task ค่าคือ creative-lab-keychain-build
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 มีหน่วยเป็นมิลลิวินาที
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่เริ่ม task มีหน่วยเป็นมิลลิวินาที
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น มีหน่วยเป็นมิลลิวินาที
Name
expires_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ผลลัพธ์ของ task จะหมดอายุ มีหน่วยเป็นมิลลิวินาที
Name
preceding_tasks
Type
integer
Description
จำนวน task ที่อยู่ก่อนหน้า มีความหมายเฉพาะเมื่อสถานะเป็น PENDING
Name
task_error
Type
object
Description
รายละเอียดข้อผิดพลาดสำหรับ task ที่ล้มเหลว ดู ข้อผิดพลาด สำหรับข้อมูลอ้างอิงฉบับเต็มของอ็อบเจ็กต์ task_error
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ใช้ไปโดย task นี้ จะคืนค่า 0 สำหรับ task ที่ FAILED (เครดิตจะถูกคืนเมื่อล้มเหลว)
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลด artifact ที่สร้างขึ้น โดยจัดกลุ่มตามชื่อ artifact จะมีเพียงหนึ่งรายการเสมอ — รูปแบบที่ร้องขอผ่าน output.format ของคำขอ build คีย์จะตรงกับรูปแบบที่ร้องขอ:
- 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 ที่รวม artifact ทุกรายการที่ตัวสร้างสรรค์สร้างขึ้น จะปรากฏเมื่อ output.format เป็น zip

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": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}