Creative Lab — Collapsible Fidget API

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

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

ต่างจาก endpoint อื่น ๆ ของ Creative Lab ตรงที่ endpoint นี้ไม่มีคู่ขั้นตอน ต้นแบบ/สร้าง (prototype/build) — ไม่มีตัวเลือกระหว่างกลางให้เลือก ดังนั้นงานเดียว จะพาภาพไปจนถึงขั้นตอนสร้างเป็นโมเดล 3D อย่างสมบูรณ์ ส่วนตัวควบคุมจีออเมทรีที่เว็บแอป เปิดให้ใช้ (ขนาด, จำนวนชั้น, ความกว้างของช่องว่าง, ความหนาผนัง, ความลึกของการอัดขึ้นรูป, การนูน) ก็ไม่ได้เป็นส่วนหนึ่งของคำขอเช่นกัน: ทุกงานจะถูกสร้างขึ้นด้วยค่าเริ่มต้น ฝั่งเซิร์ฟเวอร์ที่เหมือนกัน

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

สร้างงาน Collapsible Fidget

สร้างโมเดล collapsible fidget จากภาพถ่ายต้นฉบับ ดู The Collapsible Fidget Task Object สำหรับรูปแบบของการตอบกลับ

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

พารามิเตอร์

Name
image_url
Type
string
จำเป็น
Description
ภาพถ่ายต้นฉบับที่ให้ Meshy แปลงเป็น collapsible fidget ปัจจุบันเรารองรับรูปแบบ .jpg, .jpeg, .png, และ .webp
มีสองวิธีในการระบุรูปภาพ:
- URL ที่เข้าถึงได้แบบสาธารณะ: URL ที่สามารถเข้าถึงได้จากอินเทอร์เน็ตสาธารณะ
- Data URI: data URI ของรูปภาพที่เข้ารหัสแบบ base64 ตัวอย่างของ data URI: data:image/jpeg;base64,<your base64-encoded image data>
รูปภาพที่มีขอบเขตชัดเจนและปิดสนิทเพียงหนึ่งเดียวจะให้ผลลัพธ์ดีที่สุด — เงาของรูปภาพนี้เองที่จะกลายเป็นวงแหวน พื้นหลังที่รกรุงรัง มีวัตถุแยกหลายชิ้น หรือรูปทรงที่บางมากอาจเหลือพื้นที่ไม่เพียงพอสำหรับผนังที่ซ้อนกัน และงานจะล้มเหลวพร้อมข้อผิดพลาดของงาน
Name
name
Type
string
Description
ชื่องานที่ไม่บังคับสำหรับการแสดงผล สูงสุด 100 ตัวอักษร นี่เป็นเพียงป้ายกำกับของงานเท่านั้น จะไม่มีการสลักข้อความใด ๆ ลงบนโมเดล

สิ่งที่ส่งกลับ

พร็อพเพอร์ตี้ result ของการตอบกลับประกอบด้วย id ของงานที่สร้าง collapsible fidget ขึ้นใหม่ ทำการ poll เอนด์พอยต์ Get a Task หรือสมัครรับข้อมูลจาก stream จนกว่างานจะมีสถานะ SUCCEEDED จากนั้นดาวน์โหลดไฟล์ STL ที่พร้อมพิมพ์ได้จาก model_urls.stl (และหากมี ให้ดาวน์โหลด GLB จาก model_urls.glb เพื่อดูตัวอย่างก่อน)

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

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 คีย์ของคุณ
Name
402 - Payment Required
Description
บัญชีของคุณอยู่ในแผนฟรี — การสร้างงานบนเอนด์พอยต์นี้ต้องใช้แผนแบบชำระเงิน — หรือคุณมีเครดิตไม่เพียงพอ
Name
403 - Forbidden
Description
รูปภาพที่ป้อนเข้ามาถูกตั้งค่าสถานะว่าละเมิดทรัพย์สินทางปัญญา
Name
429 - Too Many Requests
Description
คุณเกินขีดจำกัดการจำกัดอัตราของคุณแล้ว

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

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

