ข้อผิดพลาด

ค้นหาสาเหตุที่คำขอหรือภารกิจล้มเหลว และขั้นตอนต่อไปที่ควรทำ คำขออาจล้มเหลวได้ทันทีด้วยข้อผิดพลาด HTTP และภารกิจอาจล้มเหลวในภายหลังด้วย task_error

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

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

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

ข้อผิดพลาดของงาน (Task errors)

งานที่ Meshy สร้างขึ้นอาจล้มเหลวได้แม้ในขณะที่กำลังทำงาน โดย status ของงานจะเปลี่ยนเป็น FAILED และ Meshy จะคืนเครดิตให้ พร้อมทั้ง 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."
  }
}

Error types

type คือหมวดหมู่กว้างๆ ของความล้มเหลว ใช้มันเพื่อตัดสินใจว่าจะทำอย่างไรต่อไป

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

เมื่อมี code ปรากฏอยู่ แสดงว่าเป็นหนึ่งในปัญหาต่อไปนี้

image_too_complex

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

ตัวอย่างเช่น:

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

ข้อมูลนำเข้าเหล่านี้มีแนวโน้มที่จะซับซ้อนเกินไป:

หากต้องการแก้ไข ให้ลองทำตามวิธีใดวิธีหนึ่งหรือหลายวิธีต่อไปนี้:

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

model_missing_uv

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

วิธีแก้ไข ให้ทำอย่างใดอย่างหนึ่งต่อไปนี้:

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

model_insufficient_uv

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

วิธีแก้ไขให้ทำอย่างใดอย่างหนึ่งต่อไปนี้:

• หากต้องการคงเลย์เอาต์ UV ของคุณเอง ให้คลี่ (unwrap) พิกัด UV ของโมเดลใหม่ในโปรแกรม 3D ของคุณ โดยกระจายกลุ่มชิ้นส่วน (islands) ให้ทั่วพื้นที่ของ UV แทนที่จะอยู่เพียงมุมเล็ก ๆ ของพื้นที่นั้น
• หากคุณไม่จำเป็นต้องใช้เลย์เอาต์ของตัวเอง ให้ไม่ใส่ enable_original_uv หรือกำหนดค่าเป็น false จากนั้น Meshy จะสร้างเลย์เอาต์ UV ใหม่ให้ คุณจะเสียตำแหน่งตะเข็บ (seam) เดิมไป แต่พิกัด UV ใหม่จะครอบคลุมพื้นที่เพียงพอสำหรับการลงเท็กซ์เจอร์

model_missing_texture

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

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

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

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

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

วิธีแก้ไข ให้ใช้ตัวเลือกที่เหมาะกับโมเดลของคุณ:

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

textured_split_refused

งาน Auto Split ที่มี keep_texture: true ไม่สามารถคงเท็กซ์เจอร์ของโมเดลต้นฉบับไว้บนชิ้นส่วนต่างๆ ได้ ตัวอย่างเช่น โมเดลไม่มี UV หรือเท็กซ์เจอร์ของโมเดลไม่มีพื้นที่เหลือสำหรับหน้าตัดใหม่ที่เกิดจากการตัด Meshy จะคืนเครดิตให้

วิธีแก้ไข ให้ส่งคำขออีกครั้งโดยไม่ใส่ keep_texture หรือใส่ keep_texture: false จากนั้นชิ้นส่วนต่างๆ จะถูกส่งกลับมาโดยแต่ละชิ้นมีสีพื้นเรียบ

invalid_input

อินพุตไม่ผ่านการตรวจสอบ และไม่มีรหัสที่เจาะจงกว่านี้ที่ใช้ได้ message จะระบุเหตุผล

ตัวอย่างเช่น

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

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

moderation_blocked

ตัวกรองความปลอดภัยปฏิเสธ prompt หรือภาพอ้างอิงของคุณ ตัวกรองจะตรวจสอบข้อความและภาพร่วมกัน

หากต้องการแก้ไข ให้ทำอย่างใดอย่างหนึ่งหรือทั้งสองอย่างต่อไปนี้:

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

moderation_unavailable

ประเภท: server_error ระบบ moderation เนื้อหาไม่สามารถใช้งานได้ชั่วคราว ทำให้ Meshy ทำให้งานล้มเหลวแทนที่จะข้ามการตรวจสอบ เนื้อหาของคุณไม่มีปัญหาแต่อย่างใด

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

timeout

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

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

วิธีแก้ไขมีดังนี้:

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

queue_timeout

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

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

format_conversion_failed

Meshy สร้างโมเดลสำเร็จแล้ว แต่การแปลงเป็นรูปแบบที่คุณร้องขอล้มเหลว

วิธีแก้ไข ให้ทำตามขั้นตอนต่อไปนี้:

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

แนวปฏิบัติที่ดี

• ลองใหม่สำหรับงานที่ล้มเหลว สำหรับงานที่ล้มเหลวด้วย timeout, service_unavailable, หรือ server_error ให้สร้างงานใหม่โดยใช้ exponential backoff
• อย่าสร้างงานใหม่เมื่อคำขอของคุณเองหมดเวลา งานแรกอาจยังทำงานอยู่ ดังนั้นควรตรวจสอบว่ามีอยู่หรือไม่ก่อนที่จะสร้างงานอื่น ดูที่ ควรรอนานแค่ไหน
• บันทึก task ID ไว้ รวม ID นี้ไว้เมื่อคุณติดต่อฝ่ายสนับสนุน
• ตรวจสอบข้อมูลนำเข้าก่อนที่จะส่ง ตรวจสอบให้แน่ใจว่ารูปภาพและโมเดลตรงตามข้อกำหนดด้านรูปแบบของเอนด์พอยต์
• เรียกใช้ API จากเซิร์ฟเวอร์ของคุณ โค้ดที่ทำงานในเบราว์เซอร์จะเปิดเผย API คีย์ของคุณให้กับทุกคนที่เปิดหน้าเพจนั้น