Image to 3D API

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

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

สร้าง Image to 3D Task

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

พารามิเตอร์

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

Name
input_task_id
Type
string
จำเป็น
Description
ID ของ task การสร้างภาพที่เสร็จสมบูรณ์แล้วซึ่งจะใช้ผลลัพธ์เป็นรูปภาพอินพุต Task นี้ต้องเป็นหนึ่งใน task ต่อไปนี้: ข้อความเป็นรูปภาพ หรือ รูปภาพเป็นรูปภาพ นอกจากนี้ จะต้องดำเนินการผ่าน 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-t1 หรือ 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
- meshy-t1: โมเดลโลว์โพลีเก่า; ไม่รองรับการตั้งค่าจำนวนหน้าด้วย target_polycount
Name
ultra_mode
Type
boolean
ค่าเริ่มต้น false
Description
เปิดใช้งานการสร้างแบบ Ultra เพื่อให้ได้ geometry ที่มีความละเอียดสูงขึ้นและรายละเอียดพื้นผิวที่ละเอียดกว่า
รองรับเฉพาะเมื่อ ai_model คือ meshy-7 (หรือ latest)
Name
should_texture
Type
boolean
ค่าเริ่มต้น true
Description
กำหนดว่าจะแสดงเท็กซ์เจอร์หรือไม่ เมื่อตั้งค่าเป็น false จะข้ามขั้นตอนการแสดงเท็กซ์เจอร์ ให้เมชที่ไม่มีเท็กซ์เจอร์

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

Name
enable_pbr
Type
boolean
ค่าเริ่มต้น false
Description
สร้าง PBR Maps (metallic, roughness, normal) นอกจากสีพื้นฐานแล้ว ยังรวมแผนที่การปล่อยแสงอยู่ด้วยเมื่อ ai_model คือ meshy-6 ยกเว้นที่ texture_resolution: 8k ส่วน meshy-7 และ latest จะไม่ผลิตแผนที่การปล่อยแสง
Name
texture_resolution
Type
string
ค่าเริ่มต้น 2k
Description
ความละเอียดของเท็กซ์เจอร์สีพื้นฐาน หนึ่งใน 2k (2048×2048), 4k (4096×4096), หรือ 8k (8192×8192) ความละเอียดที่สูงขึ้นจะเก็บรายละเอียดพื้นผิวได้มากขึ้น
4k และ 8k ไม่สามารถใช้งานได้กับ ai_model: meshy-5 ที่ 8k จะไม่มีการผลิตแผนที่การปล่อยแสง
Name
hd_texture
Type
boolean
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น false
Description
ใช้ texture_resolution แทน - เทียบเท่ากับ texture_resolution: "4k" เมื่อทั้งสองตั้งค่า texture_resolution จะเป็นผู้กำหนด
Name
texture_prompt
Type
string
Description
ให้ prompt ข้อความเพื่อนำทางกระบวนการ texturing สูงสุด 600 ตัวอักษร
Name
texture_image_url
Type
string
Description
ให้ภาพ 2D เพื่อแนะนำกระบวนการ texturing ปัจจุบันเรารองรับฟอร์แมต .jpg, .jpeg, และ .png
มีสองวิธีในการให้ภาพ:
- URL ที่เปิดให้สาธารณชนเข้าถึงได้: URL ที่เข้าถึงได้จากอินเทอร์เน็ตสาธารณะ
- Data URI: Data URI ที่เข้ารหัสด้วย base64 ของภาพ ตัวอย่าง Data URI: data:image/jpeg;base64,<your base64-encoded image data>
การทำให้มี texturing ด้วยภาพอาจไม่ได้ผลลัพธ์ที่ดีที่สุดหากมีความแตกต่างของ geometry อย่างมีนัยสำคัญระหว่าง asset ดั้งเดิมและภาพที่อัปโหลด มีเพียงหนึ่งใน texture_image_url หรือ texture_prompt เท่านั้นที่สามารถใช้เพื่อแนะนำกระบวนการ texturing หากมีการให้ทั้งสองค่าจะใช้ texture_prompt ในการแสดงเท็กซ์เจอร์ของโมเดลตามค่าเริ่มต้น การทำ texturing ผ่านทั้งข้อความหรือภาพจะเสียค่าเครดิต 10 เครดิตต่อ task

Name
should_remesh
Type
boolean
ค่าเริ่มต้น false (meshy-6, meshy-7), true (others)
Description
ควบคุมว่าจะเปิดใช้งานขั้นตอน remesh หรือไม่ สำหรับโมเดลคุณภาพสูงสุด เราแนะนำให้ตั้งค่า should_remesh เป็น false

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

