API รูปภาพเป็น 3D

API รูปภาพเป็น 3D เป็นฟีเจอร์ที่ช่วยให้คุณสามารถผสานรวมความสามารถรูปภาพเป็น 3D ของ Meshy เข้ากับแอปพลิเคชันของคุณเองได้ ในส่วนนี้ คุณจะพบข้อมูลทั้งหมด ที่จำเป็นสำหรับการเริ่มต้นใช้งาน API นี้

POST/openapi/v1/image-to-3d

สร้างงาน Image to 3D

เอนด์พอยต์นี้ช่วยให้คุณสามารถสร้างงานรูปภาพเป็น 3D ใหม่ได้ ดูข้อมูลเพิ่มเติมได้ที่ The Image to 3D Task Object เพื่อดูว่าพร็อพเพอร์ตี้ใดบ้างที่รวมอยู่ในอ็อบเจ็กต์งานรูปภาพเป็น 3D

พารามิเตอร์

จำเป็นต้องระบุเพียงหนึ่งใน input_task_id หรือ image_url เท่านั้น หากระบุทั้งสองอย่าง input_task_id จะมีความสำคัญเหนือกว่า

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

    ID ของงานสร้างรูปภาพที่เสร็จสมบูรณ์แล้ว ซึ่งเอาต์พุตของงานนั้นจะถูกใช้เป็นรูปภาพอินพุต งานนี้ต้องเป็นหนึ่งในงานต่อไปนี้: ข้อความเป็นรูปภาพ หรือ รูปภาพเป็นรูปภาพ นอกจากนี้ ต้องเป็นงานที่รันผ่าน API มีสถานะเป็น SUCCEEDED และสร้างรูปภาพออกมาเพียงหนึ่งภาพเท่านั้น

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

    ระบุรูปภาพให้ Meshy ใช้ในการสร้างโมเดล ปัจจุบันรองรับรูปแบบไฟล์ .jpg, .jpeg และ .png

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

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

    ระบุประเภทของการสร้างเมช 3D

    ค่าที่ใช้ได้:

    • standard: การสร้างเมช 3D แบบละเอียดสูงตามปกติ
    • smart-topology: เลือกโมเดล Smart Topology ด้วย ai_model (meshy-t2)
    • lowpoly (เลิกใช้): สร้างเมชแบบโลว์โพลีที่ปรับให้เหมาะสมสำหรับโพลิกอนที่สะอาดกว่า เราแนะนำให้ใช้ smart-topology แทน

    เมื่อเลือก smart-topology แล้ว topology, should_remesh และ save_pre_remeshed_model จะถูกละเว้น

    เมื่อเลือก lowpoly แล้ว ai_model, topology, target_polycount, should_remesh และ save_pre_remeshed_model จะถูกละเว้น

  • Name
    ai_model
    Type
    string
    ค่าเริ่มต้น latest
    Description

    ID ของโมเดลที่จะใช้ ค่าที่ใช้ได้ขึ้นอยู่กับ model_type

    การสร้างแบบมาตรฐาน (model_type: standard):

    • meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
    • meshy-7 (เลิกใช้): ใช้ meshy-7.1 แทน

    การสร้างแบบ Smart Topology (model_type: smart-topology):

    • meshy-t2 (ค่าเริ่มต้น): โมเดล Smart Topology — topology ที่สะอาดกว่า มีการแยกชิ้นส่วนตามธรรมชาติ เอาต์พุตเป็นสามเหลี่ยม และจำนวนหน้าที่คุณสามารถกำหนดได้ด้วย target_polycount
  • Name
    geometry_resolution
    Type
    string
    ค่าเริ่มต้น standard
    Description

    ขั้นตอนการสร้างจีออเมทรี 2k จะรัน Ultra pass ที่ 2048³ ส่วน 4k จะรันที่ 4096³ เพื่อ รายละเอียดพื้นผิวที่ดีที่สุด

    ค่าที่ใช้ได้: standard, 2k, 4k

    ต้องใช้ meshy-7.1 หรือ latest

  • Name
    ultra_mode
    Type
    boolean
    ⚠ เลิกใช้แล้ว
    ค่าเริ่มต้น false
    Description

    ใช้ geometry_resolution แทน ultra_mode: true เทียบเท่ากับ geometry_resolution: "2k"

  • Name
    should_texture
    Type
    boolean
    ค่าเริ่มต้น true
    Description

    กำหนดว่าจะสร้างเท็กซ์เจอร์หรือไม่ การตั้งค่าเป็น false จะข้ามขั้นตอนเท็กซ์เจอร์ ทำให้ได้เมชที่ไม่มีเท็กซ์เจอร์

