Creative Lab Lamp API

แปลงภาพถ่ายให้กลายเป็นโป๊ะโคมไฟที่พิมพ์ 3 มิติได้ในสองขั้นตอน งานต้นแบบจะสร้างภาพแนวคิดสีขาวด้านและแปลงเป็นโมเดล 3 มิติ งานสร้าง (build task) ซึ่งใช้ ID ของงานต้นแบบเป็น input_task_id จะแปลงโมเดลนั้นให้เป็นชิ้นส่วน STL ที่สามารถพิมพ์ได้ เมื่อใช้ fixture preset เริ่มต้น ชิ้นส่วนจะเป็นโป๊ะโคมไฟแบบเปิดด้านล่างพร้อมแผ่นฐานสำหรับฟิกซ์เจอร์ไฟ และตัวยึดฟิกซ์เจอร์

POST /openapi/creative-lab/lamp/v1/prototype
POST /openapi/creative-lab/lamp/v1/build

POST/openapi/creative-lab/lamp/v1/prototype

สร้างงาน Lamp prototype

สร้างภาพคอนเซ็ปต์สีขาวด้านหนึ่งภาพจากรูปถ่าย และแปลงเป็นโมเดลโคมไฟแบบ 3D งานนี้จะส่งคืนภาพคอนเซ็ปต์ใน image_urls และโมเดลใน model_urls.glb พร้อมภาพตัวอย่างใน thumbnail_url หากต้องการสร้างชิ้นส่วนที่พิมพ์ได้ ให้ส่ง ID ของงานนี้ไปยัง build endpoint ในชื่อ input_task_id สำหรับฟิลด์ต่าง ๆ ของงาน โปรดดูที่ The Lamp prototype task object

Request

POST

/openapi/creative-lab/lamp/v1/prototype

# Stage 1: concept image + 3D lampshade model from a source photo
curl https://api.meshy.ai/openapi/creative-lab/lamp/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>",
    "image_subject": "character"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Prototype example

เริ่มต้นด้วยรูปถ่ายต้นฉบับ ขั้นตอน prototype จะส่งคืนภาพคอนเซ็ปต์และโมเดล 3D ที่ขั้นตอน build จะนำไปประมวลผลต่อ

Source cat photo used as the Creative Lab Lamp input — Prototype input

Creative Lab Lamp prototype output generated from the source photo — Prototype output

พารามิเตอร์

Name
image_url
Type
string
จำเป็น
Description
รูปถ่ายที่ใช้เป็นต้นแบบของโคมไฟ โดยระบุเป็น URL สาธารณะ หรือ Data URI (data:image/jpeg;base64,<your base64-encoded image data>)
รูปภาพต้องเป็นไฟล์ JPG, JPEG, PNG หรือ WebP ที่มีขนาดไม่เกิน 20 MB

Name
image_subject
Type
string
ค่าเริ่มต้น character
Description
ประเภทของสิ่งที่อยู่ในรูปภาพ ซึ่งจะกำหนดวิธีที่ Meshy ใช้สร้างสไตล์ให้
ค่าที่ใช้ได้:
- character: ตัวละครหรือวัตถุเดี่ยว เช่น ฟิกเกอร์ สัตว์ หรือมาสคอต
- landscape: ฉากหรือทัศนียภาพกลางแจ้ง เช่น ภูเขา ทิวทัศน์เมือง หรือป่า
Name
name
Type
string
Description
ชื่อสำหรับงาน ความยาวไม่เกิน 100 ตัวอักษร ชื่อนี้จะถูกส่งกลับมาในฟิลด์ name ของงาน หากชื่อยาวเกินไปจะส่งคืน 400
Name
remove_background
Type
boolean
ค่าเริ่มต้น false
Description
กำหนดว่าจะลบพื้นหลังออกจากภาพต้นแบบหรือไม่ หากตั้งเป็น true จะส่งคืนภาพ PNG แบบ RGBA ที่มีพื้นโปร่งใส ทำให้คุณสามารถวางตัวแบบลงบนพื้นหลังใดก็ได้ Meshy จะสร้างโมเดล 3D จากภาพโดยไม่รวมพื้นหลังด้วยเช่นกัน หาก Meshy ไม่สามารถลบพื้นหลังได้ จะใช้ภาพที่มีพื้นหลังเดิมแทน และงานยังคงสำเร็จ

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

