浮雕 API
将一张照片转换为浅浮雕 3D 模型和 16 位深度图，适用于 3D 打印、激光雕刻和 CNC 雕刻。
创建 Relief 任务
创建一个 Relief 任务。该任务会将照片转换为浮雕模型。任务成功后，会生成 GLB 文件和 STL 文件格式的模型、16 位灰度深度图以及预览图像。如果只想获取深度图，请将 should_generate_model 设置为 false。
该任务在后台运行。
Relief 任务不能作为其他 endpoint（例如 Remesh、Convert 或 Auto Split）的输入。此类请求会返回 403。
Request
# 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"
}
参数
- Name
- image_url
- Type
- string
- 必选
- Description
要转换为浮雕的照片，可以是公开可访问的 URL，或 data URI（
data:image/png;base64,...）。图片必须是 JPG、JPEG、PNG 或 WebP 文件，大小不超过 20 MB，且尺寸至少为 32 × 32 像素。其长边最多约为短边的 16 倍。不符合要求的图片会返回
400。Meshy 会在生成浮雕前将透明区域填充为黑色。
- Name
- variant
- Type
- string
- 默认值 low
- Description
浮雕样式。它决定深度图的形状，并设置默认的
carving_depth_mm。可用值：
high：雕刻更深，适用于 3D 打印件。low：雕刻较浅，适用于激光雕刻、CNC 雕刻和薄匾牌。
发送
null或""与不传该参数效果相同。其他任何值都会返回400。
- Name
- should_generate_model
- Type
- boolean
- 默认值 true
- Description
是否构建浮雕模型。设置为
false可得到仅含深度图的任务，不生成模型和预览图像。Meshy 仍会检查尺寸、雕刻、底座、弯曲和分辨率等参数，但不会使用它们。此设置不会改变积分花费。
- Name
- size_mm
- Type
- number
- 默认值 60
- Description
照片长边在模型上的长度（在任何弯曲之前以平展状态测量），范围为
20到250毫米。启用remove_base后，模型可以更小。
- Name
- carving_mode
- Type
- string
- 默认值 emboss
- Description
主体是凸出于底板，还是被刻入底板。
可用值：
emboss：照片中距离较近的部分凸出。engrave：深度被反转，距离较近的部分被刻入。
两种模式下的深度图相同。
- Name
- carving_depth_mm
- Type
- number
- 默认值 6 (high), 3 (low)
- Description
浮雕的雕刻深度，范围为
0到60毫米。当remove_base设置为true时，0会生成一个空模型。任务仍会成功，并花费 20 积分，其 GLB 和 STL 文件不含任何 geometry。
- Name
- remove_base
- Type
- boolean
- 默认值 false
- Description
是否裁去背景并不生成底板。设置为
true时，removal_threshold决定哪些部分算作背景。无论是否设置，Meshy 都会检查removal_threshold。
remove_base = true- Name
- removal_threshold
- Type
- number
- 默认值 0.01
- Description
Meshy 据此裁去背景的深度阈值，范围为
0.01到1，深度图的取值范围为0到1。较高的值可能会裁去整个浮雕，留下空模型，但任务仍会成功并照常计费。
- Name
- base_thickness_mm
- Type
- number
- 默认值 1, or 0 with remove_base
- Description
底板的厚度，范围为
0.1到10毫米。当remove_base为true时，请省略该参数或传入0。
- Name
- bend_mode
- Type
- string
- 默认值 off
- Description
是否弯曲浮雕，以及朝哪个方向弯曲。当该值不为
off时，bend_axis和bend_angle决定弯曲的形状。无论取值如何，Meshy 都会检查它们。可用值：
off：平面浮雕。convex：正面向外凸起。concave：正面向内凹陷。
bend_mode = convex or concave- Name
- bend_axis
- Type
- string
- 默认值 xz
- Description
弯曲卷起的是哪一组边缘。
可用值：
xz：左右两侧边缘。yz：上下两侧边缘。
- Name
- bend_angle
- Type
- number
- 默认值 60
- Description
弯曲所跨越的弧度，范围为
0到360度。低于1时，浮雕保持平面状态。
- Name
- mesh_resolution
- Type
- integer
- 默认值 1024
- Description
沿照片长边方向的 mesh 点数，范围为
512到2048。较高的值能保留更精细的细节，但会生成更大的文件。在默认值1024下，GLB 文件约为 40 到 50 MB，STL 文件约为 80 到 105 MB。方形照片会生成偏大的文件体积。在2048时，文件大小分别约为 150 MB 和 300 MB。弯曲会使文件更大：在2048下，STL 文件可能达到约 800 MB。
返回
202 Accepted，在 result 中返回新建 Relief 任务的 ID。
失败情形
- Name
400 - Bad Request- Description
请求无法运行。错误消息会说明具体发现了哪种问题。例如：
- 缺少参数：未发送
image_url。 - 参数无效：某个参数类型错误、超出取值范围，或不属于其可用值之一。例如，
variant既不是high也不是low，或者mesh_resolution不是512到2048之间的整数。 - 底座厚度：
remove_base设置为true时base_thickness_mm不为0，或在未设置时低于0.1。 - URL 无法访问：Meshy 无法下载
image_url指向的图片，例如 URL 返回404或超时。 - 图片无效：图片不是 JPG、JPEG、PNG 或 WebP 文件，超过 20 MB，尺寸小于 32 × 32 像素，像素过多，或无法读取。
- 长宽比极端：图片长边超过短边约 16 倍。
请修正请求后重新发送。Meshy 不会就此收费。参见Errors。
- 缺少参数：未发送
- Name
401 - Unauthorized- Description
API key 缺失或无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
例如：
- 积分不足：账户没有足够的积分来执行此任务，或账户已达到积分限额。请检查你的积分 balance，然后重试。
- 免费方案：创建任务需要付费方案。请在你的subscription 设置中升级方案，然后重试。
- Name
403 - Forbidden- Description
内容 moderation 拦截了该图片。Meshy 不会就此请求收费。请发送其他图片。
- Name
429 - Too Many Requests- Description
达到了以下某项限制：
- 你发送的请求过多。请稍候后重试。参见速率限制。
- 排队或正在运行的任务过多。请等待部分任务完成后重试。
- 在积分已用尽的无限制方案下，达到了可在无积分情况下运行的任务数量上限。请等待某个任务完成，或增加积分。
如果安全检查在任务运行期间拒绝了该图片，任务会失败，task_error.type 被设置为 invalid_input，task_error.code 被设置为 provider_content_refused。Meshy 会退还该任务的积分。请发送其他图片。参见Errors。
获取 Relief 任务
根据 ID 返回一个 Relief 任务。
Request
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
}
删除浮雕任务
永久删除一个浮雕任务，包括其模型、深度图和数据。删除后无法撤销。
Request
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."
}
路径参数
- Name
- id
- Type
- path
- Description
要删除的任务的 ID。
任务状态
删除一个 PENDING 任务会退还创建该任务时所用的积分。
IN_PROGRESS 任务无法删除。该请求会返回 409 Conflict，
任务会继续运行。Meshy 不会为已经开始的任务退款，
因此删除它会让你同时损失积分和结果。请等待任务
变为 SUCCEEDED 或 FAILED 状态后再删除。
删除一个 SUCCEEDED 任务不会退还其积分。FAILED 任务在失败时已经退过款了。
返回值
任务删除成功时返回 200 OK；当任务处于
IN_PROGRESS 状态时返回 409 Conflict。
获取浮雕任务列表
返回你的浮雕任务列表。
Request
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
}
]
参数
- Name
- page_num
- Type
- integer
- Description
要返回的页码。起始值和默认值均为
1。
- Name
- page_size
- Type
- integer
- Description
每页返回的任务数量，最多为
100。默认值为10。Meshy 会将101到255之间的值视为100，更大的值会返回400。
- Name
- sort_by
- Type
- string
- Description
排序方式。
可用值：
+created_at：最早优先-created_at：最新优先
返回值
分页的浮雕任务对象列表。
流式获取浮雕任务
以服务器发送事件（SSE）的形式流式传输浮雕任务的更新。
Request
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
}
参数
- Name
- id
- Type
- path
- Description
创建响应中返回的任务 ID。
返回
以服务器发送事件的形式返回浮雕任务对象的流。
每个 message 事件都包含完整的任务对象，与获取浮雕任务返回的对象相同。当任务处于 PENDING 或 IN_PROGRESS 状态时，事件之间发生变化的字段是 progress、status、started_at 和 preceding_tasks（仅在该任务前面还有其他任务排队时才会出现）。model_urls、depth_map_url 和 thumbnail_url 会在任务达到 SUCCEEDED 状态后被赋值。仅生成深度图的任务会保持 model_urls 为 {}，且 thumbnail_url 为空。
error 事件仅包含 status_code 和 message，因此在读取 status 之前请先检查事件名称。
Relief 任务对象
Relief 任务对象描述由一张照片生成的一个浮雕。model_urls、depth_map_url 和 thumbnail_url 始终存在，在任务成功之前为空。
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。请将其视为不透明字符串，不要依赖其格式。
- Name
- type
- Type
- string
- Description
任务类型，始终为
relief。
- Name
- model_urls
- Type
- object
- Description
浮雕模型的下载 URL。文件可能很大；
mesh_resolution列出了典型大小。- Name
glb- Type
- string
- Description
不带 texture 的 GLB 文件。其单位为米。仅生成深度图的任务不会包含此字段。
- Name
stl- Type
- string
- Description
同一模型的二进制 STL 文件。其单位为毫米，因此打开时就是浮雕的实际大小，Z 轴朝上。仅生成深度图的任务不会包含此字段。
- Name
- depth_map_url
- Type
- string
- Description
浮雕所基于的 16 位灰度深度图的下载 URL。像素越亮，高度越高。这些值是相对高度，并非以毫米计。激光雕刻和 CNC 软件可以将其用作高度图。文件大小约为 1 到 2 MB。若不存在则为空。
- Name
- thumbnail_url
- Type
- string
- Description
浮雕模型预览图的下载 URL。若未渲染预览图则为空，包括仅生成深度图的任务。
- Name
- progress
- Type
- integer
- Description
任务完成的百分比。在任务开始前为
0，成功后为100。
- Name
- status
- Type
- string
- Description
任务状态，为
PENDING、IN_PROGRESS、SUCCEEDED或FAILED之一。
- Name
- preceding_tasks
- Type
- integer
- Description
队列中排在此任务之前的任务数量。当值为
0时该字段会被省略，因此只有在有任务排在此任务之前时才会出现。
- Name
- created_at
- Type
- timestamp
- Description
任务创建时间，以 Unix 毫秒表示。
- Name
- started_at
- Type
- timestamp
- Description
任务开始时间，以 Unix 毫秒表示。在任务开始前为
0。
- Name
- finished_at
- Type
- timestamp
- Description
任务完成时间，以 Unix 毫秒表示。在任务完成前为
0。
- Name
- expires_at
- Type
- timestamp
- Description
任务结果过期时间，以 Unix 毫秒表示。在任务完成前为
0。
- Name
- task_error
- Type
- object
- Description
任务失败时的错误详情。参见Errors。
- Name
- consumed_credits
- Type
- integer
- Description
任务消耗的积分数：
20，若任务为FAILED则为0，Meshy 会退还积分。