Creative Lab — Fridge Magnet API

เปลี่ยนภาพถ่ายของคุณให้เป็นแม่เหล็กติดตู้เย็นแบบกำหนดเอง — ภาพนูนต่ำ (depth relief) สีสี่เหลี่ยมมุมมนที่มีด้านหลังแบบแม่เหล็กเรียบ ขนาดพอดีสำหรับติดตู้เย็น — โดยแบ่งเป็นสองขั้นตอน: prototype จะสร้างภาพคอนเซปต์ที่มีการลงสีจากภาพถ่ายต้นฉบับของคุณ จากนั้น build จะเปลี่ยนภาพคอนเซปต์นั้นให้เป็นโมเดล 3D แบบนูนต่ำ ทั้งสองขั้นตอนนี้เชื่อมโยงกันผ่าน input_task_id

POST /openapi/creative-lab/fridge-magnet/v1/prototype
POST /openapi/creative-lab/fridge-magnet/v1/build

POST/openapi/creative-lab/fridge-magnet/v1/prototype

สร้างงาน Fridge Magnet Prototype

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

พารามิเตอร์

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

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

พร็อพเพอร์ตี้ result ของ response จะมี id ของงาน fridge magnet prototype ที่สร้างขึ้นใหม่ ให้ทำการ poll เอนด์พอยต์ Get a Task หรือติดตามผ่าน stream จนกว่างานจะมีสถานะเป็น SUCCEEDED จากนั้นจึงส่งไอดีนั้นไปยัง 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 มีรูปแบบผิดพลาด
- เนื้อหาถูกตั้งค่าสถานะ: ภาพที่ส่งเข้ามาถูกตั้งค่าสถานะโดยระบบ moderation ด้าน NSFW หรือทรัพย์สินทางปัญญา
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอสำหรับดำเนินงานนี้
Name
429 - Too Many Requests
Description
คุณส่งคำขอเกินขีดจำกัดอัตราที่กำหนด

Request

POST

/openapi/creative-lab/fridge-magnet/v1/prototype

# Stage 1: generate a colorized fridge magnet concept image
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype \
  -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": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9"
}

Prototype example

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

Source landscape photo used as the Creative Lab Fridge Magnet input — Prototype input

Creative Lab Fridge Magnet prototype output generated from the source photo — Prototype output

POST/openapi/creative-lab/fridge-magnet/v1/build

สร้าง Fridge Magnet Build Task

สร้างแม่เหล็กติดตู้เย็นสำหรับพิมพ์ 3 มิติขั้นสุดท้ายจาก prototype task ที่สำเร็จแล้ว การ build จะรัน depth-map relief pipeline บนภาพคอนเซปต์ที่ลงสีแล้วของ prototype และส่งมอบมี artifact แบบเมชเดียวในรูปแบบที่คุณต้องการ ดู The Fridge Magnet Build Task Object สำหรับ รูปแบบของการตอบกลับ

พารามิเตอร์

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

`options`

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

Name
badge_shape
Type
string
ค่าเริ่มต้น rounded-rect
Description
เค้าโครงเส้นขอบของแม่เหล็กติดตู้เย็น ค่าที่ใช้ได้:
- circle
- rounded-rect (ค่าเริ่มต้น)
- hexagon
- shield
- star
Name
size_mm
Type
number
ค่าเริ่มต้น 60
Description
ความยาวขอบของสี่เหลี่ยมขอบเขตของแม่เหล็กติดตู้เย็น มีหน่วยเป็นมิลลิเมตร ช่วงค่า: (0, 400]
Name
relief_height_mm
Type
number
ค่าเริ่มต้น 3.3
Description
ความสูงของ relief สูงสุดเหนือฐาน มีหน่วยเป็นมิลลิเมตร ช่วงค่า: [0, 20]
Name
relief_offset_mm
Type
number
ค่าเริ่มต้น 0
Description
ระยะเลื่อนแนวตั้งที่ใช้กับ relief ก่อนการอัดขึ้นรูป มีหน่วยเป็นมิลลิเมตร ช่วงค่า: [0, 20]
Name
base_thickness_mm
Type
number
ค่าเริ่มต้น 2.0
Description
ความหนาของแผ่นฐานที่อยู่ด้านหลัง relief มีหน่วยเป็นมิลลิเมตร ค่าเริ่มต้นของ fridge-magnet คือฐานที่หนากว่าที่ 2 มม. — เพื่อให้แม่เหล็กมีเนื้อวัสดุมากพอที่จะยึดติดกับตู้เย็นได้โดยที่ relief ไม่รู้สึกเปราะบาง ช่วงค่า: [0, 20]
Name
has_closed_back
Type
boolean
ค่าเริ่มต้น true
Description
กำหนดว่าด้านหลังของแม่เหล็กติดตู้เย็นจะถูกปิดเป็นพื้นผิวปิด (ด้านที่คุณติดแม่เหล็กเข้าไป) หรือไม่ ตั้งเป็น false เพื่อให้เป็นเปลือกแบบเปิด
Name
relief_curve
Type
string
ค่าเริ่มต้น linear
Description
เคิร์ฟถ่ายทอดที่แปลงค่า 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
ความเข้มของการปรับให้เรียบที่ใช้กับ 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
ค่าขีดจำกัดต่ำสุดของค่า depth-map ค่าที่ต่ำกว่านี้จะถูกปรับให้เป็นศูนย์ ช่วงค่า: [0, 1]
Name
remove_background
Type
boolean
ค่าเริ่มต้น true
Description
ลบพื้นหลังของภาพคอนเซปต์ของ prototype โดยอัตโนมัติก่อนทำ relief
แยกจากพารามิเตอร์ของ prototype ที่มีชื่อเดียวกัน (ค่าเริ่มต้น false) ซึ่งควบคุมว่าภาพ prototype เองจะถูกส่งกลับมาแบบมีความโปร่งใสหรือไม่
Name
export_resolution
Type
integer
ค่าเริ่มต้น 512
Description
ความละเอียดของเมชที่ใช้ในการส่งออก ช่วงค่า: [64, 2048]