ฟิลด์ result จะเก็บ ID ของงาน prototype ใหม่ ดึงข้อมูลงาน หรือ สตรีมข้อมูลงาน จนกว่า status จะเป็น SUCCEEDED จากนั้นส่ง ID นั้นไปยัง build endpoint ในชื่อ input_task_id

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

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

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

สร้างงาน build สำหรับ Lamp

สร้างชิ้นส่วนที่พิมพ์แบบ 3D ได้จากงาน prototype ที่สำเร็จแล้ว Meshy จะปรับขนาดโมเดลของ prototype ให้เป็น diameter_mm ตัดด้านล่างให้แบนตาม cut_amount_percent และเจาะกลวงให้มี ความหนาผนัง thickness_mm เมื่อใช้ fixture preset ระบบจะเปิดด้านล่าง เพิ่มแผ่นฐานที่มีรูสำหรับ fixture และสร้างฐานยึดแยกต่างหากสำหรับหลอดไฟ สำหรับฟิลด์ของงานนี้ ดูที่ อ็อบเจ็กต์งาน build ของ Lamp

Request

POST

/openapi/creative-lab/lamp/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/lamp/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": {
      "diameter_mm": 120,
      "thickness_mm": 2,
      "light_source_preset": "bambu_mh001_60mm",
      "cut_amount_percent": 30
    },
    "output": {
      "format": "stl"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

ตัวอย่างการ build

งาน build จะแปลงโมเดล 3D ของ prototype ให้เป็นชิ้นส่วนโคมไฟที่พิมพ์ได้

ตัวอย่างโมเดล build ของ Lamp ใน Creative Lab — ตัวอย่างโมเดล build

พารามิเตอร์

Name
input_task_id
Type
string
จำเป็น
Description
ID ของงาน prototype ที่จะ build ต้องเป็นงานที่บัญชีของคุณสร้างด้วย POST /openapi/creative-lab/lamp/v1/prototype และมีสถานะ SUCCEEDED
ID ที่ไม่ใช่งาน prototype ของ Lamp จาก API ของคุณจะส่งคืน 404 รวมถึง prototype ที่สร้างในเว็บแอปด้วย
Name
name
Type
string
Description
ชื่อสำหรับงาน ความยาวไม่เกิน 100 ตัวอักษร ชื่อนี้จะถูกส่งกลับมาในฟิลด์ name ของงาน หากชื่อยาวเกินไปจะส่งคืน 400

`options`

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

Name
diameter_mm
Type
number
ค่าเริ่มต้น 150
Description
ขนาดมิติที่ใหญ่ที่สุดของโคมไฟ เป็นมิลลิเมตร ตั้งแต่ 50 ถึง 400 Meshy จะปรับขนาดโมเดลให้พอดีอย่างสม่ำเสมอ 0 จะใช้ค่าเริ่มต้น และค่าอื่นใดนอกช่วงจะส่งคืน 400
Name
thickness_mm
Type
number
ค่าเริ่มต้น 1
Description
ความหนาผนังของโคมไฟ เป็นมิลลิเมตร สูงสุด 10 0 จะใช้ค่าเริ่มต้น และค่าติดลบหรือค่าที่เกิน 10 จะส่งคืน 400
Name
cut_amount_percent
Type
number
ค่าเริ่มต้น 1
Description
เปอร์เซ็นต์ของความสูงโมเดลที่จะตัดให้แบนที่ด้านล่าง ตั้งแต่ 1 ถึง 100 ด้านล่างที่แบนช่วยให้โคมไฟวางบนแท่นพิมพ์ได้และเหลือพื้นที่สำหรับ fixture ค่าที่อยู่นอกช่วงจะส่งคืน 400
Name
light_source_preset
Type
string
ค่าเริ่มต้น bambu_mh001_60mm
Description
พรีเซ็ตของอุปกรณ์ไฟ ซึ่งกำหนดวิธีที่ Meshy สร้างด้านล่าง
ค่าที่ใช้ได้:
- bambu_mh001_60mm: โคมไฟแบบเปิดด้านล่างพร้อมแผ่นฐานที่มีรู fixture ขนาด 60 มม. ทั้งคู่อยู่ใน model_urls.lamp_stl และฐานยึดอยู่ใน model_urls.base_stl
- none: โคมไฟแบบปิดสนิทชิ้นเดียวใน model_urls.lamp_stl โดยไม่มี model_urls.base_stl
Name
fixture_offset_x_mm
Type
number
ค่าเริ่มต้น 0
Description
ระยะที่จะเลื่อนรู fixture ตามแกน X จากจุดศูนย์กลางของโคมไฟ เป็นมิลลิเมตร ตั้งแต่ -80 ถึง 80 ใช้ได้เฉพาะเมื่อ light_source_preset ไม่ใช่ none
Name
fixture_offset_z_mm
Type
number
ค่าเริ่มต้น 0
Description
ระยะที่จะเลื่อนรู fixture ตามแกน Z (ความลึก) จากจุดศูนย์กลางของโคมไฟ เป็นมิลลิเมตร ตั้งแต่ -80 ถึง 80 ใช้ได้เฉพาะเมื่อ light_source_preset ไม่ใช่ none
Name
rotate_x_deg
Type
number
ค่าเริ่มต้น 0
Description
การหมุนรอบแกน X ที่จะใช้กับโมเดลก่อนที่ Meshy จะประมวลผล เป็นองศา ตั้งแต่ -360 ถึง 360 Meshy จะใช้การหมุนทั้งสามแกนเป็นมุม Euler แบบ XYZ รอบจุดศูนย์กลางของโมเดล
Name
rotate_y_deg
Type
number
ค่าเริ่มต้น 0
Description
การหมุนรอบแกน Y ที่จะใช้กับโมเดลก่อนที่ Meshy จะประมวลผล เป็นองศา ตั้งแต่ -360 ถึง 360
Name
rotate_z_deg
Type
number
ค่าเริ่มต้น 0
Description
การหมุนรอบแกน Z ที่จะใช้กับโมเดลก่อนที่ Meshy จะประมวลผล เป็นองศา ตั้งแต่ -360 ถึง 360
Name
include_result_json
Type
boolean
ค่าเริ่มต้น false
Description
กำหนดว่าจะเพิ่มไฟล์ result.json ลงในชุดไฟล์ zip หรือไม่ โดยมีชื่อของไพพ์ไลน์ที่ทำงาน คำเตือน และพาธของไฟล์ ต้องตั้งค่า output.format เป็น zip หากตั้งเป็น true คู่กับ stl จะส่งคืน 400

`output`

ไม่บังคับ กำหนดไฟล์ที่งาน build จะส่งคืน

Name
format
Type
string
ค่าเริ่มต้น stl
Description
ไฟล์ที่งาน build จะส่งคืน
ค่าที่ใช้ได้:
- stl: model_urls.lamp_stl โคมไฟพร้อมแผ่นฐานเมื่อมี fixture preset และ model_urls.base_stl เมื่อ light_source_preset ไม่ใช่ none
- zip: ไฟล์ zip หนึ่งไฟล์ใน model_urls.bundle_zip ที่มี lamp.stl และ base.stl กับ result.json เมื่อเข้าเงื่อนไข

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

ฟิลด์ result เก็บ ID ของงาน build ใหม่ ดึงข้อมูลงาน หรือ สตรีมงาน จนกว่า status จะเป็น SUCCEEDED จากนั้นดาวน์โหลดไฟล์จาก model_urls

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

Name
400 - Bad Request
Description
คำขอไม่สามารถทำงานได้ ตัวอย่างเช่น:
- input_task_id ขาดหายไปหรือไม่ใช่ ID งานที่ถูกต้อง
- สถานะของงาน prototype ไม่ใช่ SUCCEEDED หากยังทำงานอยู่ ให้รอแล้วลองใหม่ หากล้มเหลวหรือถูกยกเลิก ให้สร้างงาน prototype ใหม่
- งาน prototype สำเร็จแล้วแต่ไม่มีโมเดล 3D สร้างงาน prototype ใหม่
- ฟิลด์ options อยู่นอกช่วงหรือไม่ใช่ค่าที่ใช้ได้
- output.format ไม่ใช่ stl หรือ zip หรือ include_result_json เป็น true โดยไม่มี zip
ข้อความแสดงข้อผิดพลาดจะบอกว่าพบปัญหาใด
Name
401 - Unauthorized
Description
API คีย์ขาดหายไปหรือไม่ถูกต้อง ตรวจสอบส่วนหัว Authorization
Name
402 - Payment Required
Description
หนึ่งในกรณีต่อไปนี้ใช้ได้:
- บัญชีมีเครดิตไม่เพียงพอ
- API คีย์ พื้นที่ทำงาน หรือสมาชิกถึงขีดจำกัดเครดิตแล้ว
- บัญชีอยู่บนแผนฟรี
ตรวจสอบเครดิตและแผนของคุณ แล้วลองใหม่
Name
404 - Not Found
Description
input_task_id ไม่ตรงกับงาน prototype ของ Lamp ใดที่บัญชีของคุณสร้างด้วย API prototype ที่สร้างในเว็บแอปก็จะส่งคืน 404 เช่นกัน ให้ส่ง ID result จากการตอบกลับการสร้าง prototype
Name
429 - Too Many Requests
Description
หนึ่งในขีดจำกัดต่อไปนี้ถูกถึงแล้ว:
- คุณส่งคำขอมากกว่าที่การจำกัดอัตราของคุณอนุญาต รอสักสองสามวินาทีแล้วลองใหม่ ดู การจำกัดอัตรา
- งานของคุณอยู่ในคิวหรือกำลังทำงานมากเกินไป รอให้บางงานเสร็จสิ้นแล้วลองใหม่
- บนแผนไม่จำกัดที่ไม่มีเครดิตเหลือ คุณถึงจำนวนงานที่สามารถทำงานได้โดยไม่ใช้เครดิตแล้ว รอให้งานเสร็จสิ้น หรือเพิ่มเครดิต

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

ดึงข้อมูลงาน Lamp

คืนค่างาน prototype หรือ build โดย path ที่ใช้ต้องตรงกับขั้นตอนของงานนั้น หากส่งคำของาน build ผ่าน /prototype/:id จะได้รับ 404 และในทำนองเดียวกัน หากส่งคำของาน prototype ผ่าน /build/:id ก็จะได้รับ 404 เช่นกัน

สำหรับฟิลด์ต่าง ๆ โปรดดูที่ The Lamp prototype task object และ The Lamp build task object

Request

GET

/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

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

# Build
curl https://api.meshy.ai/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-lamp-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": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-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": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}

พารามิเตอร์

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

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

ออบเจ็กต์งาน prototype หรือ ออบเจ็กต์งาน build ขึ้นอยู่กับขั้นตอนที่ตรงกับ path

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

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

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

ลบงาน Lamp

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

พาธต้องตรงกับขั้นตอน (stage) ของงานนั้น ตัวอย่างเช่น การใช้ DELETE บน /prototype/:id ด้วย ID ของ build task จะคืนค่า 404

Request

DELETE

/openapi/creative-lab/lamp/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/lamp/v1/prototype/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 พร้อม body ที่ว่างเปล่า

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

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

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

สตรีมงาน Lamp

สตรีมการอัปเดตของงาน Lamp ในรูปแบบ Server-Sent Events (SSE) พาธต้องตรงกับขั้นตอนของงาน หากไม่ตรงกัน เช่น ใช้ ID ของ build task ที่ /prototype/:id/stream สตรีมจะส่งอีเวนต์ error หนึ่งรายการพร้อม status_code: 404 แล้วปิดการเชื่อมต่อ

Request

GET

/openapi/creative-lab/lamp/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/lamp/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 following PENDING frame is shortened 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-lamp-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}