ใช้เฉพาะเมื่อ should_texture = true
  • Name
    enable_pbr
    Type
    boolean
    ค่าเริ่มต้น false
    Description

    สร้าง PBR แมป (metallic, roughness, normal) นอกเหนือจากสีพื้นฐาน นอกจากนี้จะรวม emission map ด้วยเมื่อ ai_model เป็น meshy-6 ยกเว้นที่ texture_resolution: 8k meshy-6-lite, meshy-7.1 และ latest ไม่สร้าง emission map

  • Name
    texture_resolution
    Type
    string
    ค่าเริ่มต้น 2k
    Description

    ความละเอียดเท็กซ์เจอร์สีพื้นฐาน หนึ่งใน 2k (2048×2048), 4k (4096×4096) หรือ 8k (8192×8192) ความละเอียดที่สูงกว่าจะจับรายละเอียดพื้นผิวได้มากขึ้น

    4k และ 8k ไม่สามารถใช้ได้กับ ai_model meshy-6-lite ที่ 8k จะไม่มีการสร้าง emission map

  • Name
    hd_texture
    Type
    boolean
    ⚠ เลิกใช้แล้ว
    ค่าเริ่มต้น false
    Description

    ใช้ texture_resolution แทน — เทียบเท่ากับ texture_resolution: "4k" เมื่อตั้งค่าทั้งสองอย่าง texture_resolution จะมีความสำคัญเหนือกว่า

  • Name
    texture_prompt
    Type
    string
    Description

    ระบุ prompt ข้อความเพื่อกำหนดทิศทางกระบวนการสร้างเท็กซ์เจอร์ สูงสุด 800 ตัวอักษร

  • Name
    texture_image_url
    Type
    string
    Description

    ระบุรูปภาพ 2 มิติเพื่อกำหนดทิศทางกระบวนการสร้างเท็กซ์เจอร์ ปัจจุบันรองรับรูปแบบไฟล์ .jpg, .jpeg และ .png

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

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

    การสร้างเท็กซ์เจอร์จากรูปภาพอาจทำงานได้ไม่เหมาะสมนัก หากมีความแตกต่างของจีออเมทรีอย่างมากระหว่างชิ้นงานต้นฉบับกับรูปภาพที่อัปโหลด สามารถใช้ได้เพียงหนึ่งใน texture_image_url หรือ texture_prompt เท่านั้นเพื่อกำหนดทิศทางกระบวนการสร้างเท็กซ์เจอร์ หากระบุพารามิเตอร์ทั้งสองอย่าง texture_prompt จะถูกใช้ในการสร้างเท็กซ์เจอร์ให้โมเดลโดยค่าเริ่มต้น การสร้างเท็กซ์เจอร์ไม่ว่าจะผ่านข้อความหรือรูปภาพจะมีค่าใช้จ่าย 10 เครดิตต่องาน

  • Name
    should_remesh
    Type
    boolean
    ค่าเริ่มต้น false (Meshy 6 and Meshy 7 models), true (others)
    Description

    ควบคุมว่าจะเปิดใช้งานขั้นตอนรีเมชหรือไม่ สำหรับโมเดลที่มีคุณภาพสูงสุด เราแนะนำให้ตั้งค่า should_remesh เป็น false

