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

Create a Collapsible Fidget Task

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

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

พารามิเตอร์

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

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

พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของ task collapsible fidget ที่สร้างขึ้นใหม่ ให้ polling ที่เอนด์พอยต์ Get a Task หรือสมัครรับข้อมูลจาก stream จนกว่า task จะมีสถานะเป็น 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
บัญชีของคุณอยู่ในแพลนฟรี — การสร้าง task บนเอนด์พอยต์นี้ต้องใช้แพลนแบบชำระเงิน — หรือคุณมีเครดิตไม่เพียงพอ
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

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

ดูรูปแบบของการตอบกลับได้ที่ The Collapsible Fidget Task Object

พารามิเตอร์

Name
id
Type
path
Description
รหัสประจำตัวที่ไม่ซ้ำกันของงาน collapsible fidget ที่ต้องการเรียกดู

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

การตอบกลับมีข้อมูล object ของงาน collapsible fidget

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 ทุกเฟรมจะมีอ็อบเจ็กต์งานฉบับเต็มสำหรับสถานะนั้น ๆ — รูปแบบเดียวกับที่ เอนด์พอยต์ Get ส่งกลับ — ดังนั้นในระหว่างที่งานอยู่ในสถานะ PENDING หรือ IN_PROGRESS ฟิลด์ผลลัพธ์จะยังไม่ถูกกำหนดค่า (null, [] หรือ {}) และ finished_at จะเป็น null

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 PENDING frame below is abbreviated 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=***"
  }
}

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

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

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

พารามิเตอร์ของคำค้นหา (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: เรียงตามเวลาที่สร้างจากมากไปน้อย

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

ส่งกลับรายการแบบแบ่งหน้าของ ออบเจกต์งาน collapsible fidget

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

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

Properties

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงาน แม้ว่าเราจะใช้ k-sortable UUID เป็นรายละเอียดการใช้งานสำหรับ task ids แต่คุณไม่ควรตั้งสมมติฐานใด ๆ เกี่ยวกับรูปแบบของ 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
ความคืบหน้าของงาน หากงานยังไม่เริ่ม property นี้จะเป็น 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
ไทม์สแตมป์ของเวลาที่งานเริ่มดำเนินการ หน่วยเป็นมิลลิวินาที หากงานยังไม่เริ่ม property นี้จะเป็น null
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานเสร็จสิ้น หน่วยเป็นมิลลิวินาที หากงานยังไม่เสร็จสิ้น property นี้จะเป็น 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 viewer สีของไฟล์นี้มีไว้สำหรับดูตัวอย่างเท่านั้น: STL ไม่มีข้อมูลสี และ fidget ที่พิมพ์ออกมาจะได้สีจากเส้นใยพลาสติก (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=***"
  }
}