Lỗi

Trong hướng dẫn này, chúng ta sẽ nói về những gì xảy ra khi có sự cố xảy ra trong khi 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 Nhiệm Vụ

Những lỗi này xảy ra sau khi một nhiệm vụ đã được tạo và đang xử lý. Kiểm tra đối tượng task_error trong phản hồi nhiệm 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 sự cố. Sử dụng nó để 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, nó xác định một vấn đề cụ thể có thể hành động được. Dưới đây là tham chiếu đầy đủ cho mỗi 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 đối tượng 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:

• Đống nhỏ các vật thể dày đặc (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 lưới, giàn giáo, lưới dây)
• Cấu trúc tòa nhà phức tạp (ví dụ, các tòa nhà nhiều tầng với nhiều cửa sổ và ban công)
• Nhiều đối tượng riêng biệt trong một hình ảnh thay vì một đối tượng duy nhất

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

Giải pháp:

1. Sử dụng một đối tượng duy nhất cho mỗi hình ảnh. Mô hình hoạt động tốt nhất với một đối tượng rõ ràng. Không bao gồm nhiều đối tượng riêng biệt trong cùng một hình ảnh hoặc prompt.
2. Đơn giản hóa đối tượng 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 đầy hoa.
3. Tránh các prompt cấp cảnh. Các tòa nhà hoàn chỉnh, khu phố, nội thất đầy đủ đồ nội thất, hoặc phong cảnh có khả năng vượt quá khả năng của mô hình. Tập trung vào một đối tượng duy nhất.
4. Tránh các cấu trúc lặp lại dày đặc. Các đối tượng như giàn giáo, lưới dây, mẫu lưới, hoặc đống nhiều vật nhỏ là các tác nhân 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 để áp dụng 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ủa bạn.

Giải pháp:

Cách khắc phục đúng 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ụ, đặt đườ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ệ. Xác minh rằng UV tồn tại trong trình chỉnh sửa UV của phần mềm 3D của bạn 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 chắn): bỏ qua enable_original_uv hoặc đặt nó thành false. Hệ thống sẽ tự động tạo một 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 độ phủ nhưng bạn sẽ không có quyền kiểm soát vị trí đặt các đường nối texture.

model_insufficient_uv

Lỗi này xảy ra khi một mô hình có tọa độ UV, nhưng phạm vi UV quá nhỏ để tạo kết cấu chất lượng. Điều này thường xảy ra với các mô hình được xuất từ các công cụ 3D tạo ra các UV tạm thời hoặc bị sụp đổ mà không có một bố cục UV đúng cách.

Giải pháp:

• Nếu bạn cần giữ nguyên bố cục UV gốc của mình: mở lại UV của mô hình trong phần mềm 3D của bạn. Đảm bảo các đảo UV được trải đều trên không gian UV thay vì bị sụp đổ vào một khu vực nhỏ.
• Nếu bạn không cần kiểm soát UV cụ thể: bỏ qua enable_original_uv hoặc đặt nó thành false. Hệ thống sẽ tự động tạo ra một bố cục UV mới. Sự đánh đổi là bạn sẽ mất vị trí đường may gốc của mình, nhưng các UV được tạo tự động sẽ có phạm vi phù hợp cho việc tạo kết cấu.

invalid_input

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

Những nguyên nhân phổ biến 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 nén 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 khung xương, máy ảnh, hoặc đèn)
• Nội dung không vượt qua các bộ lọc an toàn

Giải pháp: Kiểm tra trường message để biết chi tiết về vấn đề đã xảy ra. Xác minh rằng các tệp đầu vào và tham số của bạn phù hợ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ị từ chối bởi các bộ lọc an toàn AI. Bộ lọc đánh giá cả prompt văn bản và bất kỳ hình ảnh tham chiếu nào cùng nhau.

Cách giải quyết:

• 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 các bộ lọc an toàn.

timeout

Lỗi này có nghĩa là thời gian xử lý nhiệm 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 do đầu vào quá phức tạp để xử lý trong giới hạn thời gian.

Cách giải quyết:

1. Thử lại yêu cầu. Lỗi timeout thường là tạm thời và thử lại có thể thành công.
2. Đơn giản hóa đầu vào của bạn. Nếu thử lại liên 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ề các 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 được tạo không thể 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.

Giải pháp:

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ể liên 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.

Thực hành tốt nhất

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