Text to 3D API

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

Mô tả loại đối tượng mà mô hình 3D thể hiện. Tối đa 800 ký tự.

Chỉ định loại hình 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 hoặc meshy-t2.5).
• lowpoly (không dùng nữa, sẽ ngừng hỗ trợ vào ngày 30 tháng 10 năm 2026): Tạo lưới low-poly được tối ưu hóa cho các đa giác gọn gàng hơn. Chúng tôi khuyến nghị sử dụng Meshy T2.5 thay thế: smart-topology với meshy-t2.5.

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 dạng tiêu chuẩn (model_type: standard):

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

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

• meshy-t2: mô hình Smart Topology — topology gọn gàng hơn, các bộ phận được tách tự nhiên, đầu ra tam giác, và số lượng mặt có thể thiết lập bằng target_polycount.
• meshy-t2.5 (mặc định): Chi tiết sắc nét hơn cho asset trong game. Đầu ra tam giác, và số lượng mặt có thể thiết lập bằng target_polycount.

Giai đoạn tạo hình học. 2k chạy tiến trình Ultra ở độ phân giải 2048³; 4k chạy ở độ phân giải 4096³ để cho chi tiết bề mặt tinh xảo nhất.

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

Hãy 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. Để đạt chất lượng mô hình 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ô hình standard. Lưới sẽ được remesh (giản lược) về xấp xỉ số lượng này. Khoảng từ 100 đến 300.000, mặc định 30.000. Nếu decimation_mode được thiết lập, nó sẽ được ưu tiên và target_polycount sẽ bị bỏ qua.
• Smart Topology — với model_type: smart-topology và ai_model là meshy-t2 hoặc meshy-t2.5. Mô hình được tạo trực tiếp với số lượng mặt này; không có bước remesh nào chạy và không cần should_remesh. Với meshy-t2: khoảng từ 100 đến 15.000, mặc định 4.000. Với meshy-t2.5: khoảng từ 100 đến 30.000, mặc định 15.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 đối xứng.
• auto: Tự động xác định và áp dụng đối xứng dựa trên hình học đầu vào.
• on: Buộc đối xứng trong quá trình 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 ở tư thế chữ A.
• t-pose: Tạo mô hình ở tư thế chữ T.
• "" (chuỗi rỗng): Không áp dụng tư thế cụ thể nào.

Hãy dùng pose_mode thay thế. Có tạo mô hình ở tư thế 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ố 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 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 sang bước tạo.

Văn bản từ prompt sẽ được sàng lọc.

Chỉ định những định dạng tệp 3D nào cần có trong đầu ra. Chỉ các định dạng được yêu cầu mới được tạo ra và trả về, điều này có thể giảm thời gian hoàn thành tác vụ. Khi bỏ trống, 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 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 là true, dịch vụ sẽ sử dụng AI vision để tự động ước tính chiều cao thực tế của đối tượng và đổi kích thước mô hình tương ứng. Gốc tọa độ sẽ mặc định là bottom trừ khi origin_at được thiết lập 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 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.

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

Trường này nên được đặt thành "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) ngoài màu nền (base color). Bản đồ emission cũng được bao gồm khi ai_model là meshy-6, ngoại trừ ở texture_resolution: 8k (không tạo bản đồ emission). meshy-6-lite, meshy-7.1 và latest không tạo bản đồ emission, và một refine của preview meshy-t2 không đặt ai_model cũng vậy.

Độ phân giải texture màu nề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 sẽ nắm bắt được nhiều chi tiết bề mặt hơn. Chỉ áp dụng cho mode refine.

Hãy 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, .png, và .webp.

Kích thước tệp tối đa: 20 MB.

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 khai
• Data URI: Một data URI của hình ảnh được mã hóa base64. Ví dụ về một data URI: data:image/jpeg;base64,<dữ liệu hình ảnh được mã hóa base64 của bạn>

ID của mô hình được 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 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ữ cho một preview và refine của nó dùng cùng một mô hình xuyên suốt. Truyền một giá trị rõ ràng để ghi đè việc kế thừa đó.

Khi được đặt thành true, nội dung đầu vào sẽ tự động được kiểm duyệt để tìm 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 kiểm duyệt.

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

Chỉ định những đị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 preview và trả về dưới dạng alpha_thumbnail_url trong phản hồi GET. Trường thumbnail_url hiện có vẫn không thay đổi.

Khi được đặt thành true, dịch vụ sẽ sử dụng AI vision để 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 tương ứng. 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 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.
• Mô hình không hỗ trợ remove_lighting: remove_lighting được đặt cùng với ai_model: "meshy-6-lite".

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ụ Văn bản sang 3D cần truy xuất.

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 số lượng mỗi 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 cho tác vụ Văn bản sang 3D cần truyền trực tiếp.

Định danh duy nhất cho task. 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 của task, bạn không nên đưa ra bất kỳ giả định nào về định dạng của id.

Loại của task Văn bản sang 3D. Các giá trị có thể là text-to-3d-preview cho các task ở giai đoạn preview và text-to-3d-refine cho các task ở giai đoạn refine.

URL để tải xuống tệp mô hình 3D có texture do 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ị chỉnh sửa đã được dùng để tạo task.

Được giữ lại để đảm bảo khả năng 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ị chỉnh sửa đã được dùng để tạo task preview. Không được hỗ trợ bởi Meshy-6.

Được giữ lại để đảm bảo khả năng 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à task preview đã chạy (2k hoặc 4k); bị bỏ qua đối với standard.

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

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

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

URL để tải xuống video xem trước. Sẽ bị xóa trong một bản phát hành trong tương lai.

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

Dấu thời gian cho biết thời điểm task bắt đầu, tính bằng mili giây. Nếu task chưa bắt đầu, thuộc tính này sẽ là 0.

Dấu thời gian cho biết thời điểm task được tạo, tính bằng mili giây.

Dấu thời gian cho biết thời điểm task hoàn thành, tính bằng mili giây. Nếu task chưa hoàn thành, thuộc tính này sẽ là 0.

Trạng thái của task. 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ừ task. 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 task đứng trước.

Chi tiết lỗi cho các task thất bại. Xem Lỗi để biết tài liệu tham khảo đầy đủ về đối tượng task_error.

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