ใช้เฉพาะเมื่อ should_remesh = true
  • Name
    topology
    Type
    string
    ค่าเริ่มต้น triangle
    Description

    ระบุ topology ของโมเดลที่สร้างขึ้น

    ค่าที่ใช้ได้:

    • quad: สร้างเมชที่มีรูปหลายเหลี่ยม 4 ด้านเป็นหลัก
    • triangle: สร้างเมชสามเหลี่ยมที่ผ่านการลดจำนวนโพลิกอนแล้ว
  • Name
    decimation_mode
    Type
    integer
    Description

    เปิดใช้งานการลดจำนวนโพลิกอนแบบปรับตัว โดยการตั้งค่าระดับจำนวนโพลิกอน เมื่อตั้งค่านี้ target_polycount จะถูกละเว้น

    ค่าที่ใช้ได้:

    • 1: ปรับตัว — จำนวนโพลิกอนระดับสูงสุด
    • 2: ปรับตัว — จำนวนโพลิกอนระดับสูง
    • 3: ปรับตัว — จำนวนโพลิกอนระดับกลาง
    • 4: ปรับตัว — จำนวนโพลิกอนระดับต่ำ
  • Name
    save_pre_remeshed_model
    Type
    boolean
    ค่าเริ่มต้น false
    Description

    เมื่อตั้งค่าเป็น true Meshy จะจัดเก็บไฟล์ GLB เพิ่มเติมก่อนที่ขั้นตอนการรีเมชจะเสร็จสมบูรณ์

  • Name
    target_polycount
    Type
    integer
    Description

    จำนวนโพลิกอน (หน้า) เป้าหมายในเอาต์พุต จำนวนจริงอาจแตกต่างจากเป้าหมายขึ้นอยู่กับจีออเมทรี

    target_polycount มีผลใน 2 กรณีที่เป็นอิสระต่อกัน:

    • รีเมช — เมื่อ should_remesh: true บนโมเดล standard เมชจะถูกรีเมช (ลดจำนวนโพลิกอน) ให้ใกล้เคียงกับจำนวนนี้ ช่วง 100 ถึง 300,000 ค่าเริ่มต้น 30,000 หากตั้งค่า decimation_mode ไว้ จะมีความสำคัญเหนือกว่าและ target_polycount จะถูกละเว้น
    • Smart Topology — เมื่อ model_type: smart-topology และ ai_model: meshy-t2 โมเดลจะถูกสร้างขึ้นโดยตรงที่จำนวนหน้านี้ โดยไม่มีการรีเมชและไม่จำเป็นต้องใช้ should_remesh ช่วง 100 ถึง 15,000 ค่าเริ่มต้น 4,000
  • Name
    symmetry_mode
    Type
    string
    ⚠ เลิกใช้แล้ว
    ค่าเริ่มต้น auto
    Description

    เลิกใช้ พารามิเตอร์นี้ไม่มีผลต่อเอาต์พุตอีกต่อไป

    ฟิลด์ symmetry_mode ควบคุมพฤติกรรมความสมมาตรระหว่างกระบวนการสร้างโมเดล

    ค่าที่ใช้ได้ ได้แก่:

    • off: ปิดใช้งานความสมมาตร
    • auto: กำหนดและใช้ความสมมาตรโดยอัตโนมัติตามจีออเมทรีของอินพุต
    • on: บังคับใช้ความสมมาตรระหว่างการสร้าง
  • Name
    pose_mode
    Type
    string
    ค่าเริ่มต้น ""
    Description

    ระบุ mode ท่าทางสำหรับโมเดลที่สร้างขึ้น

    ค่าที่ใช้ได้:

    • a-pose: สร้างโมเดลในท่า A
    • t-pose: สร้างโมเดลในท่า T
    • "" (สตริงว่าง): ไม่ใช้ท่าทางที่เจาะจง
  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ เลิกใช้แล้ว
    ค่าเริ่มต้น false
    Description

    ใช้ pose_mode แทน กำหนดว่าจะสร้างโมเดลในท่า A/T หรือไม่

  • Name
    image_enhancement
    Type
    boolean
    ค่าเริ่มต้น true
    Description

    ปรับรูปภาพอินพุตให้เหมาะสมเพื่อผลลัพธ์ที่ดียิ่งขึ้น ตั้งค่าเป็น false เพื่อคงลักษณะที่แน่นอนของรูปภาพอินพุตไว้โดยไม่มีการประมวลผลด้านสไตล์ใดๆ

    รองรับเฉพาะเมื่อ ai_model เป็น meshy-6, meshy-7.1 หรือ latest

  • Name
    remove_lighting
    Type
    boolean
    ค่าเริ่มต้น true
    Description

    ลบไฮไลต์และเงาออกจากเท็กซ์เจอร์สีพื้นฐาน ทำให้ได้ผลลัพธ์ที่สะอาดกว่าและใช้งานได้ดีกว่าภายใต้การตั้งค่าแสงแบบกำหนดเอง

    รองรับเฉพาะเมื่อ ai_model เป็น meshy-6

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

    เมื่อตั้งค่าเป็น true เนื้อหาอินพุตจะถูกตรวจสอบโดยอัตโนมัติเพื่อหาเนื้อหาที่อาจเป็นอันตราย หากตรวจพบเนื้อหาที่เป็นอันตราย งานจะไม่ดำเนินต่อไปยังขั้นตอนการสร้าง

    เนื้อหาจากอินพุต image_url, texture_image_url และ texture_prompt จะถูกตรวจสอบ

  • Name
    target_formats
    Type
    string[]
    Description

    ระบุรูปแบบไฟล์ 3D ที่จะรวมอยู่ในเอาต์พุต จะสร้างและส่งคืนเฉพาะรูปแบบที่ร้องขอเท่านั้น ซึ่งสามารถลดเวลาในการทำงานให้เสร็จสมบูรณ์ได้ หากไม่ระบุ จะรวมรูปแบบที่รองรับทั้งหมด

    ค่าที่ใช้ได้: glb, obj, fbx, stl, usdz, 3mf

    หากไม่ระบุ จะสร้างรูปแบบทั้งหมดยกเว้น 3mf โดย 3mf จะรวมอยู่ด้วยก็ต่อเมื่อระบุอย่างชัดเจนเท่านั้น

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

    เมื่อตั้งค่าเป็น true บริการจะใช้ AI vision เพื่อประมาณความสูงของวัตถุในโลกจริงโดยอัตโนมัติ และปรับขนาดโมเดลตามนั้น จุดกำเนิดจะมีค่าเริ่มต้นเป็น bottom เว้นแต่จะตั้งค่า origin_at ไว้อย่างชัดเจน

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

    เมื่อตั้งค่าเป็น true งานจะเรนเดอร์ตัวอย่างพื้นหลังโปร่งใส (RGBA) เพิ่มเติม และส่งคืนเป็น alpha_thumbnail_url ในการตอบสนอง GET ฟิลด์ thumbnail_url ที่มีอยู่เดิมจะไม่เปลี่ยนแปลง

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

    เมื่อตั้งค่าเป็น true งานจะเรนเดอร์ภาพตัวอย่างขนาดย่อจากมุมมองหลัก 4 มุม (หน้า, ขวา, หลัง, ซ้าย) เพิ่มเติม และส่งคืนภายใต้ thumbnail_urls ในการตอบสนอง GET ฟิลด์ thumbnail_url ที่มีอยู่เดิมจะไม่เปลี่ยนแปลงและยังคงชี้ไปที่มุมมองด้านหน้า ดังนั้นไคลเอนต์ที่มีอยู่จะไม่ได้รับผลกระทบ

    เพิ่มเวลาแฝงของงานประมาณ 3 วินาที

