Creative Lab Collapsible Fidget API

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

POST /openapi/creative-lab/fidget-collapsible/v1

ต่างจาก endpoint อื่นๆ ของ Creative Lab endpoint นี้ไม่มีขั้นตอน prototype และ build แยกจากกัน ไม่มีภาพตัวเลือกให้เลือกเปรียบเทียบ ดังนั้นงานเดียวก็เปลี่ยนภาพถ่ายให้กลายเป็นโมเดล 3 มิติได้เลย

คำขอนี้ไม่มีการตั้งค่าจีออเมทรีเช่นกัน เว็บแอปให้คุณตั้งค่าขนาด จำนวนชั้น ความกว้างของช่องว่าง ความหนาผนัง ความลึกของการอัดขึ้นรูป และความนูนได้ ส่วนงานผ่าน API ทุกงานจะใช้ค่าเริ่มต้นเดียวกันสำหรับค่าเหล่านี้

POST/openapi/creative-lab/fidget-collapsible/v1

สร้างงาน Collapsible Fidget

สร้างโมเดล collapsible fidget จากภาพถ่าย สำหรับฟิลด์ต่าง ๆ ของงาน โปรดดู The Collapsible Fidget task object

แต่ละงานมีค่าใช้จ่าย 6 เครดิต และต้องใช้แพลนแบบชำระเงิน

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -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": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

พารามิเตอร์

Name
image_url
Type
string
จำเป็น
Description
ภาพถ่ายที่จะแปลงเป็น collapsible fidget โดยระบุเป็น 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 ของงาน และ Meshy จะไม่สลักชื่อนี้ลงบนโมเดล หากชื่อยาวเกินไปจะได้ผลลัพธ์เป็น 400

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

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

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

Name
400 - Bad Request
Description
คำขอนี้ไม่สามารถทำงานได้ ตัวอย่างเช่น:
- ไม่มี image_url
- ภาพไม่ใช่ไฟล์ JPG, JPEG, PNG หรือ WebP
- ภาพมีขนาดเล็กเกินไป ใหญ่กว่า 20 MB หรือเกินจำนวนพิกเซลสูงสุด
- Meshy ไม่สามารถดาวน์โหลดภาพได้ เช่น เพราะ URL ส่งค่ากลับเป็น 404 หรือหมดเวลา
- data URI ไม่ใช่ base64 ที่ถูกต้อง
- ภาพถูกตรวจพบว่าเป็น NSFW
ข้อความแสดงข้อผิดพลาดจะระบุปัญหาที่พบ แก้ไขคำขอแล้วส่งอีกครั้ง
Name
401 - Unauthorized
Description
ไม่มี API คีย์ หรือ 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 จะไม่สร้างงานนี้ และจะคืนเครดิตที่เรียกเก็บไปแล้ว ลองส่งคำขออีกครั้ง

GET/openapi/creative-lab/fidget-collapsible/v1/:id

รับงาน Collapsible Fidget

คืนค่างาน Collapsible Fidget ระบบจะคืนค่าเฉพาะงานที่สร้างด้วยเอนด์พอยต์นี้เท่านั้น งานจากเอนด์พอยต์ Creative Lab อื่น หรืองานที่สร้างในเว็บแอป จะคืนค่า 404

สำหรับฟิลด์ต่าง ๆ ดูที่ The Collapsible Fidget task object

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

พารามิเตอร์

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

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

Collapsible Fidget task object

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

Name
400 - Bad Request
Description
id ไม่ใช่รหัสงานที่ถูกต้อง ให้ส่งรหัส result จากการตอบกลับของการสร้าง
Name
403 - Forbidden
Description
ทีมของคุณเปิดใช้งาน IP Filtering และ Meshy ตรวจพบว่ารูปภาพของงานนี้มีปัญหาด้านทรัพย์สินทางปัญญาของบุคคลที่สาม ทีมที่ใช้แพ็กเกจ Enterprise จะไม่พบข้อผิดพลาดนี้ ให้สร้างงานจากรูปภาพที่คุณมีสิทธิ์ใช้งาน
Name
404 - Not Found
Description
ไม่มีงาน Collapsible Fidget ที่มีรหัสนี้อยู่ในบัญชีของคุณ หรือไม่ได้สร้างงานนี้ด้วยเอนด์พอยต์นี้ ตรวจสอบรหัสอีกครั้ง
Name
500 - Internal Server Error
Description
Meshy ไม่สามารถตรวจสอบทรัพย์สินทางปัญญาได้ กรุณาลองส่งคำขออีกครั้ง

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

