UV Unwrap API
为现有的 3D 模型生成 UV Unwrap。请在为模型添加 texture 之前运行此任务，或者当 Blender、Substance Painter 或 Unreal 等工具需要一个干净、无重叠的 UV 布局时运行此任务。
输出结果是一个 UV 白模。它与输入模型的形状相同，拥有全新的 UV 坐标，且不含真实的 texture。它包含一个 2×2 的灰色占位 material，以确保 glTF 的 material 插槽保持有效，标准工具会将其视为未上色的模型。
UV Unwrap 支持最多 40,000 个面的 mesh。更大的模型将返回 400。如需减少面数，请先运行 Remesh。
Meshy 会在生成 UV 的过程中对四边形和 n 边形 mesh 进行三角化处理，因此输出结果始终是三角形 mesh。
创建 UV Unwrap 任务
创建一个 UV Unwrap 任务。
任务在后台运行。有关任务通常需要多长时间，请参阅处理时间。
Request
# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}'
# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"model_url": "https://example.com/path/to/model.glb"
}'
Response
{
"result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}
参数
- Name
- input_task_id
- Type
- string
- 必选
- Description
除非你发送
model_url，否则此项为必填。要进行 UV Unwrap 的 Meshy API 任务的 ID（其 GLB 输出将被解包），例如 Image to 3D、Text to 3D 或 Remesh 任务。该任务的状态必须为SUCCEEDED，并已生成 GLB 文件。该 mesh 最多可包含 40,000 个面。面数超过该值的 mesh 将返回
400。要减少面数，请先运行 Remesh。
- Name
- model_url
- Type
- string
- 必选
- Description
除非你发送
input_task_id，否则此项为必填。要解包的模型，可以是公开 URL 或 Data URI。如果两者都发送，Meshy 将使用input_task_id。模型必须是
.glb文件。要解包其他格式，请先使用 Convert API 将其转换为 GLB。通过
http或httpsURL 提供的文件最大为 400 MB，作为 Data URI 时最大为 100 MB。对于 Data URI，请使用 MIME typeapplication/octet-stream。超过 100 MB 的 GLB 不得使用 Draco 压缩。与
input_task_id相同的 40,000 面数限制同样适用。面数超过该值的 mesh 将返回400，因此请先运行 Remesh。
返回值
响应的 result 字段保存新 UV Unwrap 任务的 ID。
失败模式
- Name
400 - Bad Request- Description
请求无法运行。错误消息会说明发现的问题。例如：
- 缺少参数：既未发送
input_task_id，也未发送model_url。 - 输入任务无效：
input_task_id不是具有 GLB 结果的成功 API 任务。 - 面数超限：该 mesh 的面数超过了 UV Unwrap 所允许的上限。请先运行 Remesh。
- 模型格式无效：
model_url文件的扩展名不受支持。 - URL 不可访问：Meshy 无法下载
model_url文件。 - 模型文件过大：
model_url文件通过http或httpsURL 提供时超过 400 MB，或作为 Data URI 时超过 100 MB。 - 面数过多：
model_url文件超过 100 MB，且面数超过 10,000,000。请减少面数后重新发送文件。 - 模型文件不可读：
model_url文件超过 100 MB，且 Meshy 无法读取其文件头。例如，这是一个经过 Draco 压缩的 GLB。 - 模型头部过于复杂：
model_url文件超过 100 MB，且其文件头中包含过多的 mesh、节点或记录，无法完成检查。请减少文件中的对象数量后重新发送。
请修正请求后重新发送。参见 Errors。
- 缺少参数：既未发送
- Name
401 - Unauthorized- Description
API key 缺失或无效。请检查
Authorization请求头。
- Name
402 - Payment Required- Description
例如：
- 积分不足：账户没有足够的积分来执行该任务，或账户已达到积分限额。一个 UV Unwrap 任务消耗 5 积分。请检查你的积分余额，然后重试。
- 免费计划：创建任务需要付费计划。请在你的subscription 设置中升级你的计划，然后重试。
- Name
403 - Forbidden- Description
input_task_id是一个浮雕模型，此 endpoint 无法对其进行 UV Unwrap。消息为This model type does not support this operation。请发送其他模型。
- Name
404 - Not Found- Description
input_task_id与你的任何任务都不匹配。请检查任务 ID，然后重新发送请求。
- Name
429 - Too Many Requests- Description
你已超出速率限制。请等待后重试。参见速率限制。
获取 UV Unwrap 任务
根据 ID 返回某个 UV Unwrap 任务的当前状态。
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
有关响应示例，请参阅UV Unwrap 任务对象示例。
返回值
删除 UV Unwrap 任务
永久删除一个 UV Unwrap 任务，包括其输出结果。删除操作无法撤销。
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
任务状态
删除 PENDING 状态的任务会退还创建该任务时使用的积分。
IN_PROGRESS 状态的任务无法被删除。该请求会返回 409 Conflict，
任务会继续运行。Meshy 不会为已经开始的任务退还积分，
因此删除它会让你同时损失积分和结果。请等待任务
变为 SUCCEEDED、FAILED 或 CANCELED 状态后再进行删除。
删除处于最终状态（SUCCEEDED、FAILED 或 CANCELED）的任务
不会退还其积分。
列出 UV Unwrap 任务
返回您的 UV Unwrap 任务的分页列表，按最新创建时间排序。要翻页浏览列表，请使用 page_num 和 page_size。
Request
curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
流式获取 UV Unwrap 任务进度
以服务器发送事件（SSE）的形式流式传输 UV Unwrap 任务的更新。每个 message 事件都会携带一个 UV Unwrap 任务对象。当任务达到 SUCCEEDED、FAILED 或 CANCELED 状态时，流会关闭。
如果想更早获知任务已完成，请使用此 endpoint，而不是轮询 GET /openapi/v1/uv-unwrap/:id。
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N
UV Unwrap 任务对象
一个 UV Unwrap 任务对象描述了一次 3D 模型的 UV 展开。它保存了任务的状态、progress，以及任务成功时的模型文件。
Example UV Unwrap Task Object
{
"id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
"type": "uv-unwrap",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
"progress": 100,
"status": "SUCCEEDED",
"preceding_tasks": 0,
"created_at": 1716579120000,
"started_at": 1716579122000,
"finished_at": 1716579180000,
"expires_at": 1716665580000,
"task_error": {
"message": ""
},
"consumed_credits": 5
}
- Name
- id
- Type
- string
- Description
任务 ID。请将其视为一个不透明的字符串，不要依赖其格式。
- Name
- type
- Type
- string
- Description
任务类型，始终为
uv-unwrap。
- Name
- model_urls
- Type
- object
- Description
UV 白模的签名下载 URL。UV Unwrap 始终返回一个
glb键。该模型保留了输入的 geometry，拥有全新的 UV 坐标，并使用默认的灰色 material 代替 texture。
- Name
- thumbnail_url
- Type
- string
- Description
UV 白模的 PNG 预览图的签名下载 URL。
- Name
- progress
- Type
- integer
- Description
任务完成的程度，以百分比表示，范围从
0到100。
- Name
- status
- Type
- string
- Description
任务状态，取值为
PENDING、IN_PROGRESS、SUCCEEDED、FAILED或CANCELED之一。
- Name
- preceding_tasks
- Type
- integer
- Description
排在该任务之前的任务数量。仅在任务处于
PENDING状态时出现。
- 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
签名下载 URL 过期的时间，单位为 Unix 毫秒。
- Name
- task_error
- Type
- object
- Description
任务失败时的错误详情。参见错误。
- Name
- consumed_credits
- Type
- integer
- Description
任务消耗的积分数量。一次成功的 UV Unwrap 任务消耗 5 个积分。对于
FAILED的任务，该值为0，因为 Meshy 会在任务失败时退还积分。