Text to 3D API

Trường này nên được đặt là "preview" khi tạo một tác vụ preview.

Mô tả loại vật thể của mô hình 3D. Tối đa 800 ký tự.

Chỉ định loại tạo lưới 3D.

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

• standard: Tạo lưới 3D chi tiết cao thông thường.
• smart-topology: Chọn mô hình Smart Topology với ai_model (meshy-t2).
• lowpoly (không dùng nữa): Tạo lưới low-poly được tối ưu hóa cho các đa giác sạch hơn. Chúng tôi khuyến nghị sử dụng smart-topology thay thế.

ID của mô hình cần sử dụng. Các giá trị khả dụng phụ thuộc vào model_type.

Tạo standard (model_type: standard):

• meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
• meshy-7 (không dùng nữa): sử dụng meshy-7.1 thay thế.

Tạo Smart Topology (model_type: smart-topology):

• meshy-t2 (mặc định): mô hình Smart Topology — topology sạch hơn, các bộ phận được tách biệt tự nhiên, đầu ra dạng tam giác, và số lượng mặt bạn có thể đặt bằng target_polycount.

Bước tạo hình học. 2k chạy pass Ultra ở 2048³; 4k chạy pass này ở 4096³ để có chi tiết bề mặt tinh xảo nhất.

Các giá trị khả dụng: standard, 2k, 4k

Sử dụng geometry_resolution thay thế. ultra_mode: true tương đương với geometry_resolution: "2k".

Kiểm soát việc có bật giai đoạn remesh hay không. Đối với mô hình có chất lượng cao nhất, chúng tôi khuyến nghị đặt should_remesh là false.

Số lượng đa giác (mặt) mục tiêu trong đầu ra. Số lượng thực tế có thể lệch so với mục tiêu tùy thuộc vào hình học.

target_polycount có hiệu lực trong hai trường hợp độc lập:

• Remesh — với should_remesh: true trên một mô hình standard. Lưới sẽ được remesh (giảm số đa giác) đến gần bằng số lượng này. Phạm vi từ 100 đến 300.000, mặc định là 30.000. Nếu decimation_mode được đặt, nó sẽ được ưu tiên hơn và target_polycount sẽ bị bỏ qua.
• Smart Topology — với model_type: smart-topology và ai_model: meshy-t2. Mô hình được tạo trực tiếp với số lượng mặt này; không có remesh nào chạy và không yêu cầu should_remesh. Phạm vi từ 100 đến 15.000, mặc định là 4.000.

Không dùng nữa. Tham số này không còn ảnh hưởng đến đầu ra.

Trường symmetry_mode kiểm soát hành vi đối xứng trong quá trình tạo mô hình.

Các giá trị hợp lệ là:

• off: Tắt tính năng đối xứng.
• auto: Tự động xác định và áp dụng tính đối xứng dựa trên hình học đầu vào.
• on: Áp đặt tính đối xứng trong khi tạo.

Chỉ định pose_mode cho mô hình được tạo ra.

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

• a-pose: Tạo mô hình ở dáng chữ A (A pose).
• t-pose: Tạo mô hình ở dáng chữ T (T pose).
• "" (chuỗi rỗng): Không áp dụng dáng cụ thể nào.

Sử dụng pose_mode thay thế. Có tạo mô hình ở dáng A/T hay không.

Không được hỗ trợ bởi Meshy-6. Các yêu cầu sử dụng Meshy-6 sẽ bỏ qua art_style, và một số kết hợp có thể gây ra lỗi. Các giá trị khả dụng: realistic, sculpture.

Khi được đặt là true, nội dung đầu vào sẽ tự động được kiểm duyệt để phát hiện nội dung có khả năng gây hại. Nếu phát hiện nội dung gây hại, tác vụ sẽ không tiếp tục thực hiện việc tạo.

Văn bản từ prompt sẽ được kiểm duyệt.

Chỉ định các định dạng file 3D nào cần bao gồm trong đầu ra. Chỉ những định dạng được yêu cầu mới được tạo và trả về, giúp giảm thời gian hoàn thành tác vụ. Khi bị bỏ qua, tất cả các định dạng được hỗ trợ sẽ được bao gồm.

Các giá trị khả dụng: glb, obj, fbx, stl, usdz, 3mf

Khi được đặt là true, tác vụ sẽ render thêm một phiên bản preview có nền trong suốt (RGBA) và trả về dưới dạng alpha_thumbnail_url trong phản hồi GET. Trường thumbnail_url hiện có không thay đổi.