ใช้เฉพาะเมื่อ auto_size = true
  • Name
    origin_at
    Type
    string
    ค่าเริ่มต้น bottom
    Description

    ตำแหน่งของจุดกำเนิดเมื่อเปิดใช้งาน auto_size

    ค่าที่ใช้ได้: bottom, center

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

พร็อพเพอร์ตี้ result ของการตอบสนองจะมี id ของงานรูปภาพเป็น 3D ที่สร้างขึ้นใหม่

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

  • Name
    400 - Bad Request
    Description

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

    • ขาดพารามิเตอร์: ต้องระบุ image_url หรือ input_task_id อย่างใดอย่างหนึ่ง
    • งานอินพุตไม่ถูกต้อง: input_task_id ต้องอ้างอิงถึงงาน ข้อความเป็นรูปภาพ หรือ รูปภาพเป็นรูปภาพ ที่มีสถานะ SUCCEEDED และสร้างรูปภาพออกมาเพียงหนึ่งภาพเท่านั้น
    • รูปแบบรูปภาพไม่ถูกต้อง: image_url ที่ระบุไม่ใช่รูปแบบที่รองรับ (.jpg, .jpeg, .png)
    • URL ไม่สามารถเข้าถึงได้: ไม่สามารถดาวน์โหลด image_url ได้ (404 หรือ timeout)
    • Data URI ไม่ถูกต้อง: สตริง base64 มีรูปแบบไม่ถูกต้อง
    • การรวมพารามิเตอร์ไม่ถูกต้อง: enable_pbr รองรับเฉพาะเมื่อ should_texture เป็น true เท่านั้น
    • โมเดลไม่รองรับสำหรับโลว์โพลี: ai_model: "meshy-6-lite" ไม่รองรับ model_type: "lowpoly"
    • โมเดลไม่รองรับสำหรับ Ultra: geometry_resolution ต้องใช้ meshy-7.1 หรือ latest
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    429 - Too Many Requests
    Description

    คุณได้เกินขีดจำกัดอัตราของคุณแล้ว