ลบงาน Collapsible Fidget

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

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

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

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

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

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

204 No Content พร้อมเนื้อหาว่างเปล่า

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

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

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

สตรีมงาน Collapsible Fidget

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

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

พารามิเตอร์

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

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

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

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

GET/openapi/creative-lab/fidget-collapsible/v1

แสดงรายการ Collapsible Fidget tasks

คืนค่า Collapsible Fidget tasks ของคุณ ครั้งละหนึ่งหน้า จะรวมเฉพาะ task ที่สร้างผ่านเอนด์พอยต์นี้เท่านั้น

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

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

Name
page_num
Type
integer
ค่าเริ่มต้น 1
Description
หน้าที่ต้องการให้คืนค่า ตั้งแต่ 1 ถึง 255 ค่า 0 จะคืนค่าหน้าแรก ค่าที่อยู่นอกช่วง 0 ถึง 255 จะคืนค่า 400
Name
page_size
Type
integer
ค่าเริ่มต้น 10
Description
จำนวน task ต่อหน้า สูงสุด 100 ค่าตั้งแต่ 101 ถึง 255 จะคืนค่า 100 tasks และ 0 จะใช้ค่าเริ่มต้น ค่าที่อยู่นอกช่วง 0 ถึง 255 จะคืนค่า 400
Name
sort_by
Type
string
ค่าเริ่มต้น -created_at
Description
ลำดับการเรียง
ค่าที่ใช้ได้:
- -created_at: ใหม่สุดก่อน
- +created_at: เก่าสุดก่อน

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

อาร์เรย์ของ Collapsible Fidget task objects

ออบเจ็กต์งาน Collapsible Fidget

งาน Collapsible Fidget จะเปลี่ยนภาพถ่ายให้เป็นโมเดล fidget แบบพับเก็บได้ที่พิมพ์ได้ในที่เดียว (print-in-place) เป็นงานขั้นตอนเดียว จึงไม่มีงานต้นแบบ (prototype) ให้เชื่อมต่อมาจาก การตอบกลับไม่รวมภาพเงา (silhouette) ที่ Meshy สร้างขึ้นระหว่างขั้นตอนนี้

คุณสมบัติ

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Name
id
Type
string
Description
รหัสงาน อย่าอ้างอิงตามรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของงาน ซึ่งจะเป็น creative-lab-fidget-collapsible เสมอ
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 สำหรับดาวน์โหลดโมเดล 3D ซึ่งจะว่างเปล่าจนกว่างานจะสำเร็จ งานที่สำเร็จจะมี stl เสมอ และจะมี glb ก็ต่อเมื่อ Meshy ได้เรนเดอร์ภาพตัวอย่างไว้
- Name
  stl
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ STL ซึ่งเป็นไฟล์ที่ใช้พิมพ์ คุณสามารถเปิดไฟล์นี้ได้โดยตรงในสไลเซอร์
- Name
  glb
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ GLB เพื่อดูตัวอย่างโมเดลในโปรแกรมดูภาพ 3D สีของไฟล์นี้ใช้สำหรับการแสดงตัวอย่างเท่านั้น ไฟล์ STL ไม่มีสี ดังนั้น fidget ที่พิมพ์ออกมาจะได้สีตามเส้นไฟลาเมนต์
  หาก Meshy ไม่สามารถเรนเดอร์ภาพตัวอย่างได้ model_urls จะไม่มีคีย์ glb จึงควรตรวจสอบว่ามีคีย์นี้อยู่หรือไม่ก่อนที่จะอ่านค่า งานที่มีสถานะ SUCCEEDED จะมี stl เสมอ