UV Unwrap API

The UV Unwrap API automatically generates a high-quality UV unwrap for an existing 3D model. Use it as the prerequisite step before texturing — or any time you need a clean, non-overlapping UV layout for downstream tools (Blender, Substance Painter, Unreal).

The output is a "UV white model" — same shape as the input but with brand-new UV coordinates and no real texture (a 2×2 grey placeholder material is included to keep the glTF material slot valid; standard tools treat this as untextured).

Limitations. Auto UV currently supports meshes of up to 40,000 faces — larger models are rejected with a 400; run Remesh first to reduce the polycount. Quad and n-gon meshes are triangulated during UV generation, so the output is always a triangle mesh.

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

This endpoint creates a new UV Unwrap task.

Parameters

Exactly one of input_task_id or model_url is required. If both are provided, input_task_id takes priority.

  • Name
    input_task_id
    Type
    string
    Required
    Description

    The ID of a completed Meshy API task whose GLB output you wish to UV-unwrap (for example an Image to 3D, Text to 3D, or Remesh result). The source task must have a status of SUCCEEDED and have produced a GLB file.

    If the source mesh exceeds the face-count ceiling of 40,000 faces, the request will be rejected with a 400 and you should run Remesh first to bring the polycount down.

  • Name
    model_url
    Type
    string
    Required
    Description

    Provide a 3D model directly via a publicly accessible URL or data URI. Only .glb is supported — the API reads glTF binary and does not parse other formats. To UV-unwrap a model in another format (.fbx, .obj, .stl, .gltf), convert it to .glb first via the Convert API, then pass the resulting task ID as input_task_id or its GLB output URL here.

    For Data URIs, use the MIME type application/octet-stream.

    The same 40,000-face ceiling applies as for input_task_id: oversized meshes are rejected with a 400 — run Remesh first.

Returns

The result property of the response contains the id of the newly created UV Unwrap task.

Failure Modes

  • Name
    400 - Bad Request
    Description

    The request was unacceptable. Common causes:

    • Missing parameter: Either input_task_id or model_url must be provided.
    • Invalid input task: The input_task_id must refer to a successful task with a GLB result.
    • Face count exceeded: The source mesh has more faces than the UV Unwrap ceiling. Run Remesh first.
    • Invalid model format: The model_url points to a file with an unsupported extension.
    • Unreachable URL: The model_url could not be downloaded.
  • Name
    401 - Unauthorized
    Description

    Authentication failed. Please check your API key.

  • Name
    402 - Payment Required
    Description

    Insufficient credits to perform this task. UV Unwrap costs 5 credits per call.

  • Name
    404 - Not Found
    Description

    The feature is not enabled for your account. UV Unwrap is gated by a Statsig flag during rollout — contact Meshy support if you need access.

  • Name
    429 - Too Many Requests
    Description

    You have exceeded your rate limit.

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

Retrieve an UV Unwrap Task

This endpoint retrieves the current state of an UV Unwrap task by ID.

Returns

Returns an UV Unwrap Task object.

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

See the example task object below.

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

Delete an UV Unwrap Task

Permanently delete an UV Unwrap task. The task and its outputs become inaccessible.

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

Returns a paginated list of the caller's UV Unwrap tasks, newest first. Standard pagination via page_num and 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

Stream an UV Unwrap Task

Subscribe to task progress as Server-Sent Events. Each message event carries an UV Unwrap Task object; the stream closes once the task reaches SUCCEEDED, FAILED, or CANCELED.

Use this instead of polling GET /openapi/v1/uv-unwrap/:id for lower latency on completion.

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

The UV Unwrap Task Object

  • Name
    id
    Type
    string
    Description

    Unique identifier for the task.

  • Name
    type
    Type
    string
    Description

    Always uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    Pre-signed download URLs for the generated UV white model. UV Unwrap always returns a single glb entry — the output preserves the input geometry, swaps in fresh UV coordinates, and uses a default grey material in place of any texture.

  • Name
    thumbnail_url
    Type
    string
    Description

    Pre-signed URL to a PNG preview of the UV white model.

  • Name
    progress
    Type
    integer
    Description

    Task progress, from 0 to 100.

  • Name
    status
    Type
    string
    Description

    One of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Number of tasks queued ahead of this one. Present while status is PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of task creation, in milliseconds.

  • Name
    started_at
    Type
    timestamp
    Description

    Timestamp of when processing began, in milliseconds. 0 until started.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp of completion, in milliseconds. 0 until finished.

  • Name
    expires_at
    Type
    timestamp
    Description

    Timestamp after which the signed download URLs expire, in milliseconds.

  • Name
    task_error
    Type
    object
    Description

    Error details for failed tasks. See Errors for the full task_error object reference.

  • Name
    consumed_credits
    Type
    integer
    Description

    Credits consumed by this task. Returns 0 for FAILED tasks (credits are refunded on failure). UV Unwrap charges 5 credits on success.

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
}