Creative Lab — Lamp API

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

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

สร้าง Lamp Prototype Task

สร้างภาพคอนเซ็ปต์สีขาวด้านเดียวจากภาพถ่ายอ้างอิง แล้วแปลงเป็นโมเดล 3D โครงโป่งไฟแบบกลวง คำตอบจะมีทั้งภาพคอนเซ็ปต์ (image_urls) และโมเดล 3D (model_urls.glb พร้อม thumbnail_url) ID ของ task ที่ได้กลับมาคือสิ่งที่คุณจะส่งเป็น input_task_id ไปยังเอนด์พอยต์ build โปรดดู The Lamp Prototype Task Object สำหรับรูปแบบของการตอบกลับ

พารามิเตอร์

  • 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
    image_subject
    Type
    string
    ค่าเริ่มต้น character
    Description

    คำใบ้ประเภทหัวเรื่องที่ใช้เลือก prompt สำหรับ stylization ค่าที่ใช้ได้:

    • character (ค่าเริ่มต้น) — หัวเรื่องเป็นตัวละคร/วัตถุเดี่ยว (ฟิกเกอร์, สัตว์, มาสคอต ฯลฯ)
    • landscape — หัวเรื่องเป็นฉาก/ทิวทัศน์กลางแจ้ง (ภูเขา, ทิวทัศน์เมือง, ป่า ฯลฯ)
  • Name
    name
    Type
    string
    Description

    ชื่อ task ที่ไม่บังคับสำหรับการแสดงผล สูงสุด 100 ตัวอักษร

  • Name
    remove_background
    Type
    boolean
    ค่าเริ่มต้น false
    Description

    เมื่อตั้งค่าเป็น true ภาพต้นแบบจะถูกส่งกลับมาเป็นไฟล์ PNG แบบ RGBA โปร่งใสโดยลบพื้นหลังออก เพื่อให้คุณสามารถนำหัวเรื่องไปประกอบกับพื้นหลังใดก็ได้

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

พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของ task ต้นแบบโป่งไฟที่สร้างขึ้นใหม่ ให้ทำการ poll ที่เอนด์พอยต์ Get a Task หรือติดตามผ่าน stream จนกว่า task จะมีสถานะ SUCCEEDED จากนั้นส่ง ID นั้นไปยัง 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 หรือทรัพย์สินทางปัญญา
    • image_subject ไม่ถูกต้อง: ไม่ใช่ character หรือ landscape
  • Name
    401 - Unauthorized
    Description

    การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ

  • Name
    402 - Payment Required
    Description

    เครดิตไม่เพียงพอที่จะดำเนินการ task นี้

  • Name
    429 - Too Many Requests
    Description

    คุณดำเนินการเกินการจำกัดอัตราที่กำหนดไว้

Request

POST
/openapi/creative-lab/lamp/v1/prototype
# Stage 1: concept image + hollow 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
Start with a source photo; the prototype returns the concept image and a hollow 3D model that the build stage processes.
Source cat photo used as the Creative Lab Lamp input
Prototype input
Creative Lab Lamp prototype output generated from the source photo
Prototype output
POST/openapi/creative-lab/lamp/v1/build

สร้างงาน Lamp Build

สร้างชิ้นส่วนที่พร้อมพิมพ์ 3 มิติขั้นสุดท้ายจากงานต้นแบบ (prototype task) ที่สำเร็จแล้ว การ build จะรัน lamp processor บนโมเดล 3 มิติของต้นแบบ โดยจะปรับขนาดโมเดล ให้เป็น diameter_mm ทำให้ด้านล่างแบนราบตาม cut_amount_percent เจาะให้กลวงจนได้ thickness_mm เปิดด้านล่าง และ — เมื่อเลือกใช้ fixture preset — จะเพิ่มแผ่นฐานที่มีรูสำหรับ fixture และจุดยึด แยกต่างหากสำหรับแหล่งกำเนิดแสง ดูรายละเอียดรูปแบบการตอบกลับได้ที่ The Lamp Build Task Object

