Retexture API

Bắt buộc trừ khi bạn gửi model_url. ID của một tác vụ đã tạo ra mô hình 3D cần tạo texture, ví dụ như tác vụ Văn bản sang 3D, Ảnh sang 3D, Remesh, hoặc Tạo lại texture. Tác vụ đó phải do bạn tạo bằng API và có trạng thái SUCCEEDED. Meshy sẽ tạo texture cho file GLB của tác vụ đó.

Với meshy-n1, mô hình của tác vụ có thể có tối đa 7.999.999 mặt, tính theo số tam giác (một mặt tứ giác được tính là 2).

Bắt buộc trừ khi bạn gửi input_task_id. Mô hình cần tạo texture, dưới dạng URL công khai hoặc data URI. Nếu bạn gửi cả hai, Meshy sẽ sử dụng input_task_id.

Mô hình phải là một file GLB, glTF, OBJ, FBX, hoặc STL có dung lượng tối đa 400 MB từ một URL http hoặc https, hoặc 100 MB nếu là data URI. Đối với data URI, hãy sử dụng MIME type application/octet-stream, ví dụ data:application/octet-stream;base64,<dữ liệu mô hình mã hóa base64 của bạn>.

File có dung lượng trên 100 MB cũng phải tuân theo các quy tắc sau:

• File GLB, glTF, FBX, hoặc OBJ có thể có tối đa 10.000.000 mặt. Meshy tính mặt theo số tam giác, do đó một mặt tứ giác được tính là 2, và một lưới được vẽ nhiều lần sẽ được tính một lần cho mỗi bản sao.
• File FBX phải là FBX nhị phân phiên bản 7.1 trở lên.
• File GLB hoặc glTF không được sử dụng nén Draco.

Với meshy-n1, mô hình có thể có tối đa 7.999.999 mặt, tính theo số tam giác (một mặt tứ giác được tính là 2), bất kể dung lượng file.

Bắt buộc trừ khi bạn gửi image_style_url hoặc multiview_image_urls. Văn bản mô tả texture bạn muốn, tối đa 800 ký tự. Văn bản dài hơn sẽ trả về 400. Với meshy-n1, gửi tham số này mà không có image_style_url sẽ trả về 400.

Bắt buộc trừ khi bạn gửi text_style_prompt hoặc multiview_image_urls. Một hình ảnh 2D có phong cách mà texture sẽ tuân theo, dưới dạng URL công khai hoặc data URI (data:image/jpeg;base64,<dữ liệu hình ảnh mã hóa base64 của bạn>). Nếu bạn gửi cả text_style_prompt và image_style_url, Meshy sẽ sử dụng image_style_url.

Hình ảnh phải là file .jpg, .jpeg, .png, hoặc .webp có dung lượng tối đa 20 MB, và kích thước tối thiểu 32 pixel mỗi cạnh.

Texture có thể không khớp tốt khi đối tượng trong hình ảnh có hình dạng rất khác so với mô hình. Với meshy-n1, Meshy sẽ coi hình ảnh đó là góc nhìn từ phía trước.

Bắt buộc trừ khi bạn gửi text_style_prompt hoặc image_style_url. Một đến bốn hình ảnh của cùng một đối tượng từ các góc nhìn khác nhau. Hình ảnh đầu tiên là góc nhìn chính (phía trước). Thứ tự của các góc nhìn khác (trái, sau, phải) không quan trọng. Một mảng rỗng, hoặc nhiều hơn bốn hình ảnh, sẽ trả về 400.

Mỗi hình ảnh tuân theo cùng định dạng và quy tắc kích thước như image_style_url, tối đa 20 MB mỗi hình ảnh. Bạn không thể kết hợp multiview_image_urls với text_style_prompt hoặc image_style_url.

multiview_image_urls cần một ai_model rõ ràng là meshy-7 hoặc meshy-n1. Bất kỳ ai_model nào khác, kể cả giá trị mặc định latest, sẽ trả về 400.

Mô hình AI tạo ra texture.

Các giá trị khả dụng:

• meshy-6-lite
• meshy-6
• meshy-7
• meshy-n1: một texture màu nền 2K chỉ từ các hình ảnh tham chiếu. Không có prompt văn bản, không có bản đồ PBR, không có 4K hoặc 8K. Tối đa 7.999.999 mặt.
• latest: Meshy 7

Có giữ bố cục UV của mô hình thay vì tạo một bố cục mới hay không.

• Đối với một mô hình do Meshy tạo ra, từ input_task_id hoặc một model_url trỏ đến đầu ra của Meshy, hãy dùng true để tái sử dụng bố cục UV đã được tối ưu hóa của nó.
• Đối với một mô hình bạn tải lên từ nơi khác, hãy dùng true để giữ UV đã sẵn tốt. Để false để Meshy tạo UV mới, phù hợp với mô hình chưa có ánh xạ UV hợp lý.

