Lỗi

Tìm hiểu lý do một yêu cầu hoặc một tác vụ thất bại, và những việc cần làm tiếp theo. Một yêu cầu có thể thất bại ngay lập tức với lỗi HTTP, và một tác vụ có thể thất bại sau đó với một task_error.

Lỗi yêu cầu

Meshy trả về những lỗi này ngay lập tức, khi từ chối một yêu cầu. Để biết chuyện gì đã xảy ra, hãy kiểm tra mã trạng thái HTTP và trường message.

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

Task errors

Một tác vụ mà Meshy đã tạo vẫn có thể thất bại trong khi chạy. status của nó trở thành FAILED, Meshy hoàn lại tín dụng, và task_error giải thích lý do.

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

type là danh mục lỗi ở mức tổng quát. Hãy dùng nó để quyết định bước tiếp theo cần làm gì.

Mã lỗi

Khi có trường code, nó cho biết tên của một trong các vấn đề sau.

image_too_complex

Ảnh đầu vào hoặc prompt mô tả một chủ thể có hình học quá phức tạp để tạo mô hình 3D.

Ví dụ:

• Các chồng vật thể nhỏ dày đặc, chẳng hạn như một thùng đầy trái cây hoặc một chồng sách
• Các họa tiết lặp lại phức tạp, chẳng hạn như cấu trúc lưới mắt cáo, giàn giáo, hoặc lưới dây
• Các tòa nhà phức tạp, chẳng hạn như 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 ảnh, thay vì chỉ một chủ thể duy nhất

Các đầu vào sau đây có khả năng quá phức tạp:

Để khắc phục, hãy thử một hoặc nhiều cách sau:

• Chỉ sử dụng một vật thể cho mỗi ảnh. Meshy hoạt động tốt nhất với một chủ thể rõ ràng, vì vậy đừng đặt nhiều vật thể riêng biệt trong cùng một ảnh hoặc prompt.
• Đơn giản hóa chủ thể của bạn. Ví dụ, hãy dùng một chiếc bình hoa đơn giản thay vì một chiếc bình chứa đầy hàng chục bông hoa.
• Tránh các cảnh tổng thể. Toàn bộ tòa nhà, khu phố, phòng đầy nội thất, và phong cảnh có khả năng sẽ quá nhiều. Hãy tập trung vào một vật thể duy nhất.
• Tránh các cấu trúc lặp lại dày đặc. Giàn giáo, lưới dây, cấu trúc lưới mắt cáo, và các chồng vật nhỏ là những nguyên nhân phổ biến gây lỗi.

model_missing_uv

Bạn đã gửi một mô hình để tạo texture với enable_original_uv được đặt là true, nhưng mô hình này không có tọa độ UV. Tọa độ UV xác định cách một texture 2D bao bọc lên bề mặt 3D.

Để khắc phục, hãy thực hiện một trong những cách sau:

• Để giữ nguyên bố cục UV riêng của mô hình, ví dụ như để tùy chỉnh vị trí đường nối, hãy thêm UV cho mô hình trong phần mềm 3D của bạn. Kiểm tra chúng trong trình chỉnh sửa UV của phần mềm đó, sau đó tải mô hình lên lại. Tệp STL không thể lưu trữ UV, vì vậy hãy sử dụng GLB, FBX, hoặc OBJ.
• Nếu bạn không cần bố cục riêng, hoặc không chắc chắn, hãy bỏ qua enable_original_uv hoặc đặt nó là false. Khi đó Meshy sẽ tạo bố cục UV cho mô hình. Các UV mới sẽ bao phủ mô hình tốt, nhưng bạn sẽ không thể kiểm soát vị trí của các đường nối texture.

model_insufficient_uv

Model có tọa độ UV, nhưng chúng chỉ bao phủ một phần quá nhỏ trong không gian UV để có thể tạo texture tốt. Lỗi này thường xảy ra với các model mà công cụ xuất file đã ghi ra các UV giữ chỗ hoặc bị dồn lại mà không được trải (unwrap) đúng cách.