พารามิเตอร์

  • Name
    input_task_id
    Type
    string
    จำเป็น
    Description

    รหัสงาน (task ID) ของงานต้นแบบที่สร้างผ่านเอนด์พอยต์ OpenAPI เดียวกันนี้ ต้นแบบจะต้องถูกสร้างด้วย API คีย์เดียวกัน ต้องมีสถานะถึง SUCCEEDED และต้องสร้างโมเดล 3 มิติสำเร็จแล้ว

    งานต้นแบบที่สร้างผ่านเว็บแอป จะไม่ได้รับการยอมรับ — เอนด์พอยต์ build จะยอมรับเฉพาะงานต้นแบบที่สร้างจาก POST /openapi/creative-lab/lamp/v1/prototype เท่านั้น และจะปฏิเสธแหล่งที่มาอื่นทั้งหมดด้วยรหัส 404

  • Name
    name
    Type
    string
    Description

    ชื่องาน (ไม่บังคับ) สำหรับใช้แสดงผล สูงสุด 100 ตัวอักษร

options

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

  • Name
    diameter_mm
    Type
    number
    ค่าเริ่มต้น 150
    Description

    ขนาดสูงสุดเป้าหมายของกล่องขอบเขตของโป๊ะโคมไฟ หน่วยเป็นมิลลิเมตร เมชจะถูกปรับขนาดอย่างสม่ำเสมอให้พอดี ช่วง: [50, 400]

  • Name
    thickness_mm
    Type
    number
    ค่าเริ่มต้น 1
    Description

    ความหนาผนังของโป๊ะโคมไฟที่กลวง หน่วยเป็นมิลลิเมตร ช่วง: (0, 10]

  • Name
    cut_amount_percent
    Type
    number
    ค่าเริ่มต้น 1
    Description

    เปอร์เซ็นต์ของความสูงโมเดลที่จะถูกตัดให้แบนที่ด้านล่าง เพื่อให้โป๊ะโคมไฟวางบนแท่นพิมพ์ได้และมีช่องเปิดสำหรับ fixture ช่วง: [1, 100]

  • Name
    light_source_preset
    Type
    string
    ค่าเริ่มต้น bambu_mh001_60mm
    Description

    พรีเซ็ต fixture สำหรับแหล่งกำเนิดแสง ซึ่งกำหนดวิธีสร้างส่วนด้านล่าง ค่าที่ใช้ได้:

    • bambu_mh001_60mm (ค่าเริ่มต้น) — โป๊ะโคมไฟแบบเปิดด้านล่างพร้อมแผ่นฐานที่มีรู fixture ขนาด 60 มม. ทั้งสองอย่างอยู่ใน model_urls.lamp_stl และจุดยึด fixture อยู่ใน model_urls.base_stl
    • none — โป๊ะโคมไฟแบบปิดสนิทชิ้นเดียวอยู่ใน model_urls.lamp_stl; ไม่มี model_urls.base_stl
  • Name
    fixture_offset_x_mm
    Type
    number
    ค่าเริ่มต้น 0
    Description

    ระยะเยื้องตามแกน X ของรู fixture บนแผ่นฐาน เทียบกับจุดกึ่งกลางของโป๊ะโคมไฟ หน่วยเป็นมิลลิเมตร มีความหมายก็ต่อเมื่อ light_source_preset ≠ none ช่วง: [-80, 80]

  • Name
    fixture_offset_z_mm
    Type
    number
    ค่าเริ่มต้น 0
    Description

    ระยะเยื้องตามแกน Z (ความลึก) ของรู fixture บนแผ่นฐาน เทียบกับจุดกึ่งกลางของโป๊ะโคมไฟ หน่วยเป็นมิลลิเมตร มีความหมายก็ต่อเมื่อ light_source_preset ≠ none ช่วง: [-80, 80]

  • Name
    rotate_x_deg
    Type
    number
    ค่าเริ่มต้น 0
    Description

    การหมุนรอบแกน X ที่ใช้กับโมเดลก่อนประมวลผล หน่วยเป็นองศา การหมุนทั้งสามแกนจะถูกใช้ในรูปแบบมุมออยเลอร์ XYZ รอบจุดกึ่งกลางของโมเดล ช่วง: [-360, 360]

  • Name
    rotate_y_deg
    Type
    number
    ค่าเริ่มต้น 0
    Description

    การหมุนรอบแกน Y ที่ใช้กับเมชที่นำเข้ามาก่อนประมวลผล หน่วยเป็นองศา ช่วง: [-360, 360]

  • Name
    rotate_z_deg
    Type
    number
    ค่าเริ่มต้น 0
    Description

    การหมุนรอบแกน Z ที่ใช้กับเมชที่นำเข้ามาก่อนประมวลผล หน่วยเป็นองศา ช่วง: [-360, 360]

  • Name
    include_result_json
    Type
    boolean
    ค่าเริ่มต้น false
    Description

    เมื่อตั้งค่าเป็น true และ output.format เป็น zip จะรวมไฟล์ result.json ของ lamp processor (ชื่อ pipeline, คำเตือน และเส้นทางของไฟล์ผลลัพธ์) ไว้ในชุดไฟล์ด้วย จะถูกละเว้นเมื่อ output.format เป็น stl