พารามิเตอร์

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

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

สตรีมของอ็อบเจ็กต์งาน prototype หรือ build แต่ละอีเวนต์จะมีอ็อบเจ็กต์งานฉบับเต็ม ตามที่ Get a Lamp task ส่งคืน ขณะที่งานยังเป็น PENDING หรือ IN_PROGRESS ฟิลด์เอาต์พุตของงานจะยังว่างอยู่ (null, [], หรือ {}) และ finished_at จะเป็น null

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

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

List Lamp tasks

คืนค่ารายการ Lamp tasks ของคุณในสเตจใดสเตจหนึ่ง ทีละหน้า พาธ (path) จะเป็นตัวกำหนดสเตจ /prototype จะคืนค่าเฉพาะ prototype tasks ส่วน /build จะคืนค่าเฉพาะ build tasks

Request

GET

/openapi/creative-lab/lamp/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-lamp-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": 30,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Path parameters

Name
stage
Type
path
จำเป็น
Description
สเตจที่ต้องการแสดงรายการ prototype หรือ build

Query parameters

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

Returns

อาร์เรย์ของ prototype task objects หรือ build task objects ตามสเตจที่ระบุในพาธ

อ็อบเจกต์ Task ของต้นแบบโคมไฟ (Lamp prototype)

งาน prototype จะสร้างภาพคอนเซปต์สีขาวด้านจากรูปภาพแล้วแปลงเป็นโมเดล 3 มิติ หากต้องการสร้างชิ้นส่วนที่พิมพ์ได้ ให้ส่ง ID ของ task ไปยัง build endpoint ในชื่อ input_task_id

