Lỗi

Trong hướng dẫn này, chúng ta sẽ nói về điều gì xảy ra khi có sự cố trong lúc bạn làm việc với Meshy API.

Lỗi yêu cầu

Những lỗi này được trả về ngay lập tức khi yêu cầu API của bạn bị từ chối. Kiểm tra mã trạng thái HTTP và trường message để hiểu điều gì đã xảy ra.

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

Lỗi tác vụ

Những lỗi này xảy ra sau khi một tác vụ đã được tạo và đang được xử lý. Kiểm tra đối tượng task_error trong phản hồi tác vụ để biết chi tiết lỗi.

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

Các loại lỗi

Trường type cho bạn biết danh mục chung của lỗi. Sử dụng trường này để quyết định chiến lược thử lại của bạn.

Mã lỗi

Khi trường code xuất hiện, trường này xác định một vấn đề cụ thể, có thể hành động. Dưới đây là tài liệu tham khảo đầy đủ cho từng mã lỗi.

image_too_complex

Lỗi này xảy ra khi hình ảnh đầu vào hoặc prompt mô tả một chủ thể quá phức tạp về mặt hình học để mô hình tạo 3D có thể xử lý.

Các ví dụ phổ biến bao gồm:

• Các đống dày đặc gồm nhiều vật thể nhỏ (ví dụ: một thùng đầy trái cây, một chồng sách)
• Các mẫu lặp lại phức tạp (ví dụ: cấu trúc dạng lưới, giàn giáo, lưới dây)
• Các cấu trúc tòa nhà phức tạp (ví dụ: tòa nhà nhiều tầng với nhiều cửa sổ và ban công)
• Nhiều vật thể riêng biệt trong một hình ảnh thay vì một chủ thể duy nhất

Ví dụ về các đầu vào có khả năng quá phức tạp:

Cách khắc phục:

1. Sử dụng một vật thể duy nhất cho mỗi hình ảnh. Mô hình hoạt động tốt nhất với một chủ thể rõ ràng. Đừng đưa nhiều vật thể tách biệt vào cùng một hình ảnh hoặc prompt.
2. Đơn giản hóa chủ thể của bạn. Giảm mức độ chi tiết. Ví dụ: một chiếc bình đơn giản thay vì một chiếc bình chứa hàng chục bông hoa.
3. Tránh các prompt ở cấp độ cảnh. Toàn bộ tòa nhà, các dãy phố, nội thất chứa đầy đồ đạc hoặc phong cảnh có khả năng vượt quá khả năng của mô hình. Thay vào đó, hãy tập trung vào một vật thể duy nhất.
4. Tránh các cấu trúc lặp lại dày đặc. Các chủ thể như giàn giáo, lưới dây, mẫu dạng lưới hoặc các đống gồm nhiều vật nhỏ là những nguyên nhân kích hoạt phổ biến.

model_missing_uv

Lỗi này xảy ra khi bạn tải lên một mô hình để tạo texture với enable_original_uv được đặt thành true, nhưng mô hình không có tọa độ UV. Tọa độ UV xác định cách một texture 2D bao phủ lên bề mặt 3D của mô hình.

Cách khắc phục:

Cách khắc phục phù hợp phụ thuộc vào lý do bạn đặt enable_original_uv thành true:

• Nếu bạn cần giữ nguyên bố cục UV gốc của mô hình (ví dụ: vị trí đường nối tùy chỉnh để ánh xạ texture chính xác): mô hình của bạn phải có tọa độ UV hợp lệ. Hãy xác minh UV tồn tại trong trình chỉnh sửa UV của phần mềm 3D trước khi tải lên. Lưu ý rằng các tệp STL không thể lưu trữ dữ liệu UV, vì vậy hãy sử dụng GLB, FBX hoặc OBJ thay thế.
• Nếu bạn không cần kiểm soát UV cụ thể (hoặc bạn không chắc): bỏ qua enable_original_uv hoặc đặt nó thành false. Hệ thống sẽ tự động tạo bố cục UV cho mô hình của bạn. Các UV được tạo tự động được tối ưu hóa cho độ bao phủ, nhưng bạn sẽ không kiểm soát được vị trí đặt các đường nối texture.

model_insufficient_uv