output

ตัวเลือกรูปแบบการส่งข้อมูล (ไม่บังคับ) ค่าเริ่มต้นคือ stl

  • Name
    format
    Type
    string
    ค่าเริ่มต้น stl
    Description

    ชุดไฟล์ผลลัพธ์ที่ส่งกลับโดยการ build ค่าที่ใช้ได้:

    • stl (ค่าเริ่มต้น) — ส่งกลับ model_urls.lamp_stl (โป๊ะโคมไฟ พร้อมกับแผ่นฐานเมื่อมีการตั้งค่า fixture preset) และ model_urls.base_stl เมื่อ light_source_preset ≠ none
    • zip — รวมไฟล์ผลลัพธ์ทั้งหมดที่ processor สร้างขึ้น (lamp.stl, base.stl ที่เป็นตัวเลือก, result.json ที่เป็นตัวเลือก) เป็นไฟล์ zip เดียว และส่งกลับภายใต้ model_urls.bundle_zip

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

พร็อพเพอร์ตี้ result ของการตอบกลับจะมี id ของงาน lamp build ที่สร้างขึ้นใหม่ ให้ polling ที่เอนด์พอยต์ Get a Task หรือติดตามผ่าน stream จนกว่างานจะมีสถานะถึง SUCCEEDED จากนั้นดาวน์โหลดไฟล์ผลลัพธ์จาก model_urls

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

  • Name
    400 - Bad Request
    Description

    คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:

    • ขาดพารามิเตอร์: จำเป็นต้องมี input_task_id
    • UUID ไม่ถูกต้อง: input_task_id ไม่ใช่ UUID ที่ถูกต้อง
    • งานต้นทางยังไม่สำเร็จ: งานต้นแบบที่อ้างอิงยังไม่มีสถานะถึง SUCCEEDED
    • ไม่มีโมเดล: งานต้นแบบสำเร็จแล้วแต่ไม่ได้สร้างโมเดล 3 มิติ
    • ตัวเลือกอยู่นอกช่วงที่กำหนด: หนึ่งในฟิลด์ของ options มีค่าอยู่นอกช่วงหรือชุดค่าที่อนุญาต
  • Name
    401 - Unauthorized
    Description

    การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API คีย์ของคุณ

  • Name
    402 - Payment Required
    Description

    เครดิตไม่เพียงพอสำหรับการทำงานนี้

  • Name
    404 - Not Found
    Description

    งานต้นแบบที่อ้างอิงไม่มีอยู่จริง เป็นของผู้ใช้คนอื่น หรือถูกสร้างผ่านเว็บแอป (เฉพาะงานต้นแบบในโหมด API เท่านั้นที่สามารถเชื่อมต่อไปยัง build ได้)

  • Name
    429 - Too Many Requests
    Description

    คุณใช้งานเกินการจำกัดอัตราที่กำหนดไว้

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 จะเปลี่ยนโมเดล 3 มิติของต้นแบบให้เป็นชิ้นส่วนโป๊ะโคมไฟที่พร้อมพิมพ์
Creative Lab Lamp build model preview
Build model preview
GET/openapi/creative-lab/lamp/v1/(prototype|build)/:id

