Creative Lab — API โคมไฟ

เปลี่ยน prompt ข้อความหรือภาพถ่ายต้นฉบับให้เป็นโป๊ะโคมไฟที่พิมพ์ 3D ได้ในสอง ขั้นตอน: ต้นแบบ สร้างภาพแนวคิดสีขาวด้านแบบมีสไตล์ จากนั้น บิลด์ เปลี่ยนภาพแนวคิดนั้นให้เป็นโป๊ะโคมไฟ 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

สร้างงานต้นแบบโคมไฟ

สร้างภาพคอนเซปต์สีขาวด้านหนึ่งภาพสำหรับโป๊ะโคมไฟ — ไม่ว่าจะ จาก text prompt (text-to-3D) หรือจากภาพถ่ายอ้างอิง (image-to-3D). ID งานที่ส่งกลับมาคือสิ่งที่คุณส่งเป็น input_task_id ไปยังเอนด์พอยต์ build โปรดดู ออบเจ็กต์งานต้นแบบโคมไฟ สำหรับรูปแบบการตอบกลับ

พารามิเตอร์

ต้องระบุ text หรือ image_url อย่างใดอย่างหนึ่งเท่านั้น การส่งทั้งสองอย่าง หรือไม่ส่งเลย จะส่งกลับ 400

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

    Text prompt ที่อธิบายหัวข้อโป๊ะโคมไฟที่ต้องการ จำเป็นเมื่อไม่ได้ระบุ image_url สูงสุด 800 อักขระ

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

    ภาพถ่ายต้นทางที่ Meshy ใช้เป็นภาพอ้างอิงสำหรับโป๊ะโคมไฟ จำเป็นเมื่อไม่ได้ระบุ text ขณะนี้เรารองรับรูปแบบ .jpg, .jpeg, .png และ .webp

    มีสองวิธีในการระบุรูปภาพ:

    • URL ที่เข้าถึงได้แบบสาธารณะ: URL ที่เข้าถึงได้จากอินเทอร์เน็ตสาธารณะ
    • Data URI: Data URI ของรูปภาพที่เข้ารหัสแบบ base64 ตัวอย่างของ data URI: data:image/jpeg;base64,<your base64-encoded image data>
  • Name
    image_subject
    Type
    string
    ค่าเริ่มต้น character
    Description

    คำใบ้หมวดหมู่หัวข้อสำหรับเส้นทาง image-to-3D ค่าที่ใช้ได้:

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

    ถูกละเว้นในเส้นทาง text-to-3D

  • Name
    name
    Type
    string
    Description

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

ส่งกลับ

คุณสมบัติ result ของการตอบกลับมี id งานของงานต้นแบบโคมไฟที่สร้างใหม่ Poll เอนด์พอยต์ รับงาน หรือสมัครรับ stream จนกว่างานจะถึง SUCCEEDED จากนั้นส่ง ID นั้นไปยัง เอนด์พอยต์ build เป็น input_task_id

โหมดความล้มเหลว

  • Name
    400 - Bad Request
    Description

    คำขอไม่เป็นที่ยอมรับ สาเหตุที่พบบ่อย:

    • พารามิเตอร์ขาดหาย: ต้องระบุ text หรือ image_url อย่างใดอย่างหนึ่งเท่านั้น
    • ระบุทั้งสองอย่าง: การส่งทั้ง text และ image_url จะถูกปฏิเสธ — ทั้งสองอย่างไม่สามารถใช้ร่วมกันได้
    • รูปแบบรูปภาพไม่ถูกต้อง: image_url ที่ระบุไม่ใช่รูปแบบที่รองรับ (.jpg, .jpeg, .png, .webp)
    • ขนาดรูปภาพอยู่นอกช่วง: รูปภาพมีขนาดเล็กเกินไป เกินขนาดไฟล์สูงสุด หรือเกินจำนวนพิกเซลสูงสุด
    • URL เข้าถึงไม่ได้: ไม่สามารถดาวน์โหลด image_url ได้ (404 หรือ timeout)
    • Data URI ไม่ถูกต้อง: สตริง base64 มีรูปแบบไม่ถูกต้อง
    • เนื้อหาถูกตั้งค่าสถานะ: รูปภาพอินพุตถูกตั้งค่าสถานะโดย NSFW หรือ moderation ทรัพย์สินทางปัญญา
    • ข้อความยาวเกินไป: text เกิน 800 อักขระ
    • 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 (image-to-3D): generate a matte-white lampshade concept image
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"
  }'

# Stage 1 (text-to-3D): generate from a text prompt
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 '{
    "text": "a stylized owl perched on a tree branch under moonlight"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