Name
topology
Type
string
ค่าเริ่มต้น triangle
Description
ระบุ topology ของโมเดลที่สร้างขึ้น
ค่าที่มีใช้ได้:
- quad: สร้างเมชชที่มีรูปแบบ quad เป็นหลัก
- triangle: สร้างเมชชสามเหลี่ยมที่ลดขนาด
Name
decimation_mode
Type
integer
Description
เปิดการลดขนาดเชิงปรับตัวโดยตั้งค่าระดับ polycount เมื่อมีการตั้งค่า target_polycount จะถูกเมิน
ค่าที่มีใช้ได้:
- 1: เชิงปรับตัว — ultra polycount
- 2: เชิงปรับตัว — high polycount
- 3: เชิงปรับตัว — medium polycount
- 4: เชิงปรับตัว — low polycount
Name
save_pre_remeshed_model
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true Meshy จะเก็บไฟล์ GLB เพิ่มเติมก่อนที่ remesh จะเสร็จสมบูรณ์

Name
target_polycount
Type
integer
Description
จำนวนโพลิกอน (faces) เป้าหมายในผลลัพธ์ จำนวนจริงอาจเบี่ยงเบนจากเป้าหมายขึ้นอยู่กับ geometry
target_polycount มีผลในสองกรณีอิสระ:
- Remesh — กับ should_remesh: true ในโมเดล standard เมชชจะถูกรีเมช (ลดขนาด) ประมาณค่าที่ตั้งไว้ ช่วง 100 ถึง 300,000 ค่าเริ่มต้น 30,000 หากตั้งค่า decimation_mode จะมีความสำคัญและ target_polycount จะถูกละเลย
- Smart Topology — กับ model_type: smart-topology และ ai_model: meshy-t2 โมเดลจะถูกสร้างขึ้นโดยตรงที่จำนวนหน้านี้; ไม่มีกระบวนการ remesh และไม่ต้องการ should_remesh ช่วง 100 ถึง 15,000 ค่าเริ่มต้น 4,000

Name
symmetry_mode
Type
string
⚠ เลิกใช้แล้ว
ค่าเริ่มต้น auto
Description
เลิกใช้ พารามิเตอร์นี้ไม่มีผลต่อผลลัพธ์อีกต่อไป
ฟิลด์ symmetry_mode ควบคุมพฤติกรรมสมมาตรระหว่างกระบวนการสร้างโมเดล
ค่าที่ใช้งานได้:
- off: ปิดการใช้งานสมมาตร
- auto: กำหนดและใช้สมมาตรโดยอัตโนมัติขึ้นอยู่กับ geometry อินพุต
- on: บังคับสมมาตรระหว่างการสร้าง
Name
pose_mode
Type
string
ค่าเริ่มต้น ""
Description
ระบุโหมดท่าของโมเดลที่สร้างขึ้น
ค่าที่มีให้ใช้ได้:
- 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
ลบ highlights และ shadows ออกจากเท็กซ์เจอร์สีพื้นฐาน ให้ผลลัพธ์ที่สะอาดขึ้นที่ทำงานได้ดีขึ้นภายใต้การตั้งค่าแสงแบบกำหนดเอง
รองรับเฉพาะเมื่อ ai_model คือ meshy-6
Name
moderation
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อตั้งค่าเป็น true เนื้อหาจะถูกตรวจสอบโดยอัตโนมัติเพื่อค้นหาภายในมีศักยภาพอันตราย ถ้าพบเนื้อหาที่เป็นอันตราย task จะไม่ดำเนินการต่อไปยังการสร้าง
เนื้อหาจากอินพุต image_url, texture_image_url, และ texture_prompt จะถูกตรวจสอบ
Name
target_formats
Type
string[]
Description
ระบุรูปแบบไฟล์ 3D ที่จะรวมอยู่ในผลลัพธ์ จะมีการสร้างและคืนค่าเฉพาะฟอร์แมตที่ร้องขอเท่านั้น ซึ่งสามารถลดเวลาการทำ task ได้ เมื่อไม่ระบุ ฟอร์แมตที่รองรับทั้งหมดจะถูกรวมเข้าไป
ค่าที่มีใช้ได้: glb, obj, fbx, stl, usdz, 3mf
เมื่อไม่ระบุ ฟอร์แมตทั้งหมด ยกเว้น 3mf จะถูกสร้าง 3mf เท่านั้นจะถูกรวมเมื่อระบุอย่างชัดเจน
Name
auto_size
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อถูกตั้งค่าเป็น true บริการจะใช้ AI vision เพื่อประมาณความสูงจริงของวัตถุโดยอัตโนมัติและปรับขนาด model ตาม เวลาที่ auto_size ค่าเริ่มต้นจะเป็น bottom เว้นแต่ origin_at จะถูกตั้งค่าอย่างชัดเจน
Name
alpha_thumbnail
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อถูกตั้งค่าเป็น true task จะทำการแสดงผลเพิ่มเติมที่มีพื้นหลังโปร่งใส (RGBA) ของพรีวิวและคืนให้เป็น alpha_thumbnail_url ในการตอบกลับ GET ฟิลด์ thumbnail_url ที่มีอยู่จะไม่ได้รับการเปลี่ยนแปลง
Name
multi_view_thumbnails
Type
boolean
ค่าเริ่มต้น false
Description
เมื่อถูกตั้งค่าเป็น true task จะทำการแสดงผลเพิ่มเติมและคืนไอคอนวิวหลักสี่ตำแหน่ง (หน้า ขวา หลัง ซ้าย) ที่อยู่ภายใต้ thumbnail_urls ในการตอบกลับ GET ฟิลด์ thumbnail_url ที่มีอยู่จะไม่ได้รับการเปลี่ยนแปลงและยังคงชี้ไปยังวิวด้านหน้า ดังนั้นลูกค้าที่มีอยู่จะไม่ได้รับผลกระทบ
เพิ่มเวลาการหน่วงในการทำ task ประมาณ 3 วินาที

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