Lỗi này xảy ra khi một model có tọa độ UV, nhưng độ phủ UV quá nhỏ để tạo texture chất lượng. Điều này thường xảy ra với các model được xuất từ các công cụ 3D tạo UV giữ chỗ hoặc UV bị thu gọn mà không unwrap đúng cách.

Cách khắc phục:

• Nếu bạn cần giữ nguyên bố cục UV ban đầu: unwrap lại UV của model trong phần mềm 3D của bạn. Đảm bảo các UV island được phân bố đúng cách trên không gian UV thay vì bị thu gọn vào một vùng nhỏ.
• Nếu bạn không cần kiểm soát UV cụ thể: bỏ qua enable_original_uv hoặc đặt thành false. Hệ thống sẽ tự động tạo bố cục UV mới. Đánh đổi là bạn sẽ mất vị trí seam ban đầu, nhưng UV được tạo tự động sẽ có độ phủ phù hợp để tạo texture.

invalid_input

Đây là mã lỗi dự phòng khi đầu vào không vượt qua xác thực nhưng không có mã cụ thể hơn nào áp dụng. Trường message chứa lý do cụ thể của lỗi.

Các nguyên nhân thường gặp bao gồm:

• Tệp mô hình trống hoặc bị hỏng
• Các biến thể định dạng tệp không được hỗ trợ (ví dụ: tệp ASCII FBX, GLB được nén bằng meshopt)
• Không tìm thấy đối tượng 3D hợp lệ nào trong mô hình đã tải lên (ví dụ: tệp chỉ chứa armature, camera hoặc đèn)
• Nội dung không vượt qua các bộ lọc an toàn

Cách khắc phục: Kiểm tra trường message để biết chi tiết cụ thể về sự cố đã xảy ra. Xác minh rằng các tệp đầu vào và tham số của bạn khớp với yêu cầu của endpoint.

moderation_blocked

Lỗi này xảy ra khi prompt hoặc hình ảnh tham chiếu của bạn bị bộ lọc an toàn AI từ chối. Bộ lọc đánh giá cả prompt văn bản và mọi hình ảnh tham chiếu cùng nhau.

Cách khắc phục:

• Diễn đạt lại prompt văn bản của bạn để loại bỏ các mô tả gợi ý hoặc nhạy cảm.
• Điều chỉnh hình ảnh tham chiếu nếu chúng mô tả nội dung có thể kích hoạt bộ lọc an toàn.

timeout

Lỗi này có nghĩa là thời gian xử lý tác vụ của bạn đã vượt quá giới hạn cho phép. Điều này có thể xảy ra do tải hệ thống cao hoặc vì đầu vào quá phức tạp để xử lý trong giới hạn thời gian.

Cách khắc phục:

1. Thử lại yêu cầu. timeout thường chỉ là tạm thời và việc thử lại có thể thành công.
2. Đơn giản hóa đầu vào của bạn. Nếu việc thử lại tiếp tục thất bại, đầu vào của bạn có thể quá phức tạp. Hãy thử giảm mức độ chi tiết trong hình ảnh hoặc prompt của bạn. Xem image_too_complex để được hướng dẫn về những loại đầu vào khó xử lý hơn.

format_conversion_failed

Lỗi này xảy ra khi mô hình 3D đã tạo không thể được chuyển đổi sang định dạng đầu ra mà bạn yêu cầu. Mô hình đã được tạo thành công, nhưng bước chuyển đổi đã thất bại.

Cách khắc phục:

1. Thử lại yêu cầu.
2. Thử một định dạng đầu ra khác. Nếu một định dạng cụ thể tiếp tục thất bại, hãy chuyển sang định dạng khác phù hợp với nhu cầu của bạn.

Các phương pháp hay nhất

1. Triển khai logic thử lại. Đối với các lỗi timeout và service_unavailable, hãy triển khai logic thử lại với thời gian chờ tăng theo cấp số nhân.
2. Ghi lại ID tác vụ. Luôn ghi lại ID tác vụ cho mục đích gỡ lỗi. Bao gồm ID này khi liên hệ với bộ phận hỗ trợ.
3. Xác thực đầu vào. Đảm bảo hình ảnh đầu vào và mô hình của bạn đáp ứng các yêu cầu về định dạng trước khi gửi.