Properties

Example Lamp Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-lamp-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": 30,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Name
id
Type
string
Description
ID ของ task อย่าอิงกับรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของ task ซึ่งเป็น creative-lab-lamp-prototype เสมอ
Name
name
Type
string
Description
name ที่คุณส่งมาตอนสร้าง task หรือ "" ถ้าคุณไม่ได้ส่งมา
Name
status
Type
string
Description
สถานะของ task
ค่าที่เป็นไปได้:
- PENDING: กำลังรอในคิว
- IN_PROGRESS: กำลังสร้างผลลัพธ์
- SUCCEEDED: สถานะสุดท้าย พร้อมผลลัพธ์
- FAILED: สถานะสุดท้าย พร้อมเหตุผลใน task_error
- CANCELED: สถานะสุดท้าย โดยไม่มีผลลัพธ์
Name
progress
Type
integer
Description
เปอร์เซ็นต์ของงานที่เสร็จแล้ว ตั้งแต่ 0 ถึง 100 โดยจะเป็น 0 จนกว่า task จะเริ่ม และเป็น 100 เมื่อสำเร็จ
Name
created_at
Type
timestamp
Description
เวลาที่สร้าง task เป็นหน่วยมิลลิวินาทีแบบ Unix
Name
started_at
Type
timestamp
Description
เวลาที่ worker เริ่มทำ task เป็นหน่วยมิลลิวินาทีแบบ Unix โดยจะเป็น null จนกว่าจะเริ่ม
Name
finished_at
Type
timestamp
Description
เวลาที่ task ถึงสถานะสุดท้าย เป็นหน่วยมิลลิวินาทีแบบ Unix โดยจะเป็น null จนกว่าจะถึง
Name
expires_at
Type
timestamp
Description
เวลาที่ผลลัพธ์ของ task จะหมดอายุ เป็นหน่วยมิลลิวินาทีแบบ Unix ซึ่งคือ 3 วันหลังจาก finished_at หรือ 3 วันหลังจาก created_at จนกว่า task จะเสร็จสิ้น สำหรับบัญชี Enterprise ซึ่งเก็บผลลัพธ์ของ API ไว้ไม่มีกำหนด ค่านี้จะเป็นประมาณ 100 ปีถัดไป ดูที่ Asset retention
Name
preceding_tasks
Type
integer
Description
ตำแหน่งของ task ในคิวขณะที่สถานะเป็น PENDING โดย 1 หมายถึงจะเริ่มเป็นลำดับถัดไป และจะเป็น 0 หลังจาก task ออกจากคิวแล้ว และเป็น 0 เสมอในผลลัพธ์แบบ list
Name
task_error
Type
object
Description
เหตุผลที่ task ล้มเหลว โดยจะเป็น null ยกเว้นเมื่อ status เป็น FAILED ดูที่ ข้อผิดพลาด
Name
consumed_credits
Type
integer
Description
จำนวนเครดิตที่ถูกคิดสำหรับ task นี้ หลังหักเงินคืน (ถ้ามี) คำขอที่ส่งคืนข้อผิดพลาดจะไม่ถูกคิดเครดิต task ที่ล้มเหลวจะมีค่าเป็น 0 เนื่องจาก Meshy จะคืนเครดิตให้ การยกเลิกจะคืนเครดิตให้เฉพาะตอนที่ task ยังอยู่ในสถานะ PENDING เท่านั้น หาก Meshy ไม่สามารถอ่านค่าที่ถูกคิดได้ การตอบกลับแบบ get หรือ stream จะไม่มีฟิลด์นี้ และคำขอแบบ list จะส่งคืน 500 ในกรณีนั้น ให้ลองส่งคำขอใหม่อีกครั้ง
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดโมเดล 3 มิติที่สร้างจากภาพคอนเซปต์ โดยจะเป็น {} จนกว่า task จะสำเร็จ
- Name
  glb
  Type
  string
  Description
  URL สำหรับดาวน์โหลดโมเดลโป๊ะโคมไฟ ในรูปแบบไฟล์ GLB ขั้นตอน build จะแปลงโมเดลนี้เป็นชิ้นส่วนที่พิมพ์ได้
