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

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

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

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

เอนด์พอยต์นี้ช่วยให้คุณสร้างงาน Image to 3D ใหม่ได้ โปรดดู The Image to 3D Task Object เพื่อดูว่ามีพร็อพเพอร์ตี้ใดบ้างที่รวมอยู่ใน Image to 3D task object

พารามิเตอร์

จำเป็นต้องระบุเพียงหนึ่งใน 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: ข้อมูล 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-5, meshy-6, meshy-7, latest (Meshy 7)
การสร้างแบบ Smart Topology (model_type: smart-topology):
- meshy-t2 (ค่าเริ่มต้น): โมเดล Smart Topology — topology ที่สะอาดกว่า มีการแยกชิ้นส่วนโดยธรรมชาติ ผลลัพธ์เป็นสามเหลี่ยม และจำนวนหน้าที่คุณสามารถกำหนดได้ด้วย target_polycount
Name
ultra_mode
Type
boolean
ค่าเริ่มต้น false
Description
เปิดใช้งานการสร้างแบบ Ultra เพื่อให้ได้จีออเมทรีที่มีความแม่นยำสูงขึ้นพร้อมรายละเอียดพื้นผิวที่ละเอียดกว่า
รองรับเฉพาะเมื่อ ai_model เป็น meshy-7 (หรือ latest) เท่านั้น
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-7 และ latest จะไม่สร้าง emission map
Name
texture_resolution
Type
string
ค่าเริ่มต้น 2k
Description
ความละเอียดของเท็กซ์เจอร์สีพื้นฐาน หนึ่งใน 2k (2048×2048), 4k (4096×4096) หรือ 8k (8192×8192) ความละเอียดที่สูงกว่าจะจับรายละเอียดพื้นผิวได้มากกว่า
4k และ 8k ไม่สามารถใช้ได้กับ ai_model: meshy-5 ที่ 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: ข้อมูล 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, meshy-7), true (others)
Description
ควบคุมว่าจะเปิดใช้งานขั้นตอนรีเมชหรือไม่ สำหรับโมเดลที่มีคุณภาพสูงสุด เราแนะนำให้ตั้งค่า should_remesh เป็น false

ใช้เฉพาะเมื่อ should_remesh = true

Name
topology
Type
string
ค่าเริ่มต้น triangle
Description
ระบุ topology ของโมเดลที่สร้างขึ้น
ค่าที่ใช้ได้:
- quad: สร้างเมชที่ส่วนใหญ่เป็นรูปสี่เหลี่ยม
- 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, หรือ 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 ของงาน Image to 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 เท่านั้น
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 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>",
    "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

ดึงงาน รูปภาพเป็น 3D

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

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน รูปภาพเป็น 3D ที่จะดึง

การตอบกลับ

การตอบกลับจะมีวัตถุงาน รูปภาพเป็น 3D ตรวจสอบ ส่วน วัตถุงาน รูปภาพเป็น 3D สำหรับรายละเอียด

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 ที่จะลบ

ผลลัพธ์

ส่งคืน 200 OK เมื่อสำเร็จ

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

// Returns 200 Ok on success.

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

รายการงาน รูปภาพเป็น 3D

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

พารามิเตอร์

คุณสมบัติเสริม

Name
page_num
Type
integer
Description
หมายเลขหน้าสำหรับการแบ่งหน้า เริ่มต้นและค่าเริ่มต้นคือ 1
Name
page_size
Type
integer
Description
ขีดจำกัดขนาดหน้า ค่าเริ่มต้นคือ 10 รายการ อนุญาตสูงสุดคือ 50 รายการ
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

สตรีมงาน รูปภาพเป็น 3D

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

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะสำหรับงาน รูปภาพเป็น 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
}

วัตถุงาน รูปภาพเป็น 3D

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

คุณสมบัติ

Name
id
Type
string
Description
ตัวระบุเฉพาะสำหรับงานนี้ แม้ว่าเราจะใช้ UUID ที่สามารถเรียงลำดับได้สำหรับ id ของงานเป็นรายละเอียดการดำเนินการ คุณไม่ควรทำการสันนิษฐานใดๆ เกี่ยวกับรูปแบบของ id
Name
type
Type
string
Description
ประเภทของงาน รูปภาพเป็น 3D ค่านี้คือ 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
  มีเฉพาะเมื่อสร้างงานด้วย 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 มีเฉพาะเมื่อสร้างงานด้วย alpha_thumbnail: true และการแสดงตัวอย่างโปร่งใสสำเร็จ มิฉะนั้นฟิลด์นี้จะถูกละเว้น
