lowpoly retires Oct 30, 2026. Please switch models before these dates to avoid request errors. See all deprecations

UV Unwrap API

Generate a UV unwrap for an existing 3D model. Run it before you texture the model, or when a tool such as Blender, Substance Painter, or Unreal needs a clean, non-overlapping UV layout.

The output is a UV white model. It has the same shape as the input, fresh UV coordinates, and no real texture. It includes a 2×2 grey placeholder material so that the glTF material slot stays valid, and standard tools treat it as untextured.

UV Unwrap supports meshes of up to 40,000 faces. A larger model returns 400. To reduce the face count, run Remesh first.

Meshy triangulates quad and n-gon meshes during UV generation, so the output is always a triangle mesh.

POST/openapi/v1/uv-unwrap

Create a UV Unwrap task

Creates a UV Unwrap task.

The task runs in the background. For how long a task usually takes, see Processing times.

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

Parameters

  • Name
    input_task_id
    Type
    string
    Required
    Description

    Required unless you send model_url. The ID of a Meshy API task whose GLB output you want to unwrap, for example an Image to 3D, Text to 3D, or Remesh task. The task must have the status SUCCEEDED and have produced a GLB file.

    The mesh can have at most 40,000 faces. A mesh with more returns 400. To reduce the face count, run Remesh first.

  • Name
    model_url
    Type
    string
    Required
    Description

    Required unless you send input_task_id. The model to unwrap, as a public URL or a data URI. If you send both, Meshy uses input_task_id.

    The model must be a .glb file. To unwrap another format, convert it to GLB with the Convert API first.

    The file can be at most 400 MB from an http or https URL, or 100 MB as a data URI. For a data URI, use the MIME type application/octet-stream. A GLB over 100 MB must not use Draco compression.

    The same 40,000-face limit applies as for input_task_id. A mesh with more returns 400, so run Remesh first.

Returns

The result field of the response holds the ID of the new UV Unwrap task.

Failure modes

  • Name
    400 - Bad Request
    Description

    The request can't run. The error message says which problem it found. For example:

    • Missing parameter: Neither input_task_id nor model_url was sent.
    • Invalid input task: input_task_id isn't a successful API task with a GLB result.
    • Face count exceeded: The mesh has more faces than UV Unwrap allows. Run Remesh first.
    • Invalid model format: The model_url file has an unsupported extension.
    • Unreachable URL: Meshy can't download the model_url file.
    • Model file too large: The model_url file is over 400 MB from an http or https URL, or over 100 MB as a data URI.
    • Too many faces: The model_url file is over 100 MB and has more than 10,000,000 faces. Reduce the face count, then send the file again.
    • Unreadable model file: The model_url file is over 100 MB, and Meshy can't read its header. For example, it's a Draco-compressed GLB.
    • Model header too complex: The model_url file is over 100 MB, and its header has too many meshes, nodes, or records to check. Reduce the number of objects in the file, then send it again.

    Fix the request, then send it again. See Errors.

  • Name
    401 - Unauthorized
    Description

    The API key is missing or invalid. Check the Authorization header.

  • Name
    402 - Payment Required
    Description

    For example:

    • Insufficient credits: The account doesn't have enough credits for this task, or the account reached a credit limit. A UV Unwrap task costs 5 credits. Check your credit balance, then retry.
    • Free plan: Creating a task requires a paid plan. Upgrade your plan in your subscription settings, then retry.
  • Name
    403 - Forbidden
    Description

    input_task_id is a bas-relief model, which this endpoint can't unwrap. The message is This model type does not support this operation. Send a different model.

  • Name
    404 - Not Found
    Description

    input_task_id doesn't match any of your tasks. Check the task ID, then send the request again.

  • Name
    429 - Too Many Requests
    Description

    You exceeded your rate limit. Wait, then retry. See Rate limits.

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

Get a UV Unwrap task

Returns a UV Unwrap task's current state by its ID.

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

For an example response, see the example UV Unwrap task object.

Returns

The UV Unwrap task object.

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

Delete a UV Unwrap task

Permanently deletes a UV Unwrap task, including its outputs. You can't undo a delete.

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

Task status

Deleting a PENDING task refunds the credits it used when you created it.

An IN_PROGRESS task can't be deleted. The request returns 409 Conflict, and the task keeps running. Meshy doesn't refund a task that has started, so deleting it would cost you both the credits and the result. Wait for it to reach SUCCEEDED, FAILED, or CANCELED, then delete it.

Deleting a task in a final status (SUCCEEDED, FAILED, or CANCELED) doesn't refund its credits.

GET/openapi/v1/uv-unwrap

List UV Unwrap tasks

Returns a paginated list of your UV Unwrap tasks, newest first. To page through the list, use 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 a UV Unwrap task

Streams a UV Unwrap task's updates as Server-Sent Events (SSE). Each message event carries a UV Unwrap task object. The stream closes when the task reaches SUCCEEDED, FAILED, or CANCELED.

To learn sooner that the task finished, use this endpoint instead of polling 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

The UV Unwrap task object

A UV Unwrap task object describes one UV unwrap of a 3D model. It holds the status, the progress, and the model file when the task succeeds.

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
}
  • Name
    id
    Type
    string
    Description

    The task ID. Treat it as an opaque string, and don't rely on its format.

  • Name
    type
    Type
    string
    Description

    The task type, always uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    Signed download URLs for the UV white model. UV Unwrap always returns a single glb key. The model keeps the input geometry, has fresh UV coordinates, and uses a default grey material instead of a texture.

  • Name
    thumbnail_url
    Type
    string
    Description

    Signed download URL for a PNG preview image of the UV white model.

  • Name
    progress
    Type
    integer
    Description

    How much of the task is done, as a percentage from 0 to 100.

  • Name
    status
    Type
    string
    Description

    The task status, one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, or CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    The number of tasks ahead of this one in the queue. Present while the task is PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Time the task was created, in Unix milliseconds.

  • Name
    started_at
    Type
    timestamp
    Description

    Time the task started, in Unix milliseconds. It's 0 until the task starts.

  • Name
    finished_at
    Type
    timestamp
    Description

    Time the task finished, in Unix milliseconds. It's 0 until the task finishes.

  • Name
    expires_at
    Type
    timestamp
    Description

    Time the signed download URLs expire, in Unix milliseconds.

  • Name
    task_error
    Type
    object
    Description

    The error details when the task fails. See Errors.

  • Name
    consumed_credits
    Type
    integer
    Description

    The number of credits the task used. A successful UV Unwrap task costs 5 credits. It's 0 for a FAILED task, because Meshy refunds the credits when a task fails.