ดึงข้อมูล Collapsible Fidget Task

ดึงข้อมูล collapsible fidget task โดยระบุ id ของ task ที่ถูกต้อง มีเพียง task ที่สร้างขึ้นผ่านเอนด์พอยต์นี้เท่านั้นที่สามารถเข้าถึงได้ที่นี่ — task จากเอนด์พอยต์อื่นของ Creative Lab หรือ task ที่สร้างขึ้นในเว็บแอป จะได้รับผลลัพธ์เป็น 404

ดูรูปแบบของ response ได้ที่ The Collapsible Fidget Task Object

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุที่ไม่ซ้ำกันของ collapsible fidget task ที่ต้องการดึงข้อมูล

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

การตอบกลับจะประกอบด้วยอ็อบเจกต์ collapsible fidget task

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

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

ลบงาน Collapsible Fidget

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

Path Parameters

Name
id
Type
path
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงาน collapsible fidget ที่ต้องการยกเลิก

Returns

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

Failure Modes

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

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

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

สตรีมงาน Collapsible Fidget

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

พารามิเตอร์

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

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

ส่งกลับสตรีมของออบเจกต์งาน Collapsible Fidget ในรูปแบบ Server-Sent Events สำหรับงานที่มีสถานะ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะมีเพียงฟิลด์ progress และ status ที่จำเป็นเท่านั้น

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
  }
}

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

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

ดึงรายการ collapsible fidget task ของคุณแบบแบ่งหน้า โดยจะรวมเฉพาะ task ที่สร้างผ่านเอนด์พอยต์นี้เท่านั้น

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: เรียงตามเวลาที่สร้างจากมากไปน้อย

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

ส่งกลับรายการแบบแบ่งหน้าของ the collapsible fidget task object

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

The Collapsible Fidget Task Object

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

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุเฉพาะสำหรับงาน แม้ว่าเราจะใช้ k-sortable UUID สำหรับ id ของงานในรายละเอียดการทำงานจริง แต่คุณไม่ควรตั้งสมมติฐานใด ๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของงาน ค่านี้คือ creative-lab-fidget-collapsible
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 น. GMT จะแสดงเป็น 1693569600000 กฎนี้ใช้กับ ไทม์สแตมป์ทั้งหมดใน Meshy API
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานเริ่มดำเนินการ หน่วยเป็นมิลลิวินาที หากงานยังไม่เริ่มดำเนินการ ค่านี้จะเป็น null
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานเสร็จสิ้น หน่วยเป็นมิลลิวินาที หากงานยังไม่เสร็จสิ้น ค่านี้จะเป็น null
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
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดโมเดล 3D ที่สร้างขึ้น จะถูกกำหนดค่าเมื่องานมีสถานะ SUCCEEDED: stl จะปรากฏอยู่เสมอ ส่วน glb จะปรากฏเฉพาะเมื่อการเรนเดอร์ตัวอย่างสำเร็จเท่านั้น
- Name
  stl
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ STL นี่คือผลลัพธ์สำหรับพิมพ์โดยตรง — ส่งเข้าสไลเซอร์ได้ทันที
- Name
  glb
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ GLB ใช้สำหรับดูตัวอย่างโมเดลในตัวแสดงผล 3D สีที่ปรากฏใช้สำหรับดูตัวอย่างเท่านั้น เนื่องจาก STL ไม่มีข้อมูลสี และฟิดเจ็ตที่พิมพ์ออกมาจริงจะได้สีตามเส้นใยพลาสติก (filament) ที่ใช้พิมพ์ ไฟล์ GLB นี้เป็นแบบ best-effort กล่าวคือ เมื่อการเรนเดอร์ตัวอย่างไม่พร้อมใช้งาน คีย์นี้จะถูกละไว้จาก model_urls ทั้งหมด ดังนั้นควรอ่านค่านี้อย่างระมัดระวัง — stl คือผลลัพธ์ที่ส่งมอบและจะปรากฏอยู่เสมอเมื่องานมีสถานะ SUCCEEDED

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