Name
origin_at
Type
string
ค่าเริ่มต้น bottom
Description
ตำแหน่งของต้นกำเนิดเมื่อ auto_size เปิดใช้งาน
ค่าที่มีใช้ได้: bottom, center

การคืนค่า

คุณสมบัติ result จากการตอบสนองจะมี task id ของ Image to 3D task ที่สร้างใหม่

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

Name
400 - Bad Request
Description
คำขอไม่สามารถยอมรับได้ สาเหตุที่พบบ่อย:
- Missing parameter: มีการต้องให้ทั้ง image_url หรือ input_task_id
- Invalid input task: input_task_id ต้องเป็น task Text to Image หรือ Image to Image ที่ SUCCEEDED และสร้างภาพเพียงภาพเดียว
- Invalid image format: image_url ที่ให้ไม่ใช่ฟอร์แมตที่รองรับ (.jpg, .jpeg, .png)
- Unreachable URL: ไม่สามารถดาวน์โหลด image_url ได้ (404 หรือ timeout)
- Invalid Data URI: string base64 เสียรูป
- Invalid parameter combination: enable_pbr รองรับเฉพาะเมื่อ should_texture เป็นจริง
Name
401 - Unauthorized
Description
การยืนยันตัวตนล้มเหลว โปรดตรวจสอบ API key ของคุณ
Name
402 - Payment Required
Description
เครดิตไม่เพียงพอในการดำเนินการ task นี้
Name
429 - Too Many Requests
Description
คุณเกินการจำกัดอัตราของคุณแล้ว

Request

POST

/openapi/v1/image-to-3d

# คำขอที่เรียบง่ายพร้อมพารามิเตอร์ที่จำเป็น
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>"
  }'

# พร้อม remesh, PBR, และ 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

รับ Image to 3D Task

เอนด์พอยต์นี้อนุญาตให้คุณดึงข้อมูล Image to 3D task ให้ task id ที่ถูกต้อง ดูที่ The Image to 3D Task Object เพื่อดูว่า properties ไหนบ้างที่รวมอยู่กับวัตถุ Image to 3D task

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะของ Image to 3D task ที่จะดึงข้อมูล

การคืนค่า

การตอบสนองมี Image to 3D task object ตรวจสอบส่วน 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

ลบ Image to 3D Task

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

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

Name
id
Type
path
Description
ID ของ Image to 3D task ที่จะลบ

การคืนค่า

คืนค่า 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

รายการ Image to 3D Tasks

เอนด์พอยต์นี้อนุญาตให้คุณดึงรายการของ Image to 3D tasks

พารามิเตอร์

คุณลักษณะทางเลือก

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

สตรีม Image to 3D Task

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

พารามิเตอร์

Name
id
Type
path
Description
ตัวระบุเฉพาะของ Image to 3D task ที่จะสตรีม

การคืนค่า

คืนสตรีมของ The Image to 3D Task Objects เป็น Server-Sent Events

สำหรับ task ที่ 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

// ตัวอย่างเหตุการณ์ข้อผิดพลาด
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// ตัวอย่างเหตุการณ์ข้อความแสดงความก้าวหน้าของ task
// สำหรับ task ที่ PENDING หรือ IN_PROGRESS สตรีมการตอบกลับจะไม่รวมทุกฟิลด์
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
}

วัตถุ Image to 3D Task

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

คุณสมบัติ

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