ดึงข้อมูล Lamp Task

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

โปรดดู The Lamp Prototype Task Object และ The Lamp Build Task Object สำหรับ รูปแบบของ response

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

    ตัวระบุเฉพาะสำหรับ lamp task ที่ต้องการดึงข้อมูล

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

Response จะประกอบด้วยอ็อบเจ็กต์ lamp task โดยรูปแบบจะขึ้นอยู่กับว่า stage ใดถูกร้องขอ

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=***"
  }
}
DELETE/openapi/creative-lab/lamp/v1/(prototype|build)/:id

Delete a Lamp Task

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

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

Path Parameters

  • Name
    id
    Type
    path
    Description

    รหัสเฉพาะของงานโคมไฟที่ต้องการยกเลิก

Returns

คืนค่า 204 No Content เมื่อสำเร็จ โดยไม่มีเนื้อหาใด ๆ

Failure Modes

  • Name
    400 - Bad Request
    Description

    งานนี้อยู่ในสถานะสุดท้ายแล้วและไม่สามารถยกเลิกได้

  • Name
    404 - Not Found
    Description

    ไม่พบงานนี้ งานเป็นของผู้ใช้คนอื่น หรือขั้นตอน (stage) ของงานไม่ตรงกับ URL path

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).
GET/openapi/creative-lab/lamp/v1/(prototype|build)/:id/stream

สตรีมงาน Lamp

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

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

    ตัวระบุที่ไม่ซ้ำกันของงานโคมไฟที่ต้องการสตรีม

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

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

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 PENDING frame below is abbreviated 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=***"
  }
}
GET/openapi/creative-lab/lamp/v1/(prototype|build)

แสดงรายการงานโคมไฟ

ดึงรายการงานโคมไฟของคุณแบบแบ่งหน้าสำหรับสเตจเดียว พาธ 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: เรียงตามเวลาที่สร้างจากมากไปน้อย

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

คืนค่ารายการแบบแบ่งหน้าของออบเจกต์งานเฉพาะสเตจ — ไม่ว่าจะเป็น ออบเจกต์งานโปรโตไทป์โคมไฟ เมื่อแสดงรายการ /prototype หรือ ออบเจกต์งานบิลด์โคมไฟ เมื่อ แสดงรายการ /build

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

The Lamp Prototype Task Object

Lamp Prototype Task object เป็นหน่วยงานที่ Meshy ใช้ติดตามเพื่อสร้าง ภาพคอนเซปต์ สีขาวด้านสไตล์ไลซ์ (stylized matte-white) จากภาพต้นฉบับ และแปลงเป็น โมเดล 3D แบบกลวง ผลลัพธ์ของขั้นตอนนี้จะถูกส่งต่อไปยังขั้นตอนการสร้าง (build stage) ผ่าน input_task_id

