ข้อผิดพลาด

ในคู่มือนี้ เราจะพูดถึงสิ่งที่เกิดขึ้นเมื่อมีบางอย่างผิดพลาดขณะที่คุณ ทำงานกับ Meshy API

ข้อผิดพลาดของคำขอ

ข้อผิดพลาดเหล่านี้จะถูกส่งกลับทันทีเมื่อคำขอ API ของคุณถูกปฏิเสธ ตรวจสอบรหัสสถานะ HTTP และฟิลด์ message เพื่อทำความเข้าใจว่าเกิดอะไรผิดพลาด

{
  "message": "Invalid model file extension: .3dm"
}

ข้อผิดพลาดของงาน

ข้อผิดพลาดเหล่านี้เกิดขึ้นหลังจากสร้างงานแล้วและกำลังประมวลผลอยู่ ตรวจสอบออบเจ็กต์ task_error ในการตอบกลับของงานเพื่อดูรายละเอียดข้อผิดพลาด

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

ประเภทข้อผิดพลาด

ฟิลด์ type จะบอกหมวดหมู่กว้าง ๆ ของความล้มเหลว ใช้ฟิลด์นี้เพื่อตัดสินใจกลยุทธ์การลองใหม่ของคุณ

รหัสข้อผิดพลาด

เมื่อมีฟิลด์ code อยู่ ฟิลด์นี้จะระบุปัญหาเฉพาะที่สามารถดำเนินการแก้ไขได้ ด้านล่างคือข้อมูลอ้างอิงฉบับเต็มสำหรับรหัสข้อผิดพลาดแต่ละรายการ.

image_too_complex

ข้อผิดพลาดนี้เกิดขึ้นเมื่อภาพอินพุตหรือ prompt อธิบายวัตถุที่ซับซ้อนทางเรขาคณิตมากเกินกว่าที่โมเดลการสร้าง 3D จะประมวลผลได้

ตัวอย่างที่พบบ่อย ได้แก่:

• กองวัตถุขนาดเล็กที่หนาแน่น (เช่น ลังที่เต็มไปด้วยผลไม้, กองหนังสือ)
• ลวดลายซ้ำที่ซับซ้อน (เช่น โครงสร้างตาข่าย, นั่งร้าน, ตะแกรงลวด)
• โครงสร้างอาคารที่ซับซ้อน (เช่น อาคารหลายชั้นที่มีหน้าต่างและระเบียงจำนวนมาก)
• วัตถุที่แยกจากกันหลายชิ้นในภาพเดียว แทนที่จะเป็นวัตถุหลักเพียงชิ้นเดียว

ตัวอย่างของอินพุตที่มีแนวโน้มว่าจะซับซ้อนเกินไป:

วิธีแก้ไข:

1. ใช้วัตถุเพียงชิ้นเดียวต่อภาพ โมเดลทำงานได้ดีที่สุดกับวัตถุหลักหนึ่งชิ้นที่ชัดเจน อย่าใส่วัตถุที่แยกจากกันหลายชิ้นในภาพหรือ prompt เดียวกัน
2. ทำให้วัตถุของคุณเรียบง่ายขึ้น ลดระดับรายละเอียดลง ตัวอย่างเช่น แจกันเรียบง่ายแทนแจกันที่เต็มไปด้วยดอกไม้หลายสิบดอก
3. หลีกเลี่ยง prompt ระดับซีน อาคารทั้งหลัง, บล็อกเมือง, ภายในที่เต็มไปด้วยเฟอร์นิเจอร์ หรือภูมิทัศน์มีแนวโน้มที่จะเกินขีดความสามารถของโมเดล ให้โฟกัสที่วัตถุชิ้นเดียวแทน
4. หลีกเลี่ยงโครงสร้างซ้ำที่หนาแน่น วัตถุอย่างนั่งร้าน, ตะแกรงลวด, ลวดลายตาข่าย หรือกองสิ่งของขนาดเล็กจำนวนมาก เป็นตัวกระตุ้นที่พบบ่อย

model_missing_uv

ข้อผิดพลาดนี้เกิดขึ้นเมื่อคุณอัปโหลดโมเดลเพื่อทำเท็กซ์เจอร์โดยตั้งค่า enable_original_uv เป็น true แต่โมเดลไม่มีพิกัด UV พิกัด UV กำหนดว่าเท็กซ์เจอร์ 2D จะห่อหุ้มลงบนพื้นผิว 3D ของโมเดลของคุณอย่างไร

วิธีแก้ไข:

วิธีแก้ไขที่เหมาะสมขึ้นอยู่กับเหตุผลที่คุณตั้งค่า enable_original_uv เป็น true:

