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

สร้างภาพคอนเซปต์สีขาวด้านเดียวจากภาพอ้างอิง และ แปลงเป็นโมเดล 3D โคมไฟแบบกลวง คำตอบที่ได้จะประกอบด้วยทั้งภาพคอนเซปต์ (image_urls) และโมเดล 3D (model_urls.glb พร้อม thumbnail_url) รหัสงาน (task ID) ที่ได้กลับมาคือค่าที่คุณจะส่งไปเป็น 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 สำหรับการทำสไตล์ ค่าที่ใช้ได้มีดังนี้:

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

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

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

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

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

พร็อพเพอร์ตี้ result ของคำตอบจะมี id ของงานสร้างต้นแบบโคมไฟที่สร้างขึ้นใหม่ ให้ทำการ poll ที่เอนด์พอยต์ Get a Task หรือสมัครรับ stream จนกว่างานจะมีสถานะเป็น 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

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

  • 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 Task

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

พารามิเตอร์

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

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

    prototype task ที่สร้างผ่าน webapp จะ ไม่ได้ รับการยอมรับ — เอนด์พอยต์ build จะรับเฉพาะ prototype task ที่สร้างโดย 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 ของตัวประมวลผลโคมไฟ (ชื่อ pipeline, คำเตือน, และเส้นทางไฟล์ผลลัพธ์) ไว้ในชุดไฟล์ด้วย จะถูกละเว้นเมื่อ output.format เป็น stl

output

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

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

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

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

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

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

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

  • Name
    400 - Bad Request
    Description

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

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

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

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

เรียกดูงานโคมไฟ

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

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

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

    ตัวระบุเฉพาะของงานโคมไฟที่ต้องการเรียกดู

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

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

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

ลบงานโคมไฟ

ยกเลิกงานโคมไฟ หากงานยังคงอยู่ในสถานะ PENDING เครดิตที่ใช้ไปในขณะสร้างจะถูกคืน งานที่อยู่ในสถานะ IN_PROGRESS จะถูกยกเลิกโดยไม่มีการคืนเงิน (ผู้ปฏิบัติงานอาจกำลังใช้แหล่งข้อมูลอยู่) งานที่ได้เข้าสู่สถานะสุดท้ายแล้ว (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/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 สำหรับงานที่มีสถานะ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะมีเฉพาะฟิลด์ progress และ status ที่จำเป็นเท่านั้น

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

List Lamp Tasks

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

Path Parameters

  • Name
    stage
    Type
    path
    จำเป็น
    Description

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

Query Parameters

  • Name
    page_num
    Type
    integer
    ค่าเริ่มต้น 1
    Description

    หมายเลขหน้าสำหรับการแบ่งหน้า

  • Name
    page_size
    Type
    integer
    ค่าเริ่มต้น 10
    Description

    จำนวนจำกัดของขนาดหน้า สูงสุดที่อนุญาตคือ 50 รายการ

  • Name
    sort_by
    Type
    string
    ค่าเริ่มต้น -created_at
    Description

    ฟิลด์ที่ใช้ในการจัดเรียง ค่าที่ใช้ได้:

    • +created_at: จัดเรียงตามเวลาที่สร้างจากน้อยไปมาก
    • -created_at: จัดเรียงตามเวลาที่สร้างจากมากไปน้อย

Returns

ส่งคืนรายการแบบแบ่งหน้าของออบเจ็กต์งานสำหรับแต่ละสเตจ — ซึ่งอาจเป็น ออบเจ็กต์งานต้นแบบโคมไฟ เมื่อแสดงรายการ /prototype หรือ ออบเจ็กต์งาน build โคมไฟ เมื่อ แสดงรายการ /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 ใช้ติดตามการสร้างภาพคอนเซ็ปต์สีขาวด้านสไตล์ไลซ์จากภาพถ่ายต้นฉบับ และแปลงเป็นโมเดล 3Dแบบกลวง ผลลัพธ์ของขั้นตอนนี้จะถูกส่งต่อไปยังขั้นตอนการสร้าง ผ่าน input_task_id

Properties

  • 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

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

  • Name
    created_at
    Type
    timestamp
    Description

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

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

    ไทม์สแตมป์ของเวลาที่ task เสร็จสิ้น หน่วยเป็นมิลลิวินาที หาก task ยังไม่เสร็จสิ้น property นี้จะเป็น 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 นี่คือโมเดลที่ขั้นตอนการสร้างจะนำไปประมวลผล

  • Name
    thumbnail_url
    Type
    string
    Description

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

  • Name
    image_urls
    Type
    array of strings
    Description

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

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 ใช้ติดตามเพื่อสร้างโคมไฟที่พร้อมพิมพ์แบบ 3 มิติจาก prototype task ที่สำเร็จแล้ว การ build จะรัน lamp processor บนโมเดล 3 มิติของ prototype เพื่อทำให้กลวง ทำให้ก้นแบนและเปิด และ (เมื่อมีการกำหนด fixture preset) เพิ่มแผ่นฐานและจุดยึด fixture

คุณสมบัติ

  • 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

    ความคืบหน้าของ 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=***"
  }
}