API Phù điêu

Biến một bức ảnh thành mô hình 3D phù điêu và bản đồ độ sâu 16-bit, dùng để in 3D, khắc laser và chạm khắc CNC.

POST/openapi/v1/relief

Tạo tác vụ Phù điêu

Tạo một tác vụ Phù điêu. Tác vụ này biến một bức ảnh thành mô hình chạm nổi (bas-relief). Khi thành công, tác vụ sẽ tạo ra mô hình dưới dạng tệp GLB và tệp STL, một bản đồ độ sâu grayscale 16-bit, và một ảnh xem trước. Để chỉ lấy bản đồ độ sâu, đặt should_generate_model thành false.

Tác vụ chạy ngầm.

Một tác vụ Phù điêu không thể được dùng làm đầu vào cho endpoint khác, chẳng hạn như Remesh, Chuyển đổi, hoặc Auto Split. Các yêu cầu đó sẽ trả về 403.

Request

POST

/openapi/v1/relief

# Simple request: a low relief, 60 mm on its longer side
curl https://api.meshy.ai/openapi/v1/relief \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# Advanced request: a deep 120 mm relief with a thicker base, curved from side to side
curl https://api.meshy.ai/openapi/v1/relief \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "variant": "high",
    "size_mm": 120,
    "carving_depth_mm": 10,
    "base_thickness_mm": 3,
    "bend_mode": "convex",
    "bend_angle": 90
  }'

Response

{
  "result": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20"
}

Tham số

Name
image_url
Type
string
Bắt buộc
Description
Bức ảnh để biến thành phù điêu, dưới dạng URL công khai hoặc Data URI (data:image/png;base64,...).
Ảnh phải là tệp 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 × 32 pixel. Cạnh dài hơn của ảnh có thể tối đa gấp khoảng 16 lần cạnh ngắn hơn. Mọi ảnh khác sẽ trả về 400. Meshy sẽ lấp đầy các vùng trong suốt bằng màu đen trước khi dựng phù điêu.
Name
variant
Type
string
mặc định low
Description
Phong cách phù điêu. Nó định hình bản đồ độ sâu và đặt giá trị mặc định cho carving_depth_mm.
Các giá trị khả dụng:
- high: chạm khắc sâu hơn, dành cho các chi tiết in 3D.
- low: chạm khắc nông, dành cho khắc laser, chạm khắc CNC, và các tấm biển mỏng.
Gửi null hoặc "" tương đương với việc bỏ qua tham số này. Bất kỳ giá trị nào khác sẽ trả về 400.
Name
should_generate_model
Type
boolean
mặc định true
Description
Có xây dựng mô hình phù điêu hay không. Đặt thành false cho tác vụ chỉ tạo bản đồ độ sâu, không có mô hình và không có ảnh xem trước. Meshy vẫn kiểm tra các tham số kích thước, chạm khắc, đế, uốn cong, và độ phân giải, nhưng không sử dụng chúng. Việc này không làm thay đổi chi phí tín dụng.

Name
size_mm
Type
number
mặc định 60
Description
Chiều dài của cạnh dài hơn của bức ảnh trên mô hình, được đo khi phẳng trước khi uốn cong, từ 20 đến 250 milimét. Với remove_base, mô hình có thể nhỏ hơn.
Name
carving_mode
Type
string
mặc định emboss
Description
Chủ thể nổi lên khỏi tấm nền hay bị khắc chìm vào trong.
Các giá trị khả dụng:
- emboss: các phần gần hơn của bức ảnh sẽ nổi lên.
- engrave: độ sâu bị đảo ngược, do đó các phần gần hơn sẽ bị khắc chìm vào.
Bản đồ độ sâu giống nhau trong cả hai chế độ.
Name
carving_depth_mm
Type
number
mặc định 6 (high), 3 (low)
Description
Độ sâu chạm khắc của phù điêu, từ 0 đến 60 milimét. Khi remove_base được đặt thành true, giá trị 0 sẽ để lại một mô hình rỗng. Tác vụ vẫn thành công và tốn 20 tín dụng, nhưng các tệp GLB và STL của nó sẽ không có hình học.

Name
remove_base
Type
boolean
mặc định false
Description
Có cắt bỏ nền và không tạo tấm đế hay không. Khi giá trị này là true, removal_threshold sẽ xác định phần nào được tính là nền. Meshy luôn kiểm tra removal_threshold dù giá trị này là gì.

