UV Unwrap API

UV Unwrap API 会自动为现有的 3D 模型生成高质量的 UV Unwrap。请将其作为纹理处理之前的前置步骤使用——或者在任何时候，只要你需要为下游工具（Blender、Substance Painter、Unreal）提供干净、无重叠的 UV 布局。

输出结果是一个 “UV 白模”——与输入形状相同，但拥有全新的 UV 坐标，且不含真实 texture（其中包含一个 2×2 灰色占位 material，以保持 glTF material 插槽的有效性；标准工具会将其视为未上贴图状态）。

限制。 Auto UV 目前支持最多 40,000 个面 的 mesh——更大的模型会被返回 400 错误拒绝；请先运行 Remesh 以降低 polycount。四边形和多边形（n-gon）mesh 会在 UV 生成过程中被 三角化，因此输出始终是三角形 mesh。

POST/openapi/v1/uv-unwrap

创建 UV Unwrap 任务

此 endpoint 用于创建一个新的 UV Unwrap 任务。

参数

input_task_id 或 model_url 中必须且只能提供一个。如果两者都提供，则 input_task_id 优先顺序更高。

  • Name
    input_task_id
    Type
    string
    必选
    Description

    某个已完成的 Meshy API 任务的 ID，你希望对其 GLB 输出进行 UV-unwrap（例如 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 URIs，请使用 MIME type application/octet-stream。

    与 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。
  • 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

POST
/openapi/v1/uv-unwrap
# 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"
}
GET/openapi/v1/uv-unwrap/:id

获取 UV Unwrap 任务

此 endpoint 通过 ID 获取某个 UV Unwrap 任务的当前状态。

返回值

返回一个 UV Unwrap 任务对象。

Request

GET
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

请参阅下方的示例任务对象。

DELETE/openapi/v1/uv-unwrap/:id

删除 UV Unwrap 任务

永久删除一个 UV Unwrap 任务。该任务及其输出将变得不可访问。

仍处于 PENDING 状态的任务会被删除，且创建时消耗的 credits 会被退还。

已处于 IN_PROGRESS 状态的任务无法删除：请求会被拒绝并返回 409 Conflict，任务将继续运行。工作进程已经开始处理的任务，其 credits 无法退还，因此在运行过程中删除它将使你同时失去 credits 和结果。请等待其到达 SUCCEEDED、FAILED 或 CANCELED 状态后再删除。

处于终止状态（SUCCEEDED、FAILED 或 CANCELED）的任务会被删除， 且不会退还 credits。

Request

DELETE
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap

List UV Unwrap Tasks

返回调用者的 UV Unwrap 任务的分页列表，按最新排序。通过 page_num 和 page_size 进行标准分页。

Request

GET
/openapi/v1/uv-unwrap
curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap/:id/stream

流式获取 UV Unwrap 任务

以服务器发送事件（Server-Sent Events）的方式订阅任务 progress。每个 message 事件都会携带一个 UV Unwrap 任务对象；一旦任务到达 SUCCEEDED、FAILED 或 CANCELED 状态，该流将会关闭。

相较于轮询 GET /openapi/v1/uv-unwrap/:id，使用此方式可以更低延迟地获知任务完成情况。

Request

GET
/openapi/v1/uv-unwrap/:id/stream
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
}