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 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. Hãy 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."
  }
}

Loại lỗi

Trường type cho bạn biết danh mục lỗi tổng quát. Hãy dùng nó để quyết định chiến lược thử lại.

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.

model_missing_texture

Lỗi này xảy ra khi mô hình đầu vào của một tác vụ Multi-Color Print không có thông tin màu sắc nào mà trình chuyển đổi có thể tách thành các màu in. Một tệp 3MF in nhiều màu được xây dựng từ màu sắc của mô hình, vì vậy một lưới màu trắng đơn thuần — ví dụ như một bản preview Văn bản sang 3D hoặc Ảnh sang 3D chưa từng được tạo texture, hoặc một đầu ra đã được sửa chữa / tự động tách — sẽ không có gì để xử lý.

Điều gì được tính là nguồn màu sắc phụ thuộc vào style mà bạn đã yêu cầu:

• realistic lấy mẫu texture màu nền thông qua tọa độ UV của mô hình, vì vậy nó yêu cầu một texture màu nền duy nhất có tọa độ UV trên mọi phần của lưới.
• cartoon làm phẳng màu sắc theo từng mặt và chấp nhận texture màu nền trên bất kỳ phần nào hoặc màu theo từng đỉnh (COLOR_0).

Một mô hình không có cả texture màu nền lẫn màu theo đỉnh sẽ bị từ chối đối với cả hai style; với cartoon, nếu không thì nó sẽ "thành công" như một bản in đơn sắc.

Hầu hết các yêu cầu bị từ chối trước khi tác vụ được tạo (400 Bad Request kèm cùng lời giải thích), vì vậy bạn thường chỉ thấy mã lỗi này khi đầu vào không thể được kiểm tra trước — ví dụ, một tệp tải lên .fbx được kiểm tra sau khi tác vụ đã chuẩn hóa nó.

Cách khắc phục:

• Tạo texture cho mô hình trước. Chạy một tác vụ Tạo lại texture trên mô hình đó, hoặc tạo mô hình với tính năng tạo texture được bật (một tác vụ refine của Văn bản sang 3D, hoặc một tác vụ Ảnh sang 3D với should_texture: true), rồi truyền tác vụ đó vào input_task_id.
• Mô hình có màu theo đỉnh (bản quét photogrammetry, lưới được tô màu thủ công): yêu cầu style: "cartoon", vốn đọc COLOR_0.
• Mô hình được tạo texture một phần hoặc có nhiều texture dưới realistic: mọi phần của lưới đều cần tọa độ UV và cùng một texture màu nền duy nhất. Hãy tạo texture cho các phần còn lại hoặc hợp nhất các texture thành một atlas duy nhất, hoặc chuyển sang style: "cartoon".

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ị bộ lọc an toàn AI từ chối. Bộ lọc đánh giá đồng thời cả prompt văn bản lẫn mọi hình ảnh tham chiếu.

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 dục 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.

moderation_unavailable

Lỗi này xảy ra khi hệ thống moderation nội dung tạm thời không khả dụng, do đó tác vụ bị đánh dấu là lỗi thay vì chạy mà không qua kiểm tra. Không có vấn đề gì với nội dung của bạn. Loại (type) của lỗi này là server_error.

Cách khắc phục: Tạo lại tác vụ.

timeout

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

Điều này khác với timeout trong code của riêng bạn. Nếu client của bạn ngừng chờ, tác vụ vẫn đang chạy; xem Vòng đời tác vụ.

Cách khắc phục:

1. Tạo lại tác vụ. Timeout thường chỉ là tạm thời và một tác vụ mớ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 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 để biết hướng dẫn về những loại đầu vào nào khó xử lý hơn.

queue_timeout

Lỗi này có nghĩa là tác vụ đã chờ trong hàng đợi quá lâu mà không bắt đầu, nên nó đã thất bại và mọi tín dụng đã tính phí cho nó đều được hoàn lại. Dữ liệu đầu vào của bạn không phải là nguyên nhân gây ra lỗi này. type của nó là timeout.

Cách khắc phục: Tạo lại tác vụ.

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 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ể 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.

Best Practices

1. Triển khai logic thử lại. Khi một tác vụ thất bại với lỗi timeout, service_unavailable hoặc server_error, hãy tạo lại tác vụ đó với cơ chế exponential backoff. Nếu chính yêu cầu của bạn bị timeout, đừng tạo tác vụ mới: hãy kiểm tra tác vụ hiện có trước (xem Task Lifecycle).
2. Ghi lại task ID. Luôn ghi lại task ID để phục vụ việc gỡ lỗi. Hãy đính kèm nó 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 và mô hình đầu vào của bạn đáp ứng các yêu cầu về định dạng trước khi gửi.
4. Gọi API từ máy chủ của bạn. Mã chạy trong trình duyệt sẽ làm lộ khóa API của bạn cho bất kỳ ai mở trang đó.