คุณสมบัติ

  • Name
    id
    Type
    string
    Description

    ตัวระบุเฉพาะสำหรับ task แม้ว่าเราจะใช้ k-sortable UUID สำหรับ task id ในรายละเอียดการทำงานจริง แต่คุณ ไม่ควร ตั้งสมมติฐานใด ๆ เกี่ยวกับรูปแบบของ id

  • Name
    type
    Type
    string
    Description

    ประเภทของ task ค่านี้คือ creative-lab-lamp-prototype

  • Name
    name
    Type
    string
    Description

    ชื่อของ task ที่กำหนดไว้ตอนสร้าง task เป็นสตริงว่างหากไม่ได้ระบุชื่อไว้

  • Name
    status
    Type
    string
    Description

    สถานะของ task ค่าที่เป็นไปได้คือค่าใดค่าหนึ่งจาก PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED

  • Name
    progress
    Type
    integer
    Description

    ความคืบหน้าของ task หากยังไม่ได้เริ่ม task คุณสมบัตินี้จะเป็น 0 เมื่อ task สำเร็จแล้ว ค่านี้จะกลายเป็น 100

  • Name
    created_at
    Type
    timestamp
    Description

    ไทม์สแตมป์ของเวลาที่สร้าง task หน่วยเป็นมิลลิวินาที

    ไทม์สแตมป์แสดงจำนวนมิลลิวินาทีที่ผ่านไปนับตั้งแต่วันที่ 1 มกราคม 1970 UTC ตามมาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 น. GMT จะแสดงเป็น 1693569600000 สิ่งนี้ใช้กับ ไทม์สแตมป์ ทั้งหมด ใน Meshy API

  • Name
    started_at
    Type
    timestamp
    Description

    ไทม์สแตมป์ของเวลาที่เริ่ม task หน่วยเป็นมิลลิวินาที หากยังไม่ได้เริ่ม task คุณสมบัตินี้จะเป็น 0

  • Name
    finished_at
    Type
    timestamp
    Description

    ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น หน่วยเป็นมิลลิวินาที หากยังไม่เสร็จสิ้น คุณสมบัตินี้จะเป็น 0

  • Name
    expires_at
    Type
    timestamp
    Description

    ไทม์สแตมป์ของเวลาที่ผลลัพธ์ของ task จะหมดอายุ หน่วยเป็นมิลลิวินาที

  • Name
    preceding_tasks
    Type
    integer
    Description

    จำนวนของ task ที่อยู่ก่อนหน้า

    ค่าของฟิลด์นี้จะมีความหมายก็ต่อเมื่อสถานะของ task เป็น PENDING

  • Name
    task_error
    Type
    object
    Description

    รายละเอียดข้อผิดพลาดสำหรับ task ที่ล้มเหลว ดู ข้อผิดพลาด สำหรับข้อมูลอ้างอิงฉบับเต็มของออบเจ็กต์ task_error

  • Name
    consumed_credits
    Type
    integer
    Description

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

  • Name
    model_urls
    Type
    object
    Description

    URL สำหรับดาวน์โหลดโมเดล 3D ที่สร้างจากภาพคอนเซปต์ จะปรากฏเมื่อ task สำเร็จแล้ว; เป็น {} ก่อนหน้านั้น

    • Name
      glb
      Type
      string
      Description

      URL สำหรับดาวน์โหลดโมเดลโคมไฟแบบกลวงสีขาวด้านในรูปแบบ GLB นี่คือโมเดลที่ขั้นตอนการสร้าง (build stage) จะนำไปประมวลผลต่อ

  • Name
    thumbnail_url
    Type
    string
    Description

    URL สำหรับดาวน์โหลดภาพตัวอย่างที่เรนเดอร์ของโมเดล 3D เป็นสตริงว่างจนกว่า task จะสำเร็จ

  • Name
    image_urls
    Type
    array of strings
    Description

    URL สำหรับดาวน์โหลดตัวเลือกภาพคอนเซปต์ที่สร้างขึ้นโดย prototype task นี้ ปัจจุบัน API จะคืนค่าตัวเลือกเดียวเสมอ; ฟิลด์นี้เป็นอาร์เรย์เพื่อให้เวอร์ชันในอนาคตสามารถแสดงตัวเลือกหลายรายการได้โดยไม่ทำให้เกิด breaking change

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

The Lamp Build Task Object

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

Properties

  • Name
    id
    Type
    string
    Description

    ตัวระบุที่ไม่ซ้ำกันสำหรับ task

  • Name
    type
    Type
    string
    Description

    ประเภทของ task ค่านี้คือ creative-lab-lamp-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 และ options.light_source_preset:

    • Name
      lamp_stl
      Type
      string
      Description

      URL สำหรับดาวน์โหลด lamp.stl: โคมไฟที่เปิดส่วนล่างพร้อมกับแผ่นฐานที่มีรูสำหรับ 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 จะถูกละเว้นเมื่อ fixture preset เป็น none

    • Name
      bundle_zip
      Type
      string
      Description

      URL สำหรับดาวน์โหลดไฟล์ zip ที่รวมผลงานทั้งหมดที่ processor สร้างขึ้น (lamp.stl, base.stl ที่เป็นตัวเลือก และ — เมื่อ options.include_result_json เป็น true — result.json) จะปรากฏเมื่อ output.format เป็น zip เมื่อมี bundle_zip จะไม่มี lamp_stl / base_stl

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