Chỉ áp dụng khi remove_base = true

Name
removal_threshold
Type
number
mặc định 0.01
Description
Ngưỡng độ sâu mà bên dưới đó Meshy sẽ cắt bỏ nền, từ 0.01 đến 1, trong đó bản đồ độ sâu chạy từ 0 đến 1. Một giá trị cao có thể cắt bỏ toàn bộ phù điêu và để lại mô hình rỗng, tác vụ này vẫn thành công và vẫn bị tính phí.

Name
base_thickness_mm
Type
number
mặc định 1, or 0 with remove_base
Description
Độ dày của tấm đế, từ 0.1 đến 10 milimét. Khi remove_base là true, hãy bỏ qua tham số này hoặc gửi 0.

Name
bend_mode
Type
string
mặc định off
Description
Có uốn cong phù điêu hay không, và uốn theo hướng nào. Khi giá trị không phải là off, bend_axis và bend_angle sẽ định hình độ uốn cong. Meshy luôn kiểm tra hai tham số này dù giá trị là gì.
Các giá trị khả dụng:
- off: phù điêu phẳng.
- convex: mặt trước phình ra ngoài.
- concave: mặt trước cong vào trong.

Chỉ áp dụng khi bend_mode = convex or concave

Name
bend_axis
Type
string
mặc định xz
Description
Cạnh nào sẽ bị cong theo độ uốn.
Các giá trị khả dụng:
- xz: các cạnh trái và phải.
- yz: các cạnh trên và dưới.
Name
bend_angle
Type
number
mặc định 60
Description
Cung mà độ uốn cong trải dài, từ 0 đến 360 độ. Dưới 1, phù điêu vẫn giữ phẳng.

Name
mesh_resolution
Type
integer
mặc định 1024
Description
Số điểm lưới dọc theo cạnh dài hơn của bức ảnh, từ 512 đến 2048. Giá trị cao hơn giữ được chi tiết tinh tế hơn và tạo ra tệp lớn hơn. Ở mức mặc định 1024, tệp GLB có dung lượng khoảng 40 đến 50 MB và tệp STL khoảng 80 đến 105 MB. Một bức ảnh vuông sẽ cho dung lượng lớn hơn. Ở mức 2048, chúng có dung lượng khoảng 150 MB và 300 MB. Độ uốn cong làm cho các tệp lớn hơn: tệp STL có thể đạt khoảng 800 MB ở mức 2048.

Giá trị trả về

202 Accepted, cùng với ID của tác vụ Phù điêu mới trong result.

Các trường hợp lỗi

Name
400 - Bad Request
Description
Không thể chạy yêu cầu. Thông báo lỗi sẽ cho biết vấn đề mà nó phát hiện. Ví dụ:
- Thiếu tham số: image_url chưa được gửi.
- Tham số không hợp lệ: Một tham số có kiểu dữ liệu sai, nằm ngoài phạm vi cho phép, hoặc không phải là một trong các giá trị khả dụng của nó. Ví dụ, variant không phải là high hay low, hoặc mesh_resolution không phải là số nguyên từ 512 đến 2048.
- Độ dày đế: base_thickness_mm không phải là 0 khi remove_base được đặt thành true, hoặc thấp hơn 0.1 khi không có nó.
- URL không thể truy cập: Meshy không thể tải xuống ảnh từ image_url, ví dụ do URL trả về 404 hoặc hết thời gian chờ.
- Ảnh không hợp lệ: Ảnh không phải là tệp JPG, JPEG, PNG, hoặc WebP, có dung lượng trên 20 MB, nhỏ hơn 32 × 32 pixel, có quá nhiều pixel, hoặc không thể đọc được.
- Tỷ lệ khung hình cực đoan: Cạnh dài hơn của ảnh dài gấp hơn khoảng 16 lần cạnh ngắn hơn.
Sửa lại yêu cầu, sau đó gửi lại. Meshy không tính phí cho yêu cầu này. Xem Lỗi.
Name
401 - Unauthorized
Description
Khóa API bị thiếu hoặc không hợp lệ. Kiểm tra tiêu đề Authorization.
Name
402 - Payment Required
Description
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. 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 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.
Name
403 - Forbidden
Description
Kiểm duyệt nội dung đã chặn ảnh này. Meshy không tính phí cho yêu cầu này. Hãy gửi một ảnh khác.
Name
429 - Too Many Requests
Description
Một trong các giới hạn sau đã đạt đến:
- Bạn đã gửi quá nhiều yêu cầu. Hãy đợi, sau đó thử lại. Xem Giới hạn tần suất.
- Có quá nhiều tác vụ của bạn đang chờ xử lý hoặc đang chạy. Hãy đợi một số tác vụ hoàn thành, sau đó thử lại.
- Trên gói không giới hạn nhưng không còn tín dụng, bạn đã đạt đến số lượng tác vụ có thể chạy mà không cần tín dụng. Hãy đợi một tác vụ hoàn thành, hoặc nạp thêm tín dụng.