Khi được đặt là true, dịch vụ sẽ sử dụng AI vision để tự động ước tính chiều cao thực tế của vật thể và đổi kích thước mô hình cho phù hợp. Gốc tọa độ sẽ mặc định là bottom trừ khi origin_at được đặt rõ ràng.

Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:

• Thiếu tham số: Thiếu một tham số bắt buộc (ví dụ: prompt, mode).
• Tham số không hợp lệ: art_style không phải là một trong các giá trị được cho phép.
• Prompt quá dài: prompt vượt quá giới hạn ký tự.
• Mô hình không được hỗ trợ cho low poly: ai_model: "meshy-6-lite" không hỗ trợ model_type: "lowpoly".
• Mô hình không được hỗ trợ cho Ultra: geometry_resolution yêu cầu meshy-7.1 hoặc latest.

Xác thực không thành công. Vui lòng kiểm tra khóa API của bạn.

Không đủ tín dụng để thực hiện tác vụ này.

Bạn đã vượt quá giới hạn tốc độ.

Trường này phải được đặt là "refine" khi tạo một tác vụ refine.

ID của tác vụ preview tương ứng.

Trạng thái của tác vụ preview đã cho phải là SUCCEEDED.

Tạo bản đồ PBR (metallic, roughness, normal) bên cạnh màu cơ bản. Một emission map cũng được bao gồm khi ai_model là meshy-6, ngoại trừ ở texture_resolution: 8k (không tạo emission map). meshy-6-lite, meshy-7.1 và latest không tạo emission map.

Độ phân giải texture màu cơ bản. Một trong các giá trị 2k (2048×2048), 4k (4096×4096), hoặc 8k (8192×8192). Độ phân giải cao hơn ghi lại nhiều chi tiết bề mặt hơn. Chỉ áp dụng cho mode refine.

Sử dụng texture_resolution thay thế — tương đương với texture_resolution: "4k". Khi cả hai đều được đặt, texture_resolution sẽ được ưu tiên.

Cung cấp thêm một prompt văn bản để định hướng quá trình tạo texture. Tối đa 800 ký tự.

Cung cấp một hình ảnh 2D để định hướng quá trình tạo texture. Hiện tại chúng tôi hỗ trợ các định dạng .jpg, .jpeg, và .png.

Có hai cách để cung cấp hình ảnh:

• URL truy cập công khai: Một URL có thể truy cập được từ internet công cộng
• Data URI: Một data URI của hình ảnh được mã hóa base64. Ví dụ về data URI: data:image/jpeg;base64,<your base64-encoded image data>

ID của mô hình được sử dụng để refine.

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

• meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
• meshy-7 (không dùng nữa): hãy sử dụng meshy-7.1 thay thế.

Bỏ qua tham số này để kế thừa mô hình được sử dụng bởi tác vụ preview, giúp preview và refine của nó luôn dùng cùng một mô hình xuyên suốt. Truyền một giá trị rõ ràng để ghi đè sự kế thừa đó.

Khi được đặt thành true, nội dung đầu vào sẽ tự động được sàng lọc để phát hiện nội dung có khả năng gây hại. Nếu phát hiện nội dung gây hại, tác vụ sẽ không tiếp tục tạo.

Cả văn bản từ texture_prompt và hình ảnh từ texture_image_url đều sẽ được sàng lọc.

Loại bỏ vùng sáng và bóng đổ khỏi texture màu cơ bản, tạo ra kết quả sạch hơn, hoạt động tốt hơn dưới các thiết lập ánh sáng tùy chỉnh.

Chỉ định các định dạng tệp 3D nào sẽ được bao gồm trong đầu ra. Chỉ những định dạng được yêu cầu mới được tạo và trả về, điều này có thể giảm thời gian hoàn thành tác vụ. Khi bỏ qua, tất cả các định dạng được hỗ trợ sẽ được bao gồm.

Các giá trị khả dụng: glb, obj, fbx, stl, usdz, 3mf

Khi được đặt thành true, tác vụ sẽ render thêm một phiên bản nền trong suốt (RGBA) của bản xem trước và trả về dưới dạng alpha_thumbnail_url trong phản hồi GET. Trường thumbnail_url hiện có không thay đổi.

Khi được đặt thành true, dịch vụ sử dụng thị giác AI để tự động ước tính chiều cao thực tế của đối tượng và thay đổi kích thước mô hình cho phù hợp. Gốc tọa độ sẽ mặc định là bottom trừ khi origin_at được đặt rõ ràng.

Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:

