API Tạo lại texture là một tính năng cho phép bạn tích hợp các khả năng tạo lại texture (retexture) bằng AI của Meshy vào ứng dụng của riêng bạn. Trong phần này, bạn sẽ tìm thấy tất cả thông tin
bạn cần để bắt đầu với API này.
endpoint này cho phép bạn tạo một tác vụ Tạo lại texture mới. Tham khảo
Đối tượng tác vụ Tạo lại texture để xem những
thuộc tính nào được bao gồm trong đối tượng tác vụ Tạo lại texture.
Tham số
Chỉ bắt buộc một trong hai input_task_id hoặc model_url. Nếu cung cấp cả hai, input_task_id sẽ được ưu tiên.
Name
input_task_id
Type
string
Bắt buộc
Description
ID của tác vụ Ảnh sang 3D hoặc Văn bản sang 3D đã hoàn tất mà bạn muốn tạo lại texture (retexture).
Tác vụ này phải là một trong các tác vụ sau: Text to 3D Preview, Text to 3D Refine, Image to 3D hoặc Remesh. Ngoài ra, tác vụ phải có trạng thái SUCCEEDED.
Name
model_url
Type
string
Bắt buộc
Description
Cung cấp một mô hình 3D để Meshy tạo texture. Các định dạng được hỗ trợ: .glb, .gltf, .obj, .fbx, .stl.
Có hai cách để cung cấp mô hình:
URL có thể truy cập công khai: URL có thể truy cập từ internet công cộng.
Data URI: Data URI được mã hóa base64 của mô hình. Sử dụng MIME type application/octet-stream. Ví dụ: data:application/octet-stream;base64,<your base64-encoded model data>.
Chỉ bắt buộc một trong hai text_style_prompt hoặc image_style_url. Nếu cung cấp cả hai, image_style_url sẽ được ưu tiên.
Name
text_style_prompt
Type
string
Bắt buộc
Description
Mô tả phong cách texture mong muốn của đối tượng bằng văn bản. Tối đa 600 ký tự.
Name
image_style_url
Type
string
Bắt buộc
Description
Cung cấp một ảnh 2D để hướng dẫn quá trình tạo texture. Hiện chúng tôi hỗ trợ các định dạng .jpg, .jpeg và .png.
Có hai cách để cung cấp ảnh:
URL có thể truy cập công khai: URL có thể truy cập từ internet công cộng
Data URI: Data URI được mã hóa base64 của ảnh. Ví dụ về Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Việc tạo texture bằng ảnh có thể không hoạt động tối ưu nếu có sự khác biệt lớn về hình học giữa tài sản (asset) gốc và ảnh đã tải lên.
Name
ai_model
Type
string
mặc định latest
Description
ID của mô hình AI dùng để tạo lại texture (retexture). Các giá trị khả dụng: meshy-5, meshy-6, latest (Meshy 6).
Name
enable_original_uv
Type
boolean
mặc định false
Description
Giữ bố cục UV hiện có của mô hình thay vì tạo bố cục mới.
Nếu bạn đang tạo lại texture (retexture) cho mô hình do Meshy tạo (thông qua input_task_id, hoặc model_url trỏ đến đầu ra của Meshy), hãy đặt giá trị này thành true để tái sử dụng bố cục UV đã được tối ưu hóa của mô hình.
Nếu bạn đang tạo lại texture (retexture) cho mô hình của bên thứ ba mà bạn đã tải lên, hãy đặt true khi mô hình đã có UV tốt mà bạn muốn giữ lại, hoặc để false để Meshy unwrap UV mới (tốt nhất cho các mô hình thiếu ánh xạ UV phù hợp).
Name
enable_pbr
Type
boolean
mặc định false
Description
Tạo bản đồ PBR (metallic, roughness, normal) ngoài màu cơ sở. Bản đồ emission cũng được bao gồm khi ai_model là meshy-6 hoặc latest.
Name
hd_texture
Type
boolean
mặc định false
Description
Tạo texture màu cơ sở ở độ phân giải 4K (4096×4096) để có mức chi tiết cao hơn.
Chỉ được hỗ trợ khi ai_model là meshy-6 hoặc latest. bản đồ PBR luôn được tạo ở 2K.
Name
remove_lighting
Type
boolean
mặc định true
Description
Loại bỏ vùng sáng và bóng khỏi texture màu cơ sở, tạo ra kết quả sạch hơn và hoạt động tốt hơn dưới các thiết lập chiếu sáng tùy chỉnh.
Chỉ được hỗ trợ khi ai_model là meshy-6 hoặc latest.
Name
target_formats
Type
string[]
Description
Chỉ định các định dạng tệp 3D nào sẽ được đưa vào đầu ra. Chỉ các đị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 tất 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 bỏ qua, tất cả các định dạng ngoại trừ 3mf sẽ được tạo. 3mf chỉ được bao gồm khi được chỉ định rõ ràng.
Name
alpha_thumbnail
Type
boolean
mặc định false
Description
Khi đặ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ề phiên bản đó dưới dạng alpha_thumbnail_url trong phản hồi GET. Trường thumbnail_url hiện có không thay đổi.
Trả về
Thuộc tính result của phản hồi chứa id tác vụ của tác vụ Tạo lại texture mới được tạo.
Chế độ lỗi
Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Nguyên nhân phổ biến:
Thiếu tham số: Phải cung cấp model_url hoặc input_task_id.
Thiếu kiểu: Phải cung cấp text_style_prompt hoặc image_style_url.
Tác vụ đầu vào không hợp lệ: input_task_id phải tham chiếu đến một tác vụ thành công từ mô hình được hỗ trợ.
Định dạng mô hình không hợp lệ: model_url trỏ đến một tệp có phần mở rộng không được hỗ trợ.
URL không thể truy cập: Không thể tải xuống model_url hoặc image_style_url.
Name
401 - Unauthorized
Description
Xác thực không thành công. Vui lòng kiểm tra khóa API của bạn.
Name
402 - Payment Required
Description
Không đủ tín dụng để thực hiện tác vụ này.
Name
429 - Too Many Requests
Description
Bạn đã vượt quá giới hạn tốc độ của mình.
Request
POST
/openapi/v1/retexture
# Retexture with text promptcurl https://api.meshy.ai/openapi/v1/retexture \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style", "enable_original_uv": true, "enable_pbr": true }'# Retexture with image style and PBRcurl https://api.meshy.ai/openapi/v1/retexture \ -H "Authorization: Bearer ${YOUR_API_KEY}" \ -H 'Content-Type: application/json' \ -d '{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg", "ai_model": "latest", "enable_pbr": true, "enable_original_uv": true }'
endpoint này cho phép bạn truy xuất một tác vụ Tạo lại texture khi có id tác vụ hợp lệ.
Tham khảo Đối tượng tác vụ Tạo lại texture để xem những
thuộc tính nào được bao gồm trong đối tượng tác vụ Tạo lại texture.
Tham số
Name
id
Type
path
Description
Mã định danh duy nhất của tác vụ Tạo lại texture cần truy xuất.
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","obj":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***","stl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","texture_image_url":"","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"task_error": {"message":"" },"consumed_credits":10}
[ {"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10 }]
Đối tượng tác vụ Tạo lại texture là một đơn vị công việc mà Meshy sử dụng để tạo texture 3D từ đầu vào là văn bản hoặc hình ảnh.
Mô hình có các thuộc tính sau:
Thuộc tính
Name
id
Type
string
Description
Mã định danh duy nhất cho tác vụ. Mặc dù chúng tôi sử dụng UUID có thể sắp xếp theo k cho id tác vụ như một
chi tiết triển khai, bạn không nên đưa ra bất kỳ giả định nào về định dạng của id.
Name
type
Type
string
Description
Loại tác vụ Tạo lại texture. Giá trị là retexture.
Name
model_urls
Type
object
Description
URL có thể tải xuống tới tệp mô hình 3D đã được tạo texture do Meshy tạo ra.
Name
glb
Type
string
Description
URL có thể tải xuống tới tệp GLB.
Name
fbx
Type
string
Description
URL có thể tải xuống tới tệp FBX.
Name
obj
Type
string
Description
URL có thể tải xuống tới tệp OBJ.
Name
usdz
Type
string
Description
URL có thể tải xuống tới tệp USDZ.
Name
mtl
Type
string
Description
URL có thể tải xuống tới tệp MTL, được trả về cùng với các bản xuất OBJ khi có texture.
Name
stl
Type
string
Description
URL có thể tải xuống tới tệp STL.
Name
3mf
Type
string
Description
URL có thể tải xuống tới tệp 3MF. Chỉ xuất hiện khi 3mf được yêu cầu thông qua target_formats.
Name
text_style_prompt
Type
string
Description
Đây là prompt văn bản đã được sử dụng để tạo tác vụ tạo texture.
Name
image_style_url
Type
string
Description
Đây là đầu vào hình ảnh đã được sử dụng để tạo tác vụ tạo texture.
Name
thumbnail_url
Type
string
Description
URL có thể tải xuống tới hình ảnh ảnh thu nhỏ của tệp mô hình.
Name
alpha_thumbnail_url
Type
string
Description
URL có thể tải xuống tới phiên bản nền trong suốt (RGBA) của thumbnail_url. Chỉ xuất hiện khi tác vụ đượ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.
Name
progress
Type
integer
Description
Progress của tác vụ. Nếu tác vụ chưa bắt đầu, thuộc tính này sẽ là 0. Khi tác vụ đã thành công, giá trị này sẽ trở thành 100.
Name
started_at
Type
timestamp
Description
Dấu thời gian cho biết khi nào tác vụ được bắt đầu, tính bằng mili giây. Nếu tác vụ chưa bắt đầu, thuộc tính này sẽ là 0.
Một dấu thời gian biểu thị số mili giây đã trôi qua kể từ ngày 1 tháng 1 năm 1970 UTC, tuân theo
tiêu chuẩn RFC 3339.
Ví dụ, Thứ Sáu, ngày 1 tháng 9 năm 2023 12:00:00 PM GMT được biểu thị là 1693569600000. Điều này áp dụng
cho tất cả dấu thời gian trong Meshy API.
Name
created_at
Type
timestamp
Description
Dấu thời gian cho biết khi nào tác vụ được tạo, tính bằng mili giây.
Name
expires_at
Type
timestamp
Description
Dấu thời gian cho biết khi nào kết quả tác vụ hết hạn, tính bằng mili giây.
Name
finished_at
Type
timestamp
Description
Dấu thời gian cho biết khi nào tác vụ hoàn tất, tính bằng mili giây. Nếu tác vụ chưa hoàn tất, thuộc tính này sẽ là 0.
Name
status
Type
string
Description
Trạng thái của tác vụ. Các giá trị có thể là một trong PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Một mảng các đối tượng URL texture được tạo từ tác 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:
Name
base_color
Type
string
Description
URL có thể tải xuống tới hình ảnh bản đồ màu cơ sở.
Name
metallic
Type
string
Description
URL có thể tải xuống tới hình ảnh bản đồ metallic.
Nếu tác vụ được tạo với enable_pbr: false, thuộc tính này sẽ bị bỏ qua.
Name
normal
Type
string
Description
URL có thể tải xuống tới hình ảnh bản đồ normal.
Nếu tác vụ được tạo với enable_pbr: false, thuộc tính này sẽ bị bỏ qua.
Name
roughness
Type
string
Description
URL có thể tải xuống tới hình ảnh bản đồ roughness.
Nếu tác vụ được tạo với enable_pbr: false, thuộc tính này sẽ bị bỏ qua.
Name
emission
Type
string
Description
URL có thể tải xuống tới hình ảnh bản đồ emission.
Nếu tác vụ được tạo với enable_pbr: false, hoặc ai_model là meshy-5, thuộc tính này sẽ bị bỏ qua.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước.
Thuộc tính này chỉ xuất hiện khi trạng thái tác vụ là PENDING.
Name
task_error
Type
object
Description
Chi tiết lỗi cho các tác vụ thất bại. Xem Lỗi để biết tham chiếu đầy đủ về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số tín dụng được tiêu thụ bởi tác vụ này. Xuất hiện khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 cho các tác vụ FAILED (tín dụng được hoàn lại khi thất bại).
Example Retexture Task Model
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","image_style_url":"https://assets.meshy.ai/***/image/example_image.jpg?Expires=***","thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10}