• หากคุณต้องการรักษาเลย์เอาต์ UV ดั้งเดิมของโมเดลไว้ (เช่น การวางตำแหน่งรอยต่อแบบกำหนดเองเพื่อการแมปเท็กซ์เจอร์ที่แม่นยำ): โมเดลของคุณต้องมีพิกัด UV ที่ถูกต้อง ตรวจสอบว่ามี UV อยู่ในเอดิเตอร์ UV ของซอฟต์แวร์ 3D ของคุณก่อนอัปโหลด โปรดทราบว่าไฟล์ STL ไม่สามารถจัดเก็บข้อมูล UV ได้ ดังนั้นให้ใช้ GLB, FBX หรือ OBJ แทน
• หากคุณไม่ต้องการการควบคุม UV แบบเฉพาะเจาะจง (หรือคุณไม่แน่ใจ): ให้ละเว้น enable_original_uv หรือตั้งค่าเป็น false ระบบจะสร้างเลย์เอาต์ UV สำหรับโมเดลของคุณโดยอัตโนมัติ UV ที่สร้างโดยอัตโนมัติจะถูกปรับให้เหมาะสมสำหรับการครอบคลุม แต่คุณจะไม่สามารถควบคุมตำแหน่งที่วางรอยต่อเท็กซ์เจอร์ได้

model_insufficient_uv

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

วิธีแก้ไข:

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

invalid_input

นี่คือรหัสข้อผิดพลาดสำรองเมื่ออินพุตไม่ผ่านการตรวจสอบความถูกต้อง แต่ไม่มีรหัสที่เฉพาะเจาะจงกว่านี้ที่ใช้ได้ ฟิลด์ message มีเหตุผลเฉพาะของความล้มเหลว

สาเหตุที่พบบ่อยได้แก่:

• ไฟล์โมเดลว่างเปล่าหรือเสียหาย
• รูปแบบไฟล์ที่ไม่รองรับบางรูปแบบ (เช่น ไฟล์ ASCII FBX, GLB ที่บีบอัดด้วย meshopt)
• ไม่พบอ็อบเจ็กต์ 3D ที่ถูกต้องในโมเดลที่อัปโหลด (เช่น ไฟล์มีเฉพาะ armatures, กล้อง หรือไฟ)
• เนื้อหาที่ไม่ผ่านตัวกรองความปลอดภัย

การแก้ไข: ตรวจสอบฟิลด์ message เพื่อดูรายละเอียดเฉพาะว่าเกิดข้อผิดพลาดใดขึ้น ตรวจสอบว่าไฟล์อินพุตและพารามิเตอร์ของคุณตรงกับข้อกำหนดของเอนด์พอยต์

moderation_blocked

ข้อผิดพลาดนี้เกิดขึ้นเมื่อ prompt หรือรูปภาพอ้างอิงของคุณถูกปฏิเสธโดยตัวกรองความปลอดภัยของ AI ตัวกรองจะประเมินทั้ง prompt แบบข้อความและรูปภาพอ้างอิงใด ๆ ร่วมกัน

วิธีแก้ไข:

• เรียบเรียง prompt แบบข้อความของคุณใหม่เพื่อลบคำบรรยายที่ชี้นำทางเพศหรือมีความละเอียดอ่อน
• ปรับรูปภาพอ้างอิงหากรูปภาพเหล่านั้นแสดงเนื้อหาที่อาจกระตุ้นตัวกรองความปลอดภัย

timeout

ข้อผิดพลาดนี้หมายความว่าเวลาประมวลผลของงานของคุณเกินขีดจำกัดที่อนุญาตไว้ กรณีนี้อาจเกิดขึ้นเนื่องจากโหลดของระบบสูง หรือเนื่องจากอินพุตซับซ้อนเกินกว่าจะประมวลผลภายในเวลาที่กำหนด

วิธีแก้ไข:

1. ลองส่งคำขออีกครั้ง timeout มักเกิดขึ้นชั่วคราว และการลองใหม่อาจสำเร็จ
2. ทำให้อินพุตของคุณเรียบง่ายขึ้น หากลองใหม่แล้วยังล้มเหลวอยู่ อินพุตของคุณอาจซับซ้อนเกินไป ลองลดระดับรายละเอียดในรูปภาพหรือ prompt ของคุณ ดู image_too_complex สำหรับคำแนะนำว่าอินพุตประเภทใดประมวลผลได้ยากกว่า

format_conversion_failed

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

วิธีแก้ไข:

1. ลองส่งคำขออีกครั้ง
2. ลองใช้รูปแบบเอาต์พุตอื่น หากรูปแบบใดรูปแบบหนึ่งยังคงล้มเหลว ให้เปลี่ยนไปใช้รูปแบบอื่นที่เหมาะกับความต้องการของคุณ

แนวทางปฏิบัติที่ดีที่สุด

1. ใช้ตรรกะการลองใหม่. สำหรับข้อผิดพลาด timeout และ service_unavailable ให้ใช้ตรรกะการลองใหม่แบบ exponential backoff
2. บันทึก ID งาน. บันทึก ID งานไว้เสมอเพื่อวัตถุประสงค์ในการดีบัก รวมไว้ด้วยเมื่อติดต่อฝ่ายสนับสนุน
3. ตรวจสอบอินพุต. ตรวจสอบให้แน่ใจว่ารูปภาพและโมเดลอินพุตของคุณเป็นไปตามข้อกำหนดรูปแบบก่อนส่ง