• ID tác vụ không hợp lệ: preview_task_id không hợp lệ hoặc không tồn tại.
• Tác vụ chưa sẵn sàng: Tác vụ preview chưa hoàn thành thành công.
• Không khớp mô hình: Mô hình AI của tác vụ preview không tương thích với mô hình refine được yêu cầu.

Xác thực thất bại. Vui lòng kiểm tra khóa API của bạn.

Không đủ tín dụng để thực hiện tác vụ này.

Không tìm thấy tác vụ preview được chỉ định bởi preview_task_id.

Bạn đã vượt quá giới hạn tốc độ.

Định danh duy nhất của tác vụ Text to 3D cần lấy thông tin.

ID của tác vụ Văn bản sang 3D cần xóa.

Số trang dùng cho phân trang.

Giới hạn kích thước trang. Tối đa cho phép là 100 mục.

Trường dùng để sắp xếp.

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

• +created_at: Sắp xếp theo thời gian tạo theo thứ tự tăng dần.
• -created_at: Sắp xếp theo thời gian tạo theo thứ tự giảm dần.

Mã định danh duy nhất của tác vụ Văn bản sang 3D cần truyền trực tiếp.

Định danh duy nhất cho nhiệm vụ. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo k (k-sortable UUID) làm chi tiết triển khai cho id nhiệm vụ, bạn không nên đưa ra bất kỳ giả định nào về định dạng của id.

Loại nhiệm vụ Text to 3D. Các giá trị có thể là text-to-3d-preview cho nhiệm vụ ở giai đoạn preview và text-to-3d-refine cho nhiệm vụ ở giai đoạn refine.

URL có thể tải xuống của tệp mô hình 3D có texture được Meshy tạo ra. Thuộc tính cho một định dạng sẽ bị bỏ qua nếu định dạng đó không được tạo ra, thay vì trả về một chuỗi rỗng.

Đây là prompt không bị thay đổi đã được dùng để tạo nhiệm vụ.

Được giữ lại để tương thích ngược. Trường này không có tác động chức năng nào đến các mô hình được tạo ra.

art_style không bị thay đổi đã được dùng để tạo nhiệm vụ preview. Không được Meshy-6 hỗ trợ.

Được giữ lại để tương thích ngược. Trường này không có tác động chức năng nào đến các mô hình được tạo ra.

Prompt văn bản bổ sung được cung cấp để định hướng quá trình tạo texture trong giai đoạn refine.

Không dùng nữa; hãy đọc geometry_resolution thay thế.

Cấp Ultra mà nhiệm vụ preview đã chạy (2k hoặc 4k); bị bỏ qua đối với standard.

URL có thể tải xuống của ảnh texture đã được dùng để định hướng quá trình tạo texture.

URL có thể tải xuống của ảnh thu nhỏ của tệp mô hình.

URL có thể tải xuống của phiên bản nền trong suốt (RGBA) của thumbnail_url. Chỉ xuất hiện khi nhiệm vụ được tạo với alpha_thumbnail: true và ảnh xem trước trong suốt được render thành công; nếu không, trường này sẽ bị bỏ qua.

URL có thể tải xuống của video xem trước. Sẽ bị loại bỏ trong một phiên bản phát hành trong tương lai.

Tiến trình của nhiệm vụ. Nếu nhiệm vụ chưa bắt đầu, thuộc tính này sẽ là 0. Khi nhiệm vụ đã hoàn thành thành công, giá trị này sẽ trở thành 100.

Dấu thời gian khi nhiệm vụ được bắt đầu, tính bằng mili-giây. Nếu nhiệm vụ chưa bắt đầu, thuộc tính này sẽ là 0.

Dấu thời gian khi nhiệm vụ được tạo, tính bằng mili-giây.

Dấu thời gian khi nhiệm vụ hoàn thành, tính bằng mili-giây. Nếu nhiệm vụ chưa hoàn thành, thuộc tính này sẽ là 0.

Trạng thái của nhiệm vụ. Các giá trị có thể là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

Một mảng các đối tượng URL texture được tạo ra từ nhiệm vụ. Thông thường mảng này chỉ chứa một đối tượng URL texture. Mỗi URL texture có các thuộc tính sau:

Số lượng nhiệm vụ đứng trước.

Chi tiết lỗi cho các nhiệm vụ thất bại. Xem Lỗi để biết đầy đủ tham chiếu đối tượng task_error.

Số tín dụng đã bị tiêu thụ bởi nhiệm vụ này. Xuất hiện khi trạng thái nhiệm vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các nhiệm vụ FAILED (tín dụng sẽ được hoàn lại khi thất bại).