ข้อผิดพลาด

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

invalid_input

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

สาเหตุทั่วไปได้แก่:

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

วิธีแก้ไข: ตรวจสอบฟิลด์ 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 ให้ใช้ตรรกะการลองใหม่แบบถอยหลังแบบทวีคูณ
2. บันทึก ID งาน. บันทึก ID งานเสมอเพื่อวัตถุประสงค์ในการดีบัก รวมถึงเมื่อคุณติดต่อฝ่ายสนับสนุน
3. ตรวจสอบความถูกต้องของข้อมูลนำเข้า. ตรวจสอบให้แน่ใจว่าภาพและโมเดลนำเข้าของคุณตรงตามข้อกำหนดของรูปแบบก่อนการส่ง