`output`

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

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

ผลลัพธ์ที่ส่งกลับ

พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของ task การ build แม่เหล็กติดตู้เย็นที่สร้างขึ้นใหม่ ให้เรียกดูข้อมูลซ้ำ ๆ (poll) ที่เอนด์พอยต์ Get a Task หรือสมัครรับ stream จนกว่า task จะมีสถานะถึง SUCCEEDED จากนั้นดาวน์โหลด artifact จากรายการเดียวใน model_urls

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

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

Request

POST

/openapi/creative-lab/fridge-magnet/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
    "options": {
      "badge_shape": "rounded-rect",
      "size_mm": 60,
      "relief_height_mm": 3.3
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0"
}

Build example

The build task turns the selected prototype image into a 3D-printable fridge magnet model.

Creative Lab Fridge Magnet build model preview — Build model preview

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

เรียกดูงาน Fridge Magnet

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

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

พารามิเตอร์

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

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

การตอบกลับจะมีอ็อบเจกต์งานแม่เหล็กติดตู้เย็น โดยรูปแบบจะขึ้นอยู่กับ ขั้นตอนที่ขอไป

Request

GET

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
  "type": "creative-lab-fridge-magnet-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543210000,
  "started_at": 1729543215000,
  "finished_at": 1729543242000,
  "expires_at": 1729802442000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

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

ลบงานแม่เหล็กติดตู้เย็น

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

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

พารามิเตอร์เส้นทาง

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

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

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

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

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

Request

DELETE

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

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

Stream a Fridge Magnet Task

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

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงานแม่เหล็กติดตู้เย็นที่จะสตรีม

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

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

Request

GET

/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/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": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

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

List Fridge Magnet Tasks

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

Path Parameters

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

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

Request

GET

/openapi/creative-lab/fridge-magnet/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
    "type": "creative-lab-fridge-magnet-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729543210000,
    "started_at": 1729543215000,
    "finished_at": 1729543242000,
    "expires_at": 1729802442000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

The Fridge Magnet Prototype Task Object

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

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับงาน แม้ว่าเราจะใช้ k-sortable UUID สำหรับ task id ในรายละเอียดการทำงานจริง แต่คุณไม่ควรสมมติเกี่ยวกับรูปแบบของ id นี้
Name
type
Type
string
Description
ประเภทของงาน ค่านี้คือ creative-lab-fridge-magnet-prototype
Name
name
Type
string
Description
ชื่อของงานที่ระบุไว้ตอนสร้างงาน จะเป็นสตริงว่างหากไม่ได้ระบุชื่อไว้
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 น. 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 Fridge Magnet Prototype Task Object

{
  "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
  "type": "creative-lab-fridge-magnet-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543210000,
  "started_at": 1729543215000,
  "finished_at": 1729543242000,
  "expires_at": 1729802442000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

The Fridge Magnet Build Task Object

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

Properties

Name
id
Type
string
Description
ตัวระบุที่ไม่ซ้ำกันสำหรับ task
Name
type
Type
string
Description
ประเภทของ task ค่านี้คือ creative-lab-fridge-magnet-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 สำหรับดาวน์โหลดผลลัพธ์ที่สร้างขึ้น โดยจัดกลุ่มตามชื่อผลลัพธ์ จะมีเพียงหนึ่งรายการเสมอ — รูปแบบที่ระบุผ่าน 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 ที่รวมผลลัพธ์ทั้งหมดที่ตัวสร้างสร้างขึ้น จะปรากฏเมื่อ output.format เป็น zip

Example Fridge Magnet Build Task Object

{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}