ตัวอย่างต้นแบบ
เริ่มจากภาพถ่ายต้นทาง จากนั้นสร้างภาพต้นแบบที่ใช้โดยขั้นตอน build โคมไฟ
ภาพถ่ายแมวต้นทางที่ใช้เป็นอินพุต Creative Lab Lamp
อินพุตต้นแบบ
เอาต์พุตต้นแบบ Creative Lab Lamp ที่สร้างจากภาพถ่ายต้นทาง
เอาต์พุตต้นแบบ
POST/openapi/creative-lab/lamp/v1/build

สร้างงานบิลด์โคมไฟ

สร้างโป๊ะโคมสุดท้ายที่พิมพ์ 3D ได้จากงานต้นแบบที่สำเร็จแล้ว การบิลด์จะเรียกใช้ไปป์ไลน์ image-to-3D กับภาพคอนเซ็ปต์ของต้นแบบ จากนั้นประมวลผลหลังการสร้างกับเมชผ่านตัวประมวลผลโคมไฟเพื่อทำให้กลวง ทำให้ด้านบนแบน ตัดฐานตามตัวเลือก และ (เมื่อเลือกค่าพรีเซ็ตของฟิกซ์เจอร์) สร้างดิสก์ฐานแยกต่างหากสำหรับแหล่งกำเนิดแสง ดู ออบเจ็กต์งานบิลด์โคมไฟ สำหรับ รูปแบบการตอบกลับ

พารามิเตอร์

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

    ID งานของงานต้นแบบที่สร้างผ่านเอนด์พอยต์ OpenAPI เดียวกันนี้ ต้นแบบต้องถูกสร้างด้วย API คีย์เดียวกัน ต้องไปถึง SUCCEEDED แล้ว และต้องสร้างภาพตัวเลือกหนึ่งภาพพอดี

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

  • Name
    name
    Type
    string
    Description

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