Nếu một kiểm tra an toàn từ chối ảnh trong khi tác vụ đang chạy, tác vụ sẽ thất bại với task_error.type được đặt thành invalid_input và task_error.code được đặt thành provider_content_refused. Meshy sẽ hoàn lại tín dụng của tác vụ. Hãy gửi một ảnh khác. Xem Lỗi.

GET/openapi/v1/relief/:id

Lấy tác vụ Phù điêu

Trả về một tác vụ Phù điêu theo ID của nó.

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Tham số

Name
id
Type
path
Description
ID tác vụ từ phản hồi tạo tác vụ.

Giá trị trả về

Đối tượng tác vụ Phù điêu.

DELETE/openapi/v1/relief/:id

Xóa một tác vụ Phù điêu

Xóa vĩnh viễn một tác vụ Phù điêu, bao gồm mô hình, bản đồ độ sâu, và dữ liệu của nó. Bạn không thể hoàn tác một thao tác xóa.

Request

DELETE

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20 \
  -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 keeps 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."
}

Tham số đường dẫn

Name
id
Type
path
Description
ID của tác vụ cần xóa.

Trạng thái tác vụ

Xóa một tác vụ PENDING sẽ hoàn lại tín dụng đã dùng khi bạn tạo tác vụ đó.

Một tác vụ IN_PROGRESS không thể bị xóa. Yêu cầu sẽ trả về 409 Conflict, và tác vụ vẫn tiếp tục chạy. Meshy không hoàn lại tín dụng cho một tác vụ đã bắt đầu, nên việc xóa nó 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 hoặc FAILED, rồi mới xóa.

Xóa một tác vụ SUCCEEDED sẽ không hoàn lại tín dụng của nó. Một tác vụ FAILED đã được hoàn tín dụng khi nó thất bại.

Giá trị trả về

200 OK khi tác vụ được xóa, hoặc 409 Conflict khi tác vụ đang IN_PROGRESS.

GET/openapi/v1/relief

List Relief tasks

Trả về danh sách các tác vụ Phù điêu của bạn.

Request

GET

/openapi/v1/relief

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

Response

[
  {
    "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
    "type": "relief",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
    },
    "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000060000,
    "expires_at": 1700259260000,
    "task_error": null,
    "consumed_credits": 20
  }
]

Tham số

Name
page_num
Type
integer
Description
Số trang cần trả về. Bắt đầu và mặc định là 1.
Name
page_size
Type
integer
Description
Số lượng tác vụ trên mỗi trang, tối đa 100. Mặc định là 10. Meshy coi giá trị từ 101 đến 255 là 100, và giá trị lớn hơn sẽ trả về 400.
Name
sort_by
Type
string
Description
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

Trả về

Một danh sách được phân trang của đối tượng tác vụ Phù điêu.

GET/openapi/v1/relief/:id/stream

Stream một tác vụ Relief

Stream các cập nhật của một tác vụ Relief dưới dạng Server-Sent Events (SSE).

Request

GET

/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/stream

curl -N https://api.meshy.ai/openapi/v1/relief/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/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 (other task fields omitted here for brevity;
// each frame is the full task object).
event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Tham số

Name
id
Type
path
Description
ID tác vụ từ phản hồi tạo tác vụ.

Giá trị trả về

Một luồng đối tượng tác vụ Relief dưới dạng Server-Sent Events.

Mỗi sự kiện message chứa toàn bộ đối tượng tác vụ, giống như đối tượng mà Get a Relief task trả về. Trong khi tác vụ đang ở trạng thái PENDING hoặc IN_PROGRESS, các trường thay đổi giữa các sự kiện là progress, status, started_at, và preceding_tasks (chỉ xuất hiện khi còn các tác vụ đứng trước tác vụ này). model_urls, depth_map_url, và thumbnail_url sẽ nhận giá trị khi tác vụ đạt trạng thái SUCCEEDED. Một tác vụ chỉ tạo depth-map sẽ giữ model_urls là {} và thumbnail_url rỗng.

