Remesh API

Remesh API cho phép bạn remesh và xuất các mô hình 3D hiện có được tạo ra bởi các API khác của Meshy (như Ảnh sang 3D hoặc Văn bản sang 3D) sang nhiều định dạng khác nhau. Phần này cung cấp chi tiết về cách sử dụng Remesh API.

POST/openapi/v1/remesh

Create a Remesh Task

Endpoint này tạo một tác vụ remesh mới.

Để chuyển đổi định dạng và đổi kích thước, hãy sử dụng Convert API và Resize API chuyên dụng. Các tham số không dùng nữa bên dưới sẽ vẫn hoạt động, nhưng chúng tôi khuyến nghị sử dụng các endpoint mới cho các tích hợp mới.

Tham số

Chỉ cần bắt buộc một trong hai input_task_id hoặc model_url. Nếu cả hai đều được cung cấp, 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 remesh. 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 Retexture. Ngoài ra, nó phải có trạng thái SUCCEEDED.

Name
model_url
Type
string
Bắt buộc
Description
Vui lòng cung cấp một mô hình 3D để Meshy remesh thông qua một URL có thể truy cập công khai hoặc data URI. Các định dạng được hỗ trợ: .glb, .gltf, .obj, .fbx, .stl.
Đối với Data URI, sử dụng MIME type: application/octet-stream.

Name
target_formats
Type
string[]
mặc định ["glb"]
Description
Danh sách các định dạng đích cho mô hình đã remesh. Khi bỏ trống, chỉ GLB được tạo ra.
Các giá trị khả dụng: glb, fbx, obj, usdz, blend, stl, 3mf.
Name
topology
Type
string
mặc định triangle
Description
Chỉ định topology của mô hình được tạo ra.
Các giá trị khả dụng:
- quad: Tạo ra lưới chủ yếu là tứ giác (quad-dominant).
- triangle: Tạo ra lưới tam giác đã giảm số đa giác (decimated).
Name
target_polycount
Type
integer
mặc định 30,000
Description
Chỉ định số lượng đa giác mục tiêu trong mô hình được tạo ra. Số lượng đa giác thực tế có thể khác với mục tiêu tùy thuộc vào độ phức tạp của hình học.
Phạm vi giá trị hợp lệ thay đổi tùy theo cấp người dùng:
- 100 đến 300.000 (bao gồm cả hai đầu)
Name
decimation_mode
Type
integer
Description
Bật chế độ giảm số đa giác thích ứng bằng cách đặt mức số đa giác. Khi được đặt, target_polycount sẽ bị bỏ qua.
Các giá trị khả dụng:
- 1: Thích ứng — số đa giác cực cao.
- 2: Thích ứng — số đa giác cao.
- 3: Thích ứng — số đa giác trung bình.
- 4: Thích ứng — số đa giác thấp.
Name
resize_height
Type
number
⚠ không dùng nữa
mặc định 0
Description
Đổi kích thước mô hình theo một chiều cao nhất định được đo bằng mét. Chúng tôi khuyến nghị sử dụng Resize API chuyên dụng thay thế.
auto_size, resize_height, và resize_longest_side loại trừ lẫn nhau.
Name
resize_longest_side
Type
number
⚠ không dùng nữa
mặc định 0
Description
Đổi kích thước mô hình sao cho chiều dài nhất của hộp giới hạn bằng giá trị được chỉ định tính bằng mét. Chúng tôi khuyến nghị sử dụng Resize API chuyên dụng thay thế.
auto_size, resize_height, và resize_longest_side loại trừ lẫn nhau.
Name
auto_size
Type
boolean
⚠ không dùng nữa
mặc định false
Description
Khi được đặt thành true, dịch vụ sẽ sử dụng thị giác AI để 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 cho phù hợp. Chúng tôi khuyến nghị sử dụng Resize API chuyên dụng thay thế.
auto_size, resize_height, và resize_longest_side loại trừ lẫn nhau.

Chỉ áp dụng khi auto_size = true

Name
origin_at
Type
string
⚠ không dùng nữa
mặc định bottom
Description
Vị trí của gốc tọa độ. Chúng tôi khuyến nghị sử dụng Resize API chuyên dụng thay thế.
Các giá trị khả dụng: bottom, center.

Name
convert_format_only
Type
boolean
⚠ không dùng nữa
Description
Nếu là true, dịch vụ sẽ chỉ thay đổi định dạng của tệp mô hình đầu vào, bỏ qua các đầu vào khác như topology, resize_height, và target_polycount. Chúng tôi khuyến nghị sử dụng Convert API chuyên dụng thay thế.
target_formats phải được cung cấp nếu convert_format_only được đặt thành true.

Name
alpha_thumbnail
Type
boolean
mặc định false
Description
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.

Kết quả trả về

Thuộc tính result của phản hồi chứa id của tác vụ remesh vừa được tạo.

Chế độ thất bại

Name
400 - Bad Request
Description
Yêu cầu không được chấp nhận. Các nguyên nhân phổ biến:
- Thiếu tham số: Phải cung cấp model_url hoặc input_task_id.
- 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ộ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.
- Topology không hợp lệ: Tham số topology không hợp lệ.
- Các tham số loại trừ lẫn nhau: auto_size và resize_height không thể cùng được đặt.
Name
401 - Unauthorized
Description
Xác thực thất bại. 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 độ.

Request

POST

/openapi/v1/remesh

# Basic remesh with custom formats and resize
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

# Quad remesh with auto-size
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "auto_size": true
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

GET/openapi/v1/remesh/:id

Truy xuất Nhiệm vụ Remesh

Endpoint này truy xuất một nhiệm vụ remesh theo ID của nó.

Tham số