Có tạo thêm bản đồ PBR (metallic, roughness, và normal) cùng với màu nền hay không. Với meshy-6, Meshy cũng tạo ra một bản đồ emission, ngoại trừ khi texture_resolution là 8k. meshy-6-lite, meshy-7, và latest không tạo ra bản đồ emission. Với meshy-n1, giá trị true sẽ trả về 400.

Kích thước của texture màu nền. Độ phân giải cao hơn sẽ nắm bắt được nhiều chi tiết bề mặt hơn.

Các giá trị khả dụng:

• 2k: 2048 × 2048 pixel
• 4k: 4096 × 4096 pixel
• 8k: 8192 × 8192 pixel

4k và 8k cần ai_model là meshy-6, meshy-7, hoặc latest. Với meshy-6-lite hoặc meshy-n1, chúng sẽ trả về 400. Ở mức 8k, Meshy không tạo ra bản đồ emission.

Hãy dùng texture_resolution thay thế. true tương đương với texture_resolution: "4k". Nếu bạn gửi cả hai, Meshy sẽ sử dụng texture_resolution.

Có loại bỏ các điểm sáng và bóng đổ khỏi texture màu nền hay không. Kết quả sẽ hoạt động tốt hơn dưới ánh sáng riêng của bạn.

Meshy chỉ áp dụng tham số này với meshy-6, ở texture_resolution là 2k hoặc 4k. Với meshy-7 hoặc latest, hoặc ở mức 8k, Meshy chấp nhận tham số này và bỏ qua nó. Với meshy-6-lite hoặc meshy-n1, gửi tham số này với bất kỳ giá trị nào sẽ trả về 400.

Các định dạng file cần tạo. Meshy chỉ tạo ra các định dạng bạn liệt kê, điều này có thể rút ngắn thời gian tác vụ. Nếu bạn bỏ qua tham số này, Meshy sẽ tạo mọi định dạng trừ 3mf.

Các giá trị khả dụng:

• glb
• obj
• fbx
• stl
• usdz
• 3mf

Có kết xuất thêm một bản xem trước với nền trong suốt (RGBA) hay không, được trả về trong alpha_thumbnail_url khi bạn lấy tác vụ. thumbnail_url sẽ không thay đổi.

Yêu cầu không thể chạy được. Thông báo lỗi sẽ cho biết vấn đề nào đã được phát hiện. Ví dụ:

• Thiếu tham số: Không có model_url lẫn input_task_id được gửi.
• Thiếu phong cách: Không có tham số nào trong số text_style_prompt, image_style_url, và multiview_image_urls được gửi.
• Xung đột đầu vào phong cách: multiview_image_urls được gửi cùng với text_style_prompt hoặc image_style_url.
• Mô hình không được hỗ trợ cho đa góc nhìn: multiview_image_urls được gửi mà không có ai_model rõ ràng là meshy-7 hoặc meshy-n1.
• Tùy chọn không được hỗ trợ cho Meshy N1: meshy-n1 được gửi cùng với enable_pbr: true, remove_lighting, texture_resolution là 4k hoặc 8k, hd_texture: true mà không có texture_resolution, hoặc text_style_prompt mà không có image_style_url.
• Quá nhiều tam giác đối với Meshy N1: Với meshy-n1, mô hình 3D có nhiều hơn 7.999.999 tam giác. Hãy giảm số lượng tam giác, hoặc sử dụng ai_model khác.
• Mô hình quá phức tạp đối với Meshy N1: Với meshy-n1, file model_url quá phức tạp để Meshy đếm số tam giác. Hãy giảm số lượng tam giác, sau đó gửi lại file.
• Đếm tam giác bị hết thời gian chờ: Với meshy-n1, việc đếm số tam giác của file model_url mất quá nhiều thời gian. Hãy thử lại, hoặc giảm kích thước mô hình.
• Tác vụ đầu vào không hợp lệ: input_task_id không phải là một tác vụ thành công thuộc loại được hỗ trợ.
• Định dạng mô hình không hợp lệ: File model_url có phần mở rộng không được hỗ trợ.
• URL không thể truy cập: Meshy không thể tải xuống file model_url, hình ảnh image_style_url, hoặc một hình ảnh trong multiview_image_urls.
• File mô hình quá lớn: File model_url có dung lượng trên 400 MB từ một URL http hoặc https, hoặc trên 100 MB nếu là data URI.
• Quá nhiều mặt: File model_url có dung lượng trên 100 MB và có nhiều hơn 10.000.000 mặt. Hãy giảm số lượng mặt, sau đó gửi lại file.
• FBX ASCII trên 100 MB: File model_url là FBX ASCII có dung lượng trên 100 MB. Hãy gửi nó dưới dạng FBX nhị phân hoặc GLB.
• File mô hình không thể đọc được: File model_url có dung lượng trên 100 MB, và Meshy không thể đọc phần header của nó. Ví dụ, đó là file GLB hoặc glTF được nén Draco, hoặc file FBX nhị phân cũ hơn phiên bản 7.1.
• Header mô hình quá phức tạp: File model_url có dung lượng trên 100 MB, và phần header của nó có quá nhiều lưới, node, hoặc bản ghi để kiểm tra. Hãy giảm số lượng đối tượng trong file, sau đó gửi lại.
• Hình ảnh quá lớn: Hình ảnh image_style_url hoặc một hình ảnh trong multiview_image_urls có dung lượng trên 20 MB.