Một sự kiện error chỉ chứa status_code và message, vì vậy hãy kiểm tra tên sự kiện trước khi đọc status.

The Relief task object

Một Relief task object mô tả một bản phù điêu được tạo từ ảnh. model_urls, depth_map_url, và thumbnail_url luôn hiện diện, và rỗng cho đến khi tác vụ thành công.

The Relief Task Object

{
  "id": "0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20",
  "type": "relief",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/model.stl?Expires=***"
  },
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/depth.png?Expires=***",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0199c3d2-5a7e-7b14-9e2f-3c8d1a6b4f20/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000060000,
  "expires_at": 1700259260000,
  "task_error": null,
  "consumed_credits": 20
}

Depth map only

{
  "id": "0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31",
  "type": "relief",
  "model_urls": {},
  "depth_map_url": "https://assets.meshy.ai/***/tasks/0199c3d2-6b8f-7c25-8f3a-4d9e2b7c5a31/output/depth.png?Expires=***",
  "thumbnail_url": "",
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1700259230000,
  "task_error": null,
  "consumed_credits": 20
}

Name
id
Type
string
Description
ID của tác vụ. Hãy coi đây là một chuỗi không minh bạch (opaque) và đừng phụ thuộc vào định dạng của nó.
Name
type
Type
string
Description
Loại tác vụ, luôn là relief.
Name
model_urls
Type
object
Description
URL tải xuống cho mô hình phù điêu. Các tệp có thể lớn; mesh_resolution liệt kê các kích thước điển hình.
- Name
  glb
  Type
  string
  Description
  Tệp GLB, không có texture. Đơn vị của nó là mét. Không có đối với tác vụ chỉ tạo bản đồ độ sâu.
- Name
  stl
  Type
  string
  Description
  Cùng mô hình đó ở dạng tệp STL nhị phân. Đơn vị của nó là milimét, do đó nó mở ra ở kích thước thực của bản phù điêu, với trục Z hướng lên. Không có đối với tác vụ chỉ tạo bản đồ độ sâu.
Name
depth_map_url
Type
string
Description
URL tải xuống cho bản đồ độ sâu thang xám 16-bit mà bản phù điêu được tạo từ đó. Các pixel sáng hơn thì cao hơn. Các giá trị là độ cao tương đối, không phải milimét. Phần mềm khắc laser và CNC có thể sử dụng nó như một bản đồ độ cao. Tệp có kích thước khoảng 1 đến 2 MB. Rỗng nếu không có.
Name
thumbnail_url
Type
string
Description
URL tải xuống cho hình ảnh xem trước của mô hình phù điêu. Rỗng nếu không có hình nào được kết xuất, kể cả đối với tác vụ chỉ tạo bản đồ độ sâu.
Name
progress
Type
integer
Description
Tác vụ đã hoàn thành bao nhiêu, tính theo phần trăm. Giá trị là 0 cho đến khi tác vụ bắt đầu và 100 khi tác vụ thành công.
Name
status
Type
string
Description
Trạng thái của tác vụ, là một trong các giá trị PENDING, IN_PROGRESS, SUCCEEDED, hoặc FAILED.
Name
preceding_tasks
Type
integer
Description
Số lượng tác vụ đứng trước tác vụ này trong hàng đợi. Trường này bị bỏ qua khi giá trị là 0, vì vậy nó chỉ xuất hiện trong khi có các tác vụ đứng trước tác vụ này.
Name
created_at
Type
timestamp
Description
Thời điểm tác vụ được tạo, tính bằng mili giây Unix.
Name
started_at
Type
timestamp
Description
Thời điểm tác vụ bắt đầu, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ bắt đầu.
Name
finished_at
Type
timestamp
Description
Thời điểm tác vụ kết thúc, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ kết thúc.
Name
expires_at
Type
timestamp
Description
Thời điểm kết quả của tác vụ hết hạn, tính bằng mili giây Unix. Giá trị là 0 cho đến khi tác vụ kết thúc.
Name
task_error
Type
object
Description
Chi tiết lỗi khi tác vụ thất bại. Xem Lỗi.
Name
consumed_credits
Type
integer
Description
Số tín dụng mà tác vụ đã sử dụng: 20, hoặc 0 đối với tác vụ FAILED, mà Meshy sẽ hoàn lại.