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
你希望对其 GLB 输出进行 UV-unwrap 的已完成 Meshy API 任务的 ID（例如 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。文件大小上限：100 MB。
与
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指向的文件超过 100 MB。
- 缺少参数：必须提供
- 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，
任务将继续运行。由于工作进程已经开始处理的任务所消耗的 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 Task 对象；当任务到达 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
任务创建的时间戳，单位为毫秒。
- Name
- started_at
- Type
- timestamp
- Description
开始处理的时间戳，单位为毫秒。开始前为
0。
- Name
- finished_at
- Type
- timestamp
- Description
完成的时间戳，单位为毫秒。完成前为
0。
- Name
- expires_at
- Type
- timestamp
- Description
签名下载 URL 过期的时间戳，单位为毫秒。
- 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
}