ข้อผิดพลาด

ในคู่มือนี้ เราจะพูดถึงสิ่งที่เกิดขึ้นเมื่อมีบางอย่างผิดพลาดขณะที่คุณ ทำงานกับ 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 จะบอกหมวดหมู่กว้างๆ ของความล้มเหลว ใช้ข้อมูลนี้เพื่อตัดสินใจเลือกกลยุทธ์การลองใหม่ (retry)

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

เมื่อมีฟิลด์ 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 ที่สร้างขึ้นอัตโนมัติจะมีการครอบคลุมที่เหมาะสมสำหรับการทำเท็กซ์เจอร์

model_missing_texture

ข้อผิดพลาดนี้เกิดขึ้นเมื่อโมเดลอินพุตของงาน Multi-Color Print ไม่มีข้อมูลสีที่ตัวแปลงไฟล์สามารถแยกออกเป็นสีสำหรับพิมพ์ได้ 3MF สำหรับการพิมพ์หลายสีถูกสร้างขึ้นจากสีของโมเดล ดังนั้นเมชสีขาวล้วน — เช่น พรีวิวจาก Text to 3D หรือ Image to 3D ที่ไม่เคยถูกใส่เท็กซ์เจอร์ หรือผลลัพธ์ที่ผ่านการซ่อมแซม / แยกส่วนอัตโนมัติ — จะไม่มีข้อมูลให้นำไปใช้งานได้

สิ่งที่นับว่าเป็นแหล่งที่มาของสีนั้นขึ้นอยู่กับ style ที่คุณร้องขอ:

• realistic สุ่มตัวอย่างเท็กซ์เจอร์สีพื้นฐานผ่านพิกัด UV ของโมเดล ดังนั้นจึงต้องมีเท็กซ์เจอร์สีพื้นฐานเดียวพร้อมพิกัด UV บนทุกส่วนของเมช
• cartoon ทำให้สีแบนราบต่อหน้า (face) และยอมรับเท็กซ์เจอร์สีพื้นฐานบนส่วนใดก็ได้ หรือ สีต่อจุดยอด (COLOR_0)

โมเดลที่ไม่มีทั้งเท็กซ์เจอร์สีพื้นฐานและสีจุดยอดจะถูกปฏิเสธสำหรับทั้งสองสไตล์ เพราะถ้าใช้ cartoon มันจะ "สำเร็จ" กลายเป็นงานพิมพ์สีเดียวแทน

คำขอส่วนใหญ่จะถูกปฏิเสธก่อนที่งานจะถูกสร้างขึ้น (400 Bad Request พร้อมคำอธิบายเดียวกัน) ดังนั้นคุณมักจะเห็นรหัสนี้เฉพาะเมื่อไม่สามารถตรวจสอบอินพุตล่วงหน้าได้ — เช่น การอัปโหลดไฟล์ .fbx จะถูกตรวจสอบก็ต่อเมื่องานได้ทำการ normalize ไฟล์นั้นแล้ว

วิธีแก้ไข:

• ใส่เท็กซ์เจอร์ให้โมเดลก่อน รันงาน Retexture กับโมเดลนั้น หรือสร้างโมเดลโดยเปิดใช้งานการใส่เท็กซ์เจอร์ (งาน refine ของ Text to 3D หรืองาน Image to 3D ที่มี should_texture: true) แล้วส่งงานนั้นเป็น input_task_id
• โมเดลที่มีสีแบบจุดยอด (สแกนจากภาพถ่าย, เมชที่วาดด้วยมือ): ให้ร้องขอ style: "cartoon" ซึ่งจะอ่านค่า COLOR_0
• โมเดลที่ใส่เท็กซ์เจอร์เพียงบางส่วนหรือมีหลายเท็กซ์เจอร์ภายใต้ realistic: ทุกส่วนของเมชต้องมีพิกัด UV และเท็กซ์เจอร์สีพื้นฐานเดียวกันเพียงชุดเดียว ให้ใส่เท็กซ์เจอร์ในส่วนที่เหลือหรือรวมเท็กซ์เจอร์เข้าเป็นอัตลาส (atlas) เดียว หรือเปลี่ยนไปใช้ style: "cartoon" แทน

invalid_input

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

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

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

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

moderation_blocked

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

การแก้ไข:

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

moderation_unavailable

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

การแก้ไข: สร้างงานใหม่อีกครั้ง

timeout

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

สิ่งนี้แตกต่างจาก timeout ในโค้ดฝั่งของคุณเอง หากไคลเอนต์ของคุณหยุดรอไปแล้ว งานนั้นอาจยังคงทำงานอยู่ ดูเพิ่มเติมที่ Task Lifecycle

วิธีแก้ไข:

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

queue_timeout

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

วิธีแก้ไข: สร้างงานใหม่อีกครั้ง

format_conversion_failed

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

วิธีแก้ไข:

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

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

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