Với meshy-n1, một mô hình mà Meshy không thể kiểm tra trước khi tác vụ bắt đầu, chẳng hạn như file STL, sẽ không bị từ chối ở đây. Nếu mô hình đó có nhiều hơn 7.999.999 tam giác, tác vụ sẽ thất bại, và Meshy sẽ hoàn lại tín dụng cho tác vụ đó.

Hãy sửa yêu cầu, sau đó gửi lại. Xem Lỗi.

Khóa API bị thiếu hoặc không hợp lệ. Hãy kiểm tra header Authorization.

Ví dụ:

• Không đủ tín dụng: Tài khoản không có đủ tín dụng cho tác vụ này, hoặc tài khoản đã đạt đến giới hạn tín dụng. Hãy kiểm tra số dư tín dụng của bạn, sau đó thử lại.
• Gói miễn phí: Việc tạo tác vụ yêu cầu một gói trả phí. Hãy nâng cấp gói của bạn trong cài đặt đăng ký, sau đó thử lại.

Một trong các trường hợp sau áp dụng:

• Kiểm duyệt nội dung đã chặn prompt hoặc một hình ảnh đầu vào. Hãy thay đổi đầu vào, sau đó thử lại.
• input_task_id là một mô hình bas-relief (phù điêu), mà endpoint này không thể tạo lại texture. Thông báo là This model type does not support this operation. Hãy gửi một mô hình khác.

input_task_id không khớp với bất kỳ tác vụ nào của bạn. Hãy kiểm tra ID tác vụ, sau đó gửi lại yêu cầu.

Bạn đã vượt quá giới hạn tốc độ của mình. Hãy chờ, sau đó thử lại. Xem Giới hạn tốc độ.

ID tác vụ từ phản hồi tạo.

ID của tác vụ cần xóa.

Số trang cần trả về, tối đa 255. Giá trị lớn hơn sẽ trả về 400.

Số lượng tác vụ trên mỗi trang, tối đa 100.

Thứ tự sắp xếp.

Các giá trị khả dụng:

• +created_at: cũ nhất trước
• -created_at: mới nhất trước

ID tác vụ từ phản hồi tạo tác vụ.

ID tác vụ. Hãy coi đây là một chuỗi không minh bạch, và đừng phụ thuộc vào định dạng của nó.

Loại tác vụ, luôn là retexture.

URL tải xuống cho mô hình 3D đã được tạo texture, mỗi URL ứng với một định dạng tệp.

Prompt văn bản bạn đã dùng để tạo tác vụ.

Hình ảnh phong cách bạn đã dùng để tạo tác vụ.

URL tải xuống cho các hình ảnh tham chiếu đa góc nhìn bạn đã dùng để tạo tác vụ. Chỉ xuất hiện khi bạn tạo tác vụ với multiview_image_urls.

URL tải xuống cho ảnh thu nhỏ của mô hình.

URL tải xuống cho một phiên bản của thumbnail_url với nền trong suốt (RGBA). Chỉ xuất hiện khi bạn tạo tác vụ với alpha_thumbnail: true và Meshy đã render bản xem trước trong suốt.

Tác vụ đã hoàn thành bao nhiêu, tính theo phần trăm. Giá trị này là 0 cho đến khi tác vụ bắt đầu và 100 khi nó thành công.

Thời điểm tác vụ bắt đầu, tính bằng mili giây Unix. Giá trị này là 0 cho đến khi tác vụ bắt đầu.

Thời điểm tác vụ được tạo, tính bằng mili giây Unix.

Thời điểm kết quả của tác vụ hết hạn, tính bằng mili giây Unix.

Thời điểm tác vụ hoàn tất, tính bằng mili giây Unix. Giá trị này là 0 cho đến khi tác vụ hoàn tất.

Trạng thái tác vụ, là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, hoặc CANCELED.

URL tải xuống cho các texture đã tạo, dưới dạng một mảng đối tượng. Mảng này thường chứa một đối tượng. Mỗi đối tượng có các trường sau:

Số lượng tác vụ đứng trước tác vụ này trong hàng đợi. Chỉ xuất hiện khi tác vụ đang ở trạng thái PENDING; trường này bị bỏ qua khi giá trị là 0.

Thông tin chi tiết lỗi khi tác vụ thất bại. Xem Lỗi.

Số tín dụng mà tác vụ đã sử dụng. Xuất hiện khi trạng thái là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Giá trị này là 0 đối với tác vụ FAILED, vì Meshy hoàn lại tín dụng khi một tác vụ thất bại.