UV Unwrap API

UV Unwrap API 为已有的 3D 模型自动生成高质量的 UV 展开。它通常作为贴图前的预处理步骤——或者在你需要把模型导出到 Blender、Substance Painter、Unreal 等下游工具继续工作时，提供一份干净、无重叠的 UV 布局。

输出是一个「UV 白模」——形状与输入一致，但携带全新的 UV 坐标，并使用一个 2×2 灰色占位材质（用于保持 glTF material slot 合法；标准工具会把它视作无纹理）。

限制说明。 Auto UV 目前仅支持 40,000 面以内的模型——超过会返回 400，请先 Remesh 降低面数。四边形 / 多边形（quad / n-gon）网格会在 UV 生成时被三角化，因此输出恒为三角网格。

POST/openapi/v1/uv-unwrap

创建 UV Unwrap 任务

创建一个新的 UV Unwrap 任务。

参数

input_task_id 与 model_url 二选一必填。如果两个都传，以 input_task_id 为准。

  • Name
    input_task_id
    Type
    string
    Required
    Description

    想要 UV 展开的 Meshy API 任务 ID（例如一个已完成的 Image to 3D、Text to 3D 或 Remesh 任务）。源任务的状态必须为 SUCCEEDED 且必须产出过 GLB 文件。

    如果源模型的面数超过 40,000 面的上限，请求会返回 400，请先调用 Remesh 降低面数。

  • Name
    model_url
    Type
    string
    Required
    Description

    通过公开可访问的 URL 或 Data URI 直接提供一个 3D 模型。仅支持 .glb —— 本接口只读取 glTF binary，不解析其他格式。如需 UV 展开其他格式（.fbx、.obj、.stl、.gltf），请先通过 Convert API 转成 .glb，再把转换出的 task ID 作为 input_task_id 传入，或者把转换产物的 GLB URL 作为本字段传入。

    Data URI 请使用 MIME type application/octet-stream。

    与 input_task_id 一样适用 40,000 面上限：超限模型会返回 400，请先 Remesh 降低面数。

返回值

响应的 result 字段是新建 UV Unwrap 任务的 id。

错误码

  • Name
    400 - Bad Request
    Description

    请求不合法。常见原因：

    • 缺少参数：input_task_id 或 model_url 至少要传一个。
    • 源任务无效：input_task_id 必须指向一个 SUCCEEDED 且有 GLB 产物的任务。
    • 面数超限：源模型面数超过 UV Unwrap 上限，请先 Remesh。
    • 格式不支持：model_url 指向的文件扩展名不在支持列表里。
    • URL 不可达：model_url 无法下载。
  • Name
    401 - Unauthorized
    Description

    鉴权失败，请检查 API key。

  • Name
    402 - Payment Required
    Description

    Credits 不足。UV Unwrap 每次消耗 5 credits。

  • Name
    404 - Not Found
    Description

    当前账号未开启该功能。UV Unwrap 在灰度期间通过 Statsig flag 控制，如需开通请联系 Meshy 支持。

  • Name
    429 - Too Many Requests
    Description

    超过速率限制。

请求

POST
/openapi/v1/uv-unwrap
# 链式调用：基于已有的 Meshy 任务
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"
    }'

# 或者通过公开 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"
    }'

响应

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}
GET/openapi/v1/uv-unwrap/:id

获取 UV Unwrap 任务

按 ID 查询 UV Unwrap 任务的当前状态。

返回值

返回一个 UV Unwrap Task 对象。

请求

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 任务及其产物——删除后任务及输出文件均不可访问。

请求

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）。

请求

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 订阅任务进度。每条 message 事件携带一个 UV Unwrap Task 对象；当任务进入 SUCCEEDED、FAILED 或 CANCELED 后流自动关闭。

相比轮询 GET /openapi/v1/uv-unwrap/:id，流式获取在任务结束时延迟更低。

请求

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——产物保留输入几何、替换 UV 坐标、并使用一个默认灰色材质代替原贴图。

  • 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

    在当前任务前面排队的任务数。只有 status 为 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

    失败任务的错误详情。完整字段参考 Errors。

  • Name
    consumed_credits
    Type
    integer
    Description

    该任务消耗的 credits。失败任务返回 0（失败自动退款）。UV Unwrap 成功时收取 5 credits。

示例 UV Unwrap Task 对象

{
  "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
}