Name
thumbnail_urls
Type
object
Description
URL สำหรับดาวน์โหลดภาพย่อมุมมองสี่ทิศทางของโมเดล 3D ที่สร้างขึ้น แต่ละค่าเป็น URL ที่ลงนามสำหรับ PNG ขนาด 512×512 ที่เรนเดอร์ด้วยวัสดุและแสงเดียวกันกับ thumbnail_url มีประโยชน์สำหรับการดูตัวอย่างโมเดลจากหลายมุมในกระบวนการแบบแบทช์โดยไม่ต้องดาวน์โหลด GLB
มีเฉพาะเมื่อสร้างงานด้วย multi_view_thumbnails: true และถึง SUCCEEDED งานเก่าและงานที่สร้างโดยไม่มีการเลือกเข้าจะไม่รวมฟิลด์นี้
- 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
สะท้อนค่าของ ultra_mode ที่สร้างงานด้วย มีเฉพาะสำหรับงาน meshy-7 (หรือ latest) ที่ตั้งค่า ultra_mode อย่างชัดเจน มิฉะนั้นจะถูกละเว้น
Name
progress
Type
integer
Description
ความคืบหน้าของงาน หากงานยังไม่เริ่ม คุณสมบัตินี้จะเป็น 0 เมื่อสำเร็จแล้วจะกลายเป็น 100
Name
started_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่เริ่มงานในหน่วยมิลลิวินาที หากงานยังไม่เริ่ม คุณสมบัตินี้จะเป็น 0
ไทม์สแตมป์แสดงจำนวนมิลลิวินาทีที่ผ่านไปตั้งแต่วันที่ 1 มกราคม 1970 UTC ตามมาตรฐาน RFC 3339 ตัวอย่างเช่น วันศุกร์ที่ 1 กันยายน 2023 เวลา 12:00:00 PM GMT แสดงเป็น 1693569600000 ซึ่งใช้กับไทม์สแตมป์ ทั้งหมด ใน Meshy API
Name
created_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่สร้างงานในหน่วยมิลลิวินาที
Name
expires_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่ผลลัพธ์ของงานหมดอายุในหน่วยมิลลิวินาที
Name
finished_at
Type
timestamp
Description
ไทม์สแตมป์ของเวลาที่งานเสร็จสิ้นในหน่วยมิลลิวินาที หากงานยังไม่เสร็จสิ้น คุณสมบัตินี้จะเป็น 0
Name
status
Type
string
Description
สถานะของงาน ค่าที่เป็นไปได้คือหนึ่งใน PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED
Name
texture_urls
Type
array
Description
อาร์เรย์ของวัตถุ URL เท็กซ์เจอร์ที่สร้างจากงาน ปกติจะมีเพียง หนึ่ง วัตถุ URL เท็กซ์เจอร์ แต่ละ URL เท็กซ์เจอร์มีคุณสมบัติดังต่อไปนี้:
- Name
  base_color
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแผนที่สีพื้นฐาน
- Name
  metallic
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแผนที่เมทัลลิก
  หากงานถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละเว้น
- Name
  normal
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพนอร์มัลแมป
  หากงานถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละเว้น
- Name
  roughness
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแผนที่ความหยาบ
  หากงานถูกสร้างด้วย enable_pbr: false คุณสมบัตินี้จะถูกละเว้น
- Name
  emission
  Type
  string
  Description
  URL สำหรับดาวน์โหลดภาพแผนที่การปล่อยแสง
  หากงานถูกสร้างด้วย enable_pbr: false หรือ ai_model เป็น meshy-5, meshy-7, หรือ latest คุณสมบัตินี้จะถูกละเว้น
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 (เครดิตจะถูกคืนเมื่อเกิดความล้มเหลว)

ตัวอย่างวัตถุงาน รูปภาพเป็น 3D

{
  "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
}