Name
thumbnail_url
Type
string
Description
URL สำหรับดาวน์โหลดภาพตัวอย่างของโมเดล 3 มิติ โดยจะเป็น "" จนกว่า task จะสำเร็จ
Name
image_urls
Type
array of strings
Description
URL สำหรับดาวน์โหลดภาพคอนเซปต์ โดยอาร์เรย์นี้จะมี URL หนึ่งรายการหลังจาก task สำเร็จ และจะว่างเปล่าก่อนหน้านั้น

อ็อบเจ็กต์งาน build ของโคมไฟ (Lamp)

งาน build จะแปลงโมเดล 3D จากงาน prototype ที่สำเร็จแล้วให้กลายเป็นชิ้นส่วนโป๊ะโคมไฟที่พร้อมพิมพ์ Meshy จะเจาะโมเดลให้กลวงและตัดด้านล่างให้เรียบ หากใช้ fixture preset ระบบจะเปิดด้านล่างและเพิ่มแผ่นฐาน (base plate) พร้อมจุดยึด fixture ให้ด้วย

คุณสมบัติ

Example Lamp Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-lamp-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": 6,
  "model_urls": {
    "lamp_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/lamp.stl?Expires=***",
    "base_stl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/base.stl?Expires=***"
  }
}

Name
id
Type
string
Description
ไอดีของงาน อย่าอ้างอิงตามรูปแบบของมัน
Name
type
Type
string
Description
ประเภทของงาน ซึ่งจะเป็น creative-lab-lamp-build เสมอ
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 จะไม่มีฟิลด์นี้ และคำขอแบบรายการจะส่งคืน 500 ในกรณีนั้นให้ลองส่งคำขออีกครั้ง
Name
model_urls
Type
object
Description
URL สำหรับดาวน์โหลดไฟล์ที่พร้อมพิมพ์ คีย์ที่ปรากฏขึ้นอยู่กับ output.format และ options.light_source_preset
- Name
  lamp_stl
  Type
  string
  Description
  URL สำหรับดาวน์โหลด lamp.stl หากใช้ fixture preset ไฟล์นี้จะเป็นโป๊ะโคมไฟแบบเปิดด้านล่างพร้อมแผ่นฐานที่มีรูสำหรับ fixture หากตั้งค่า options.light_source_preset เป็น none ไฟล์นี้จะเป็นโป๊ะโคมไฟแบบปิดสนิทชิ้นเดียว จะปรากฏเมื่อ output.format เป็น stl
- Name
  base_stl
  Type
  string
  Description
  URL สำหรับดาวน์โหลด base.stl ซึ่งเป็นจุดยึดสำหรับ fixture ไฟ จะปรากฏเมื่อ output.format เป็น stl และ options.light_source_preset ไม่ใช่ none
- Name
  bundle_zip
  Type
  string
  Description
  URL สำหรับดาวน์โหลดไฟล์ zip ที่มี lamp.stl และ base.stl กับ result.json เมื่อเข้าเงื่อนไข จะปรากฏเมื่อ output.format เป็น zip ซึ่งในกรณีนี้จะไม่มี lamp_stl และ base_stl