Để khắc phục, hãy thực hiện một trong các cách sau:

• Để giữ nguyên bố cục UV của riêng bạn, hãy trải (unwrap) lại tọa độ UV của model trong phần mềm 3D của bạn. Hãy dàn trải các đảo UV (island) ra khắp không gian UV thay vì chỉ gói gọn trong một góc nhỏ.
• Nếu bạn không cần bố cục UV riêng, hãy bỏ qua enable_original_uv hoặc đặt giá trị của nó thành false. Khi đó, Meshy sẽ tạo một bố cục UV mới. Bạn sẽ mất đi vị trí đường nối (seam) đã đặt, nhưng UV mới sẽ bao phủ đủ không gian để tạo texture.

model_missing_texture

Mô hình đầu vào của một tác vụ Multi-Color Print không có màu nào mà Meshy có thể tách thành các màu in. Meshy xây dựng một 3MF nhiều màu từ màu của mô hình, vì vậy một lưới trắng trơn sẽ không có gì để xử lý. Ví dụ, một bản xem trước Văn bản sang 3D hoặc Ảnh sang 3D chưa từng được tạo texture sẽ không có màu. Đầu ra của Sửa khả năng in, hoặc một tác vụ Auto Split không giữ lại texture, cũng vậy.

Thế nào được tính là màu 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 UV của mô hình. Nó cần một texture màu nền duy nhất, và UV trên mọi phần lưới.
• cartoon làm phẳng màu theo từng mặt. Nó 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).

Meshy từ chối một mô hình không có cả texture màu nền lẫn màu đỉnh cho cả hai kiểu, thay vì để cartoon biến nó thành bản in một màu.

Meshy từ chối hầu hết các yêu cầu này trước khi tạo tác vụ, với mã 400 và cùng một lời giải thích. Bạn thường chỉ gặp mã này khi Meshy không thể kiểm tra đầu vào trước. Ví dụ, Meshy chỉ kiểm tra tệp .fbx được tải lên sau khi tác vụ chuyển đổi nó.

Để khắc phục, hãy dùng tùy chọn phù hợp với mô hình của bạn:

• Tạo texture cho mô hình trước. Chạy Tạo lại texture trên mô hình đó, hoặc tạo nó bằng 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. Sau đó gửi tác vụ đó dưới dạng input_task_id.
• Đối với mô hình có màu đỉnh, chẳng hạn như quét trắc quang hoặc lưới được tô vẽ thủ công, hãy dùng style: "cartoon", vốn đọc COLOR_0.
• Đối với mô hình được tạo texture một phần hoặc có nhiều texture với realistic, hãy cung cấp UV cho mọi phần lưới cùng một texture màu nền duy nhất. Để làm điều đó, hãy tạo texture cho các phần còn lại, hoặc gộp các texture vào một atlas duy nhất. Bạn cũng có thể chuyển sang dùng style: "cartoon".

textured_split_refused

Một tác vụ Auto Split với keep_texture: true không thể giữ texture của mô hình đầu vào trên các bộ phận. Ví dụ, mô hình không có UV, hoặc texture của nó không có chỗ cho các mặt mới mà các vết cắt tạo ra. Meshy sẽ hoàn lại tín dụng.

Để khắc phục, hãy gửi lại yêu cầu mà không có keep_texture, hoặc với keep_texture: false. Khi đó các bộ phận sẽ được trả về với một màu đồng nhất cho mỗi phần.

invalid_input

Dữ liệu đầu vào không vượt qua một bước kiểm tra, và không có mã lỗi cụ thể nào khác phù hợp. message sẽ cho biết lý do.

Ví dụ:

