ข้อผิดพลาด

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

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

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

รูปแบบการตอบกลับ

การตอบกลับข้อผิดพลาดประกอบด้วยฟิลด์ message เพียงฟิลด์เดียวที่อธิบายว่าเกิดข้อผิดพลาดอะไรขึ้น:

  • Name
    message
    Type
    string
    Description

    คำอธิบายสั้น ๆ เกี่ยวกับข้อผิดพลาด

รหัสสถานะ

  • Name
    2xx
    Description

    รหัสสถานะ 2xx บ่งบอกว่าการตอบกลับสำเร็จ

    • Name
      200 - OK
      Description

      โดยค่าเริ่มต้น หากทุกอย่างทำงานตามที่คาดไว้ จะส่งกลับรหัสสถานะ 200

    • Name
      202 - Accepted
      Description

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

  • Name
    4xx
    Description

    รหัสสถานะ 4xx บ่งบอกว่าเกิดข้อผิดพลาดจากฝั่งไคลเอนต์

    • Name
      400 - Bad Request
      Description

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

    • Name
      401 - Unauthorized
      Description

      ไม่มีการระบุ API คีย์ที่ถูกต้อง หรือ API คีย์ที่ระบุไม่มีสิทธิ์เข้าถึงเอนด์พอยต์ของ Meshy API

    • Name
      402 - Payment Required
      Description

      มีเงินในบัญชีที่เชื่อมโยงกับ API คีย์ที่ระบุไม่เพียงพอ

    • Name
      403 - Forbidden
      Description

      การเข้าถึงทรัพยากรที่ร้องขอถูกปฏิเสธ ซึ่งอาจเกิดขึ้นหากคุณพยายามเข้าถึง Meshy API โดยตรงจากโค้ด JavaScript ฝั่งไคลเอนต์ เนื่องจากไม่อนุญาตให้มีการร้องขอ Cross-Origin Resource Sharing (CORS) จากเบราว์เซอร์ ลองพิจารณาใช้พร็อกซีฝั่งเซิร์ฟเวอร์สำหรับคำขอลักษณะนี้ ดูรายละเอียดเพิ่มเติมได้ที่ MDN CORS guide

    • Name
      404 - Not Found
      Description

      ทรัพยากรที่ร้องขอไม่มีอยู่ ตัวอย่างเช่น เมื่อคุณพยายามดึงข้อมูลงานด้วย ID แต่ระบุ ID ที่ไม่ถูกต้อง คุณจะได้รับรหัสสถานะ 404

    • Name
      409 - Conflict
      Description

      ทรัพยากรมีอยู่จริง แต่สถานะปัจจุบันไม่อนุญาตให้ดำเนินการดังกล่าว ตัวอย่างเช่น การลบงานที่มีสถานะ IN_PROGRESS อยู่แล้วจะส่งกลับ 409: เนื่องจาก worker ได้เริ่ม ทำงานไปแล้วซึ่งไม่สามารถคืนเงินได้ ดังนั้นงานจะยังคงทำงานต่อไปแทนที่จะถูกยกเลิก โปรดรอจนกว่าจะถึงสถานะสุดท้าย (SUCCEEDED, FAILED หรือ CANCELED) แล้วลองใหม่

    • Name
      429 - Too Many Requests
      Description

      มีคำขอเข้ามายัง Meshy API เร็วเกินไปในจำนวนที่มากเกินไป โปรดดูรายละเอียดเพิ่มเติมได้ที่คู่มือ Rate Limits

  • Name
    5xx
    Description

    รหัสสถานะ 5xx บ่งบอกว่าเกิดข้อผิดพลาดจากฝั่งเซิร์ฟเวอร์ หากคุณพบข้อผิดพลาดนี้ โปรดตรวจสอบหน้าสถานะของเรา สำหรับข้อมูลเพิ่มเติม และติดต่อเราผ่านทาง Discord เพื่อขอความช่วยเหลือ

Example: 400 Bad Request

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

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

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

วัตถุ task_error ประกอบด้วยฟิลด์ต่อไปนี้:

  • Name
    type
    Type
    string
    Description

    หมวดหมู่ของข้อผิดพลาด มีอยู่เสมอในงานที่ล้มเหลว ดู ประเภทข้อผิดพลาด ด้านล่าง

  • Name
    message
    Type
    string
    Description

    คำอธิบายข้อผิดพลาดที่มนุษย์สามารถอ่านได้ มีอยู่เสมอในงานที่ล้มเหลว

  • Name
    code
    Type
    string
    ไม่บังคับ
    Description

    รหัสข้อผิดพลาดเฉพาะที่ระบุปัญหา มีอยู่เมื่อมีรายละเอียดเพิ่มเติม ดู รหัสข้อผิดพลาด ด้านล่าง

  • Name
    doc_url
    Type
    string
    ไม่บังคับ
    Description

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

Error with details

{
  "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"
  }
}

Error without details

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

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

ฟิลด์ type บอกคุณถึงประเภทกว้างๆ ของความล้มเหลว ใช้เพื่อกำหนดกลยุทธ์การลองใหม่ของคุณ

  • Name
    invalid_input
    Description

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

  • Name
    timeout
    Description

    การประมวลผลเกินขีดจำกัดเวลา ซึ่งมักจะเป็นปัญหาชั่วคราว ลองส่งคำขอใหม่ และหากยังคงล้มเหลว ให้ลองทำให้ข้อมูลของคุณง่ายขึ้น

  • Name
    service_unavailable
    Description

    บริการไม่พร้อมใช้งานชั่วคราว รอสักครู่แล้วลองใหม่

  • Name
    server_error
    Description

    เกิดข้อผิดพลาดภายในระหว่างการประมวลผล ลองส่งคำขอใหม่ หากปัญหายังคงอยู่ ติดต่อฝ่ายสนับสนุนพร้อมกับ ID งานของคุณ

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

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

image_too_complex

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

ตัวอย่างทั่วไปได้แก่:

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

ตัวอย่างของข้อมูลที่อาจซับซ้อนเกินไป:

ลังที่เต็มไปด้วยเบอร์รี่หลากชนิดเพดานโบสถ์ที่ซับซ้อนอาคารที่กำลังก่อสร้างพร้อมนั่งร้านทรงกลมตาข่ายรังผึ้ง

วิธีแก้ไข:

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

model_missing_uv

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

No UVs vs Good UVs

การแก้ไข:

การแก้ไขที่ถูกต้องขึ้นอยู่กับเหตุผลที่คุณตั้งค่า 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 ชั่วคราวหรือยุบโดยไม่มีการคลี่ออกอย่างเหมาะสม

Insufficient UVs vs Good UVs

การแก้ไข:

  • หากคุณต้องการรักษาเลย์เอาต์ 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 ของคุณเพื่อลบคำอธิบายที่ส่อเสียดหรืออ่อนไหว
  • ปรับภาพอ้างอิงหากมีเนื้อหาที่อาจกระตุ้นตัวกรองความปลอดภัย

timeout

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

วิธีแก้ไข:

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

format_conversion_failed

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

การแก้ไข:

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

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

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