options

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

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

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

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

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

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

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

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

    ค่าพรีเซ็ตฟิกซ์เจอร์แหล่งกำเนิดแสงที่กำหนดว่าจะสร้างดิสก์ฐานควบคู่กับโป๊ะโคมหรือไม่ (และแบบใด) ค่าที่ใช้ได้:

    • bambu_mh001_60mm (ค่าเริ่มต้น) — สร้างดิสก์ฐาน 60 มม. ที่มีขนาดเหมาะกับฟิกซ์เจอร์แหล่งกำเนิดแสงที่เข้ากันได้ ผลลัพธ์มี model_urls.base_stl
    • none — ไม่มีฟิกซ์เจอร์ ไม่มีดิสก์ฐาน model_urls.base_stl จะถูกละไว้
  • Name
    fixture_offset_x_mm
    Type
    number
    ค่าเริ่มต้น 0
    Description

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

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

    ออฟเซ็ตแนวตั้งตามแกน Z ของช่องตัดฟิกซ์เจอร์เมื่อเทียบกับด้านล่างของโป๊ะโคม เป็นมิลลิเมตร ช่วง: [-80, 80]

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

    การหมุนรอบแกน X ที่ใช้กับเมชที่นำเข้าก่อนการประมวลผล เป็นองศา ช่วง: [-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 ของตัวประมวลผลโคมไฟ (ซึ่งมีเมตริกเมชที่วัดได้ + ชุดตัวเลือกที่ถูก resolve แล้ว) ไว้ภายในบันเดิล จะถูกละเว้นเมื่อ output.format เป็น stl

output

ตัวเลือก wire-format ที่ไม่บังคับ ค่าเริ่มต้นคือ stl

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

    บันเดิลอาร์ติแฟกต์ที่การบิลด์ส่งกลับ ค่าที่ใช้ได้:

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

ส่งคืน

พร็อพเพอร์ตี result ของการตอบกลับมี id งานของงานบิลด์โคมไฟที่สร้างขึ้นใหม่ โพลเอนด์พอยต์ รับงาน หรือสมัครรับ สตรีม จนกว่างานจะไปถึง SUCCEEDED จากนั้นดาวน์โหลดอาร์ติแฟกต์จาก model_urls

กรณีความล้มเหลว

  • Name
    400 - Bad Request
    Description

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

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

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

    งานต้นแบบที่อ้างอิงไม่มีอยู่ เป็นของผู้ใช้คนอื่น หรือถูกสร้างผ่านเว็บแอป (เฉพาะงานต้นแบบใน API-mode เท่านั้นที่เชื่อมต่อไปยัง 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 example
The build task turns the selected prototype image into a printable lampshade model.
Creative Lab Lamp build model preview
Build model preview
GET/openapi/creative-lab/lamp/v1/(prototype|build)/:id

ดึงข้อมูลงานโคมไฟ

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

ดู ออบเจ็กต์งานต้นแบบโคมไฟ และ ออบเจ็กต์งานบิลด์โคมไฟ สำหรับ รูปแบบการตอบกลับ

พารามิเตอร์

  • 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": 6,
  "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": 30,
  "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

สตรีมงานโคมไฟ

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

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

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

ส่งคืน

ส่งคืนสตรีมของออบเจ็กต์งาน ต้นแบบโคมไฟ หรือ การสร้างโคมไฟ ในรูปแบบ 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": 30,
  "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 ส่งคืนงานสร้าง งานจากขั้นตอนอื่นจะไม่ถูกรวมอยู่ใน การตอบกลับใด ๆ

พารามิเตอร์พาธ

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

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

พารามิเตอร์คิวรี

  • 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: จัดเรียงตามเวลาที่สร้างจากมากไปน้อย

ผลลัพธ์ที่ส่งคืน

ส่งคืนรายการแบบแบ่งหน้าของอ็อบเจกต์งานตามขั้นตอน — ได้แก่ อ็อบเจกต์งานต้นแบบโคมไฟ เมื่อแสดงรายการ /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": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

ออบเจ็กต์งานต้นแบบโคมไฟ

ออบเจ็กต์งานต้นแบบโคมไฟคือหน่วยงานที่ Meshy ติดตามเพื่อ สร้าง ภาพคอนเซ็ปต์ สีขาวด้านแบบมีสไตล์จาก prompt ข้อความ หรือภาพถ่ายต้นฉบับ ผลลัพธ์ของขั้นตอนนี้จะถูกเชื่อมต่อไปยัง ขั้นตอนการสร้าง ผ่าน input_task_id

คุณสมบัติ

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    ประเภทของงาน ค่าคือ creative-lab-lamp-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 PM 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 จะส่งคืนตัวเลือกเพียงหนึ่งรายการเสมอ ฟิลด์นี้เป็นอาร์เรย์เพื่อให้การปรับปรุงในอนาคตสามารถแสดงตัวเลือกหลายรายการได้โดยไม่ทำให้เกิดการเปลี่ยนแปลงที่ไม่เข้ากัน

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": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

ออบเจ็กต์งานสร้างโคมไฟ

ออบเจ็กต์งานสร้างโคมไฟคือหน่วยงานที่ Meshy ติดตามเพื่อ สร้างโป๊ะโคมไฟขั้นสุดท้ายที่พร้อมสำหรับการพิมพ์ 3D จากงานต้นแบบที่ SUCCEEDED การสร้างจะรันไปป์ไลน์แบบร่างภาพเป็น 3D + เท็กซ์เจอร์บนภาพคอนเซปต์ของต้นแบบ จากนั้นจึงประมวลผลเมชภายหลังผ่านตัวประมวลผลโคมไฟเพื่อ ทำให้กลวง ทำให้แบน และ (ไม่บังคับ) ตัดฐานสำหรับอุปกรณ์ยึด

คุณสมบัติ

  • Name
    id
    Type
    string
    Description

    ตัวระบุเฉพาะสำหรับงาน

  • Name
    type
    Type
    string
    Description

    ประเภทของงาน ค่าเป็น creative-lab-lamp-build

  • Name
    name
    Type
    string
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • 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

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

  • Name
    model_urls
    Type
    object
    Description

    URL ที่ดาวน์โหลดได้สำหรับอาร์ติแฟกต์ที่สร้างขึ้น โดยใช้ชื่ออาร์ติแฟกต์เป็นคีย์ ชุดของคีย์ขึ้นอยู่กับ output.format และ options.light_source_preset:

    • Name
      lamp_stl
      Type
      string
      Description

      URL ที่ดาวน์โหลดได้สำหรับโป๊ะโคม lamp.stl มีอยู่เมื่อ output.format เป็น stl (ค่าเริ่มต้น)

    • Name
      base_stl
      Type
      string
      Description

      URL ที่ดาวน์โหลดได้สำหรับฐานยึด base.stl มีอยู่เมื่อ output.format เป็น stl และ options.light_source_preset ไม่ใช่ none จะถูกละไว้เมื่อพรีเซ็ตอุปกรณ์ยึดเป็น none

    • Name
      bundle_zip
      Type
      string
      Description

      URL ที่ดาวน์โหลดได้สำหรับบันเดิล zip ของทุกอาร์ติแฟกต์ที่โปรเซสเซอร์ส่งออก (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": 30,
  "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=***"
  }
}