• Một tệp mô hình trống hoặc bị hỏng
• Một biến thể không được hỗ trợ của định dạng tệp, chẳng hạn như tệp FBX dạng ASCII hoặc tệp GLB được nén bằng meshopt
• Một mô hình được tải lên không có đối tượng 3D hợp lệ nào, ví dụ một tệp chỉ chứa khung xương (armature), camera, hoặc ánh sáng
• Nội dung không vượt qua bộ lọc an toàn

Để khắc phục, hãy đọc message để biết vấn đề cụ thể. Kiểm tra xem các tệp đầu vào và tham số của bạn có đáp ứng yêu cầu của endpoint hay không.

moderation_blocked

Các bộ lọc an toàn đã từ chối prompt hoặc hình ảnh tham chiếu của bạn. Các bộ lọc kiểm tra văn bản và hình ảnh cùng nhau.

Để khắc phục, hãy thực hiện một hoặc cả hai cách sau:

• Diễn đạt lại prompt để loại bỏ các mô tả gợi dục hoặc nhạy cảm.
• Thay đổi hình ảnh tham chiếu có chứa nội dung mà bộ lọc có thể chặn.

moderation_unavailable

Loại: server_error. Chức năng moderation nội dung tạm thời không khả dụng, nên Meshy đã làm cho tác vụ thất bại thay vì bỏ qua việc kiểm tra. Nội dung của bạn không có vấn đề gì.

Để khắc phục, hãy tạo lại tác vụ.

timeout

Tác vụ đã chạy quá giới hạn thời gian phía máy chủ, dù là để xử lý hay để chờ trong hàng đợi, nên Meshy đã đánh dấu tác vụ đó là thất bại và hoàn lại tín dụng. Tình trạng này có thể xảy ra do tải cao, hoặc do đầu vào quá phức tạp để hoàn thành kịp thời.

Đ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 Nên chờ bao lâu.

Để khắc phục, hãy làm theo các bước sau:

1. Tạo lại tác vụ. Các lỗi timeout thường chỉ là tạm thời, và một tác vụ mới có thể sẽ thành công.
2. Nếu lỗi vẫn tiếp diễn, hãy đơn giản hóa đầu vào của bạn, ví dụ bằng cách giảm bớt chi tiết trong hình ảnh hoặc prompt. Đối với các đầu vào khó xử lý hơn, xem image_too_complex.

queue_timeout

Loại: timeout. Tác vụ đã chờ trong hàng đợi quá lâu mà không được bắt đầu, vì vậy Meshy đã đánh dấu tác vụ là thất bại và hoàn lại mọi tín dụng đã tính phí cho tác vụ đó. Đầu vào của bạn không phải là nguyên nhân gây ra lỗi này.

Để khắc phục, hãy tạo lại tác vụ.

format_conversion_failed

Meshy đã tạo ra mô hình, nhưng việc chuyển đổi mô hình đó sang định dạng bạn yêu cầu đã thất bại.

Để khắc phục, hãy làm theo các bước sau:

1. Tạo lại tác vụ.
2. Nếu một định dạng cứ liên tục thất bại, hãy yêu cầu một định dạng khác phù hợp với nhu cầu của bạn.

Best practices

• Thử lại các tác vụ thất bại. Đối với một tác vụ thất bại với timeout, service_unavailable, hoặc server_error, hãy tạo một tác vụ mới với cơ chế exponential backoff.
• Đừng tạo tác vụ mới khi chính yêu cầu của bạn bị timeout. Tác vụ đầu tiên có thể vẫn đang chạy, vì vậy hãy kiểm tra xem nó có tồn tại hay không trước khi tạo một tác vụ khác. Xem Cần chờ bao lâu.
• Ghi lại ID tác vụ. Hãy bao gồm ID này khi bạn liên hệ với bộ phận hỗ trợ.
• Kiểm tra dữ liệu đầu vào trước khi gửi. Đảm bảo hình ảnh và mô hình đáp ứng các yêu cầu về định dạng của endpoint.
• Gọi API từ máy chủ của bạn. Mã chạy trong trình duyệt sẽ để lộ khóa API của bạn cho bất kỳ ai mở trang đó.