Name
id
Type
path
Description
ID của nhiệm vụ remesh cần truy xuất.

Kết quả trả về

Đối tượng Nhiệm vụ Remesh.

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

DELETE/openapi/v1/remesh/:id

Xóa một Remesh Task

Endpoint này xóa vĩnh viễn một remesh task, bao gồm tất cả các model và dữ liệu liên quan. Hành động này không thể hoàn tác.

Path Parameters

Name
id
Type
path
Description
ID của remesh task cần xóa.

Trạng thái Task

Một task vẫn đang ở trạng thái PENDING sẽ được xóa và số tín dụng đã tiêu tốn tại thời điểm tạo sẽ được hoàn lại.

Một task đang ở trạng thái IN_PROGRESS không thể bị xóa: yêu cầu sẽ bị từ chối với mã 409 Conflict và task vẫn tiếp tục chạy. Tín dụng cho một task mà worker đã bắt đầu xử lý sẽ không được hoàn lại, vì vậy việc xóa nó giữa chừng sẽ khiến bạn mất cả tín dụng lẫn kết quả. Hãy đợi cho đến khi nó đạt trạng thái SUCCEEDED, FAILED hoặc CANCELED, sau đó mới xóa.

Một task ở trạng thái cuối cùng (SUCCEEDED, FAILED hoặc CANCELED) sẽ được xóa mà không được hoàn tín dụng.

Kết quả trả về

Trả về 200 OK khi thành công, hoặc 409 Conflict khi task đang ở trạng thái IN_PROGRESS.

Request

DELETE

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

GET/openapi/v1/remesh

List Remesh Tasks

Endpoint này cho phép bạn lấy danh sách các tác vụ Remesh.

Tham số

Name
page_num
Type
integer
mặc định 1
Description
Số trang cho việc phân trang.
Name
page_size
Type
integer
mặc định 10
Description
Giới hạn kích thước trang. Tối đa cho phép là 100 mục.
Name
sort_by
Type
string
Description
Trường để sắp xếp theo.
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.

Kết quả trả về

Trả về danh sách được phân trang của The Remesh Task Objects.

Request

GET

/openapi/v1/remesh

curl https://api.meshy.ai/openapi/v1/remesh?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]

GET/openapi/v1/remesh/:id/stream

Stream một Remesh Task

Endpoint này truyền (stream) các cập nhật theo thời gian thực cho một Remesh task bằng Server-Sent Events (SSE).

Tham số

Name
id
Type
path
Description
Định danh duy nhất của Remesh task cần stream.

Giá trị trả về

Trả về một luồng gồm các The Remesh Task Objects dưới dạng Server-Sent Events.

Đối với các task có trạng thái PENDING hoặc IN_PROGRESS, luồng phản hồi sẽ chỉ bao gồm các trường progress và status cần thiết.

Request

GET

/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

Đối tượng Remesh Task

Đối tượng Remesh Task đại diện cho một đơn vị công việc mà Meshy sử dụng để remesh và xuất một mô hình 3D hiện có sang nhiều định dạng khác nhau. Đối tượng này có các thuộc tính sau:

Thuộc tính

Name
id
Type
string
Description
Đị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 (k-sortable) làm chi tiết triển khai cho id tác vụ, 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ụ Remesh. Giá trị là remesh.
Name
model_urls
Type
object
Description
URL có thể tải xuống cho tệp mô hình 3D đã áp texture được tạo bởi Meshy. 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ề chuỗi rỗng.
- Name
  glb
  Type
  string
  Description
  URL có thể tải xuống cho tệp GLB.
- Name
  fbx
  Type
  string
  Description
  URL có thể tải xuống cho tệp FBX.
- Name
  obj
  Type
  string
  Description
  URL có thể tải xuống cho tệp OBJ.
- Name
  usdz
  Type
  string
  Description
  URL có thể tải xuống cho tệp USDZ.
- Name
  blend
  Type
  string
  Description
  URL có thể tải xuống cho tệp Blender.
- Name
  stl
  Type
  string
  Description
  URL có thể tải xuống cho tệp STL.
- Name
  3mf
  Type
  string
  Description
  URL có thể tải xuống cho tệp 3MF. Chỉ xuất hiện khi 3mf được yêu cầu thông qua target_formats.
Name
thumbnail_url
Type
string
Description
URL có thể tải xuống cho hình ảnh xem trước được render từ mô hình đã remesh.
Name
alpha_thumbnail_url
Type
string
Description
URL có thể tải xuống cho 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 render thành công; nếu không, trường này sẽ bị bỏ qua.
Name
progress
Type
integer
Description
Tiến trình 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ụ đã hoàn thành, giá trị này sẽ trở thành 100.
Name
status
Type
string
Description
Trạng thái của tác vụ. Các giá trị có thể là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước.
Giá trị của trường này chỉ có ý nghĩa khi trạng thái tác vụ là PENDING.
Name
created_at
Type
timestamp
Description
Dấu thời gian khi tác vụ được tạo, tính bằng mili giây.
Name
started_at
Type
timestamp
Description
Dấu thời gian khi 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.
Name
finished_at
Type
timestamp
Description
Dấu thời gian khi tác vụ hoàn thành, tính bằng mili giây. Nếu tác vụ chưa hoàn thành, thuộc tính này sẽ là 0.
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 đầy đủ tham chiếu về đối tượng task_error.
Name
consumed_credits
Type
integer
Description
Số lượng tín dụng đã tiêu thụ bởi tác vụ này. Có mặt khi trạng thái tác vụ là PENDING, IN_PROGRESS, hoặc SUCCEEDED. Trả về 0 đối với các tác vụ FAILED (tín dụng sẽ được hoàn lại khi thất bại).

Example Remesh Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}