UV Unwrap API
UV Unwrap API 可为现有的 3D 模型自动生成高质量的 UV unwrap。可将其用作贴图 texture 之前的前置步骤——或在任何需要为下游工具（Blender、Substance Painter、Unreal）提供干净、无重叠的 UV 布局时使用。
输出结果是一个 “UV 白模”——与输入模型形状相同，但带有全新的 UV 坐标，且没有真实 texture（为保持 glTF material 插槽有效，其中包含一个 2×2 的灰色占位 material；标准工具会将其视为未贴图状态）。
限制。 Auto UV 目前支持最多 40,000 个面 的 mesh——更大的模型会被拒绝并返回 400；请先运行 Remesh 以降低 polycount。四边形和 N 边形 mesh 会在 UV 生成过程中被三角化，因此输出结果始终为三角形 mesh。
创建 UV Unwrap 任务
此 endpoint 用于创建一个新的 UV Unwrap 任务。
该任务会在后台运行。关于通常需要多长时间，请参阅处理时间。
参数
input_task_id 或 model_url 两者必须且只能提供其中一个。如果两者都提供，则 input_task_id 具有更高的优先顺序。
- Name
- input_task_id
- Type
- string
- 必选
- Description
你希望进行 UV-unwrap 的、已完成的 Meshy API 任务的 ID，该任务的 GLB 输出将作为处理对象（例如 Image to 3D、Text to 3D 或 Remesh 的结果）。源任务的状态必须为
SUCCEEDED，且已生成 GLB 文件。如果源 mesh 超过了 40,000 个面的上限，请求将被拒绝并返回
400，此时你应先运行 Remesh 以降低 polycount。
- Name
- model_url
- Type
- string
- 必选
- Description
通过可公开访问的 URL 或 data URI 直接提供 3D 模型。仅支持
.glb—— 该 API 读取的是 glTF 二进制格式，不会解析其他格式。若要对其他格式（.fbx、.obj、.stl、.gltf）的模型进行 UV-unwrap，请先通过 Convert API 将其转换为.glb，然后将生成的任务 ID 作为input_task_id传入，或在此处传入其 GLB 输出的 URL。对于 Data URI，请使用 MIME type
application/octet-stream。最大文件大小：
http或httpsURL 为 400 MB，data:URI 为 100 MB。超过 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 结果的任务。 - 超出面数限制：源 mesh 的面数超过了 UV Unwrap 的上限。请先运行 Remesh。
- 无效的模型格式：
model_url指向的文件扩展名不受支持。 - URL 无法访问：无法下载
model_url指向的文件。 - 模型文件过大：
model_url文件超过了 400 MB（http或httpsURL）或 100 MB（data:URI）的限制。 - 面数过多：
model_url文件超过 100 MB，且面数超过 10,000,000。请减少面数后重新发送文件。 - 模型文件无法读取：
model_url文件超过 100 MB，且其文件头无法读取，例如经过 Draco 压缩的 GLB。 - 模型文件头过于复杂：
model_url文件超过 100 MB，且其文件头中包含过多需要检查的 mesh、节点或记录。请减少文件中的对象数量后重新发送。
- 缺少参数：必须提供
- Name
401 - Unauthorized- Description
authentication 失败。请检查你的 API key。
- Name
402 - Payment Required- Description
credits 不足，无法执行此任务。UV Unwrap 每次调用花费 5 credits。
- Name
404 - Not Found- Description
你的账户未启用此功能。UV Unwrap 在灰度发布期间由 Statsig 开关控制 —— 如需获取权限，请联系 Meshy 支持团队。
- Name
429 - Too Many Requests- Description
你已超出速率限制。
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"
}
获取 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 任务。该任务及其输出结果将变得不可访问。
仍处于 PENDING 状态的任务会被删除，并退还创建时消耗的 credits。
已处于 IN_PROGRESS 状态的任务无法被删除：该请求会被拒绝并返回 409 Conflict，任务会继续运行。worker 已经开始处理的任务所消耗的 credits 是不可退还的，因此在运行过程中删除它会使你同时失去 credits 和结果。请等待任务进入 SUCCEEDED、FAILED 或 CANCELED 状态后再删除。
处于终止状态（SUCCEEDED、FAILED 或 CANCELED）的任务会被删除，且不会退还 credits。
Request
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
List UV Unwrap Tasks
返回调用者的 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 任务进度
以 Server-Sent Events 的方式订阅任务 progress。每个 message 事件都携带一个UV Unwrap 任务对象；当任务进入 SUCCEEDED、FAILED 或 CANCELED 状态时，流将关闭。
相比轮询 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 任务对象
- Name
- id
- Type
- string
- Description
任务的唯一标识符。
- 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
任务创建的 timestamp，单位为毫秒。
- Name
- started_at
- Type
- timestamp
- Description
开始处理的 timestamp，单位为毫秒。开始前为
0。
- Name
- finished_at
- Type
- timestamp
- Description
完成的 timestamp，单位为毫秒。完成前为
0。
- Name
- expires_at
- Type
- timestamp
- Description
签名下载 URL 失效的 timestamp，单位为毫秒。
- Name
- task_error
- Type
- object
- Description
失败任务的错误详情。完整的
task_error对象参考请参阅 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
此任务消耗的 credits。对于
FAILED的任务返回0（失败时会退还 credits）。UV Unwrap 成功后扣除 5 个 credits。
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
}