Request

POST
/openapi/v1/image-to-3d
# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -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>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -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>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v1/image-to-3d/:id

ดึงข้อมูล Image to 3D Task

เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงข้อมูลงาน รูปภาพเป็น 3D โดยใช้ id ของงานที่ถูกต้อง ดูรายละเอียดที่ The Image to 3D Task Object เพื่อดูว่ามีคุณสมบัติ (properties) ใดบ้างที่รวมอยู่ในอ็อบเจ็กต์งาน รูปภาพเป็น 3D

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

    รหัสเฉพาะสำหรับงาน รูปภาพเป็น 3D ที่ต้องการดึงข้อมูล

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

การตอบกลับจะมีอ็อบเจ็กต์งาน รูปภาพเป็น 3D อยู่ด้วย ดูรายละเอียดได้ที่ส่วน The Image to 3D Task Object

Request

GET
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}
DELETE/openapi/v1/image-to-3d/:id

ลบงานรูปภาพเป็น 3D

เอนด์พอยต์นี้จะลบงานรูปภาพเป็น 3D อย่างถาวร รวมถึงโมเดลและข้อมูลที่เกี่ยวข้องทั้งหมด การกระทำนี้ไม่สามารถย้อนกลับได้

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

  • Name
    id
    Type
    path
    Description

    ID ของงานรูปภาพเป็น 3D ที่ต้องการลบ

สถานะของงาน

งานที่ยังอยู่ในสถานะ PENDING จะถูกลบและเครดิตที่ใช้ไปตอนสร้างงานจะถูกคืนให้

งานที่อยู่ในสถานะ IN_PROGRESS แล้วจะไม่สามารถลบได้: คำขอจะถูกปฏิเสธด้วย 409 Conflict และงานจะยังคงทำงานต่อไป เครดิตสำหรับงานที่ worker เริ่มดำเนินการไปแล้วจะไม่สามารถคืนได้ ดังนั้นการลบงานระหว่างที่กำลังทำงานอยู่ จะทำให้คุณเสียทั้งเครดิตและผลลัพธ์ไปพร้อมกัน โปรดรอจนกว่างานจะถึงสถานะ SUCCEEDED, FAILED หรือ CANCELED แล้วจึงลบ

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

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

ส่งคืน 200 OK เมื่อสำเร็จ หรือ 409 Conflict เมื่องานอยู่ในสถานะ IN_PROGRESS

Request

DELETE
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
GET/openapi/v1/image-to-3d

List Image to 3D Tasks

เอนด์พอยต์นี้ช่วยให้คุณสามารถดึงรายการงาน รูปภาพเป็น 3D ได้

พารามิเตอร์

แอตทริบิวต์ที่ไม่บังคับ

  • Name
    page_num
    Type
    integer
    Description

    หมายเลขหน้าสำหรับการแบ่งหน้า เริ่มต้นและมีค่าเริ่มต้นเป็น 1

  • Name
    page_size
    Type
    integer
    Description

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

  • Name
    sort_by
    Type
    string
    Description

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

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

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

ส่งกลับรายการแบบแบ่งหน้าของ The Image to 3D Task Objects

Request

GET
/openapi/v1/image-to-3d
curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
        "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
        "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
        "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
        "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {
      "message": ""
    },
    "consumed_credits": 30
  }
]
GET/openapi/v1/image-to-3d/:id/stream

สตรีมงาน Image to 3D

เอนด์พอยต์นี้จะสตรีมการอัปเดตแบบเรียลไทม์สำหรับงาน Image to 3D โดยใช้ Server-Sent Events (SSE)

พารามิเตอร์

  • Name
    id
    Type
    path
    Description

    ตัวระบุเฉพาะสำหรับงาน Image to 3D ที่ต้องการสตรีม

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

ส่งคืนสตรีมของ The Image to 3D Task Objects ในรูปแบบ Server-Sent Events

สำหรับงานที่มีสถานะ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะมีเฉพาะฟิลด์ progress และ status ที่จำเป็นเท่านั้น

Request

GET
/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
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": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
  "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
  "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
  "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}

The Image to 3D Task Object

Image to 3D Task object เป็นหน่วยงานที่ Meshy ใช้ติดตามการสร้างโมเดล 3D จากอินพุตที่เป็น รูปภาพ อ็อบเจ็กต์นี้มีคุณสมบัติดังต่อไปนี้

Properties

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    ประเภทของ Image to 3D task ค่าคือ image-to-3d

  • Name
    model_urls
    Type
    object
    Description

    URL สำหรับดาวน์โหลดไฟล์โมเดล 3D ที่มีเท็กซ์เจอร์ซึ่งสร้างโดย Meshy คุณสมบัติสำหรับรูปแบบไฟล์จะถูกละไว้หากไม่ได้สร้างรูปแบบนั้น แทนที่จะคืนค่าเป็นสตริงว่าง

    • Name
      glb
      Type
      string
      Description

      URL สำหรับดาวน์โหลดไฟล์ GLB

    • Name
      fbx
      Type
      string
      Description

      URL สำหรับดาวน์โหลดไฟล์ FBX

    • Name
      obj
      Type
      string
      Description

      URL สำหรับดาวน์โหลดไฟล์ OBJ

    • Name
      usdz
      Type
      string
      Description

      URL สำหรับดาวน์โหลดไฟล์ USDZ

    • Name
      mtl
      Type
      string
      Description

      URL สำหรับดาวน์โหลดไฟล์ MTL ซึ่งจะถูกส่งกลับมาพร้อมกับการส่งออก OBJ เมื่อมีเท็กซ์เจอร์

    • Name
      stl
      Type
      string
      Description

      URL สำหรับดาวน์โหลดไฟล์ STL

    • Name
      3mf
      Type
      string
      Description

      URL สำหรับดาวน์โหลดไฟล์ 3MF จะมีให้เฉพาะเมื่อมีการขอ 3mf ผ่าน target_formats

    • Name
      pre_remeshed_glb
      Type
      string
      Description

      URL สำหรับดาวน์โหลดผลลัพธ์ GLB ต้นฉบับก่อนการ remesh

      มีให้เฉพาะเมื่อ task ถูกสร้างขึ้นด้วยทั้ง should_remesh: true และ save_pre_remeshed_model: true

  • Name
    thumbnail_url
    Type
    string
    Description

    URL สำหรับดาวน์โหลดภาพย่อของไฟล์โมเดล เทียบเท่ากับ thumbnail_urls.front เมื่อมีอยู่ เก็บไว้เพื่อความเข้ากันได้แบบย้อนหลัง

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL สำหรับดาวน์โหลดเวอร์ชันพื้นหลังโปร่งใส (RGBA) ของ thumbnail_url จะมีให้เฉพาะเมื่อ task ถูกสร้างขึ้นด้วย alpha_thumbnail: true และการแสดงตัวอย่างแบบโปร่งใสถูกเรนเดอร์สำเร็จแล้ว หากไม่เช่นนั้นฟิลด์นี้จะถูกละไว้

  • Name
    thumbnail_urls
    Type
    object
    Description

    URL สำหรับดาวน์โหลดภาพย่อสี่มุมมองหลักของโมเดล 3D ที่สร้างขึ้น แต่ละค่าเป็น signed URL ไปยังไฟล์ PNG ขนาด 512×512 ที่เรนเดอร์ด้วยวัสดุและแสงเดียวกันกับ thumbnail_url มีประโยชน์สำหรับการแสดงตัวอย่างโมเดลจากหลายมุมในไปป์ไลน์แบบแบตช์โดยไม่ต้องดาวน์โหลด GLB

    มีให้เฉพาะเมื่อ task ถูกสร้างขึ้นด้วย multi_view_thumbnails: true และมีสถานะเป็น SUCCEEDED แล้ว task เก่าและ task ที่สร้างขึ้นโดยไม่ได้เปิดใช้ตัวเลือกนี้จะไม่มีฟิลด์นี้

    • Name
      front
      Type
      string
      Description

      มุมมองด้านหน้า หมุน 0° รอบแกนตั้ง (ตรงกับ thumbnail_url)

    • Name
      right
      Type
      string
      Description

      มุมมองด้านขวา หมุน 90°

    • Name
      back
      Type
      string
      Description

      มุมมองด้านหลัง หมุน 180°

    • Name
      left
      Type
      string
      Description

      มุมมองด้านซ้าย หมุน 270°

  • Name
    texture_prompt
    Type
    string
    Description

    ข้อความ prompt ที่ใช้ในการกำหนดแนวทางกระบวนการทำเท็กซ์เจอร์

  • Name
    texture_image_url
    Type
    string
    Description

    URL สำหรับดาวน์โหลดภาพเท็กซ์เจอร์ที่ใช้ในการกำหนดแนวทางกระบวนการทำเท็กซ์เจอร์

  • Name
    ultra_mode
    Type
    boolean
    ⚠ เลิกใช้แล้ว
    Description

    เลิกใช้แล้ว ให้อ่าน geometry_resolution แทน

  • Name
    geometry_resolution
    Type
    string
    Description

    ระดับ Ultra ที่ task นี้ทำงาน (2k หรือ 4k) จะถูกละไว้สำหรับ standard

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

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

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    texture_urls
    Type
    array
    Description

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

    • Name
      base_color
      Type
      string
      Description

      URL สำหรับดาวน์โหลดภาพแมปสีพื้นฐาน

    • Name
      metallic
      Type
      string
      Description

      URL สำหรับดาวน์โหลดภาพแมปโลหะ

      หาก task ถูกสร้างขึ้นด้วย enable_pbr: false คุณสมบัตินี้จะถูกละไว้

    • Name
      normal
      Type
      string
      Description

      URL สำหรับดาวน์โหลดภาพนอร์มัลแมป

      หาก task ถูกสร้างขึ้นด้วย enable_pbr: false คุณสมบัตินี้จะถูกละไว้

    • Name
      roughness
      Type
      string
      Description

      URL สำหรับดาวน์โหลดภาพแมปความหยาบ

      หาก task ถูกสร้างขึ้นด้วย enable_pbr: false คุณสมบัตินี้จะถูกละไว้

    • Name
      emission
      Type
      string
      Description

      URL สำหรับดาวน์โหลดภาพแมปการเปล่งแสง

      หาก task ถูกสร้างขึ้นด้วย enable_pbr: false หรือ ai_model เป็น meshy-6-lite, meshy-7.1, หรือ latest คุณสมบัตินี้จะถูกละไว้

  • 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 (เครดิตจะถูกคืนเมื่อล้มเหลว)

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "texture_image_url": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
      "metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
      "normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
      "roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
      "emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}