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。四边面和多边面 mesh 在 UV 生成过程中会被三角化，因此输出始终为三角形 mesh。

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

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

参数

input_task_id 和 model_url 中必须且只能提供其中一个。如果两者都提供了，则 input_task_id 优先。

  • Name
    input_task_id
    Type
    string
    必选
    Description

    一个已完成的 Meshy API 任务的 ID，你希望对其 GLB 输出进行 UV 展开（例如 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 展开，请先通过 Convert API 将其转换为 .glb，然后将得到的任务 ID 作为 input_task_id 传入，或在此处传入其 GLB 输出的 URL。

    对于 Data URI，请使用 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 任务。该任务及其输出结果将变得无法访问。

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

获取 UV Unwrap 任务列表

返回调用者的 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 Task object；当任务达到 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
}