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

Convert API

The Convert API allows you to convert existing 3D models into different file formats.

POST/openapi/v1/convert

Create a Convert Task

This endpoint creates a new format conversion task.

The task runs in the background. For how long it usually takes, see Processing Times.

Parameters

Only 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 task whose model you wish to convert. The task must have a status of SUCCEEDED.

  • Name
    model_url
    Type
    string
    Required
    Description

    A publicly accessible URL or data URI pointing to a 3D model file. Supported formats: .glb, .gltf, .obj, .fbx, .stl. For Data URIs, use the MIME type: application/octet-stream.

    Maximum file size: 400 MB for an http or https URL, 100 MB for a data: URI.

    A GLB, glTF, FBX or OBJ file over 100 MB can have at most 10,000,000 faces. Faces are counted as triangles: a quad counts as 2, and a mesh drawn more than once counts once per copy. Over 100 MB, an FBX file must be binary FBX 7.1 or newer, and a GLB or glTF file must not use Draco compression.

  • Name
    target_formats
    Type
    string[]
    Required
    Description

    A list of output formats for the converted model. Available values: glb, fbx, obj, usdz, blend, stl, 3mf.

Returns

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

Failure Modes

  • 400 - Bad Request

The request was unacceptable. Common causes:

  • Missing parameter: Either model_url or input_task_id must be provided.
  • Missing target_formats: At least one target format must be specified.
  • Invalid input task: The input_task_id must refer to a successful task.
  • Invalid model format: The model_url points to a file with an unsupported extension.
  • Unreachable URL: The model_url could not be downloaded.
  • Model file too large: The model_url file exceeds 400 MB (http or https URL) or 100 MB (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.
  • ASCII FBX over 100 MB: The model_url file is an ASCII FBX over 100 MB. Send it as binary FBX or GLB.
  • Unreadable model file: The model_url file is over 100 MB and its header can't be read, for example a Draco-compressed GLB or glTF, or a binary FBX older than 7.1.
  • 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.
  • 401 - Unauthorized

Authentication failed. Please check your API key.

  • 402 - Payment Required

Insufficient credits to perform this task.

  • 429 - Too Many Requests

You have exceeded your rate limit.

Request

POST
/openapi/v1/convert
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/convert/:id

Retrieve a Convert Task

This endpoint retrieves a convert task by its ID.

Parameters

  • Name
    id
    Type
    path
    Description

    The ID of the convert task to retrieve.

Returns

The Convert Task object.

Request

GET
/openapi/v1/convert/:id
curl https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}
DELETE/openapi/v1/convert/:id

Delete a Convert Task

This endpoint permanently deletes a convert task, including all associated models and data. This action is irreversible.

Path Parameters

  • Name
    id
    Type
    path
    Description

    The ID of the convert task to delete.

Task Status

A task that is still PENDING is deleted and the credits consumed at create-time are refunded.

A task that is already IN_PROGRESS cannot be deleted: the request is rejected with 409 Conflict and the task keeps running. Credits for a task the worker has already started are not refundable, so deleting it mid-run would cost you the credits and the result both. Wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it.

A task in a terminal state (SUCCEEDED, FAILED or CANCELED) is deleted without a refund.

Returns

Returns 200 OK on success, or 409 Conflict when the task is IN_PROGRESS.

Request

DELETE
/openapi/v1/convert/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
GET/openapi/v1/convert

List Convert Tasks

This endpoint allows you to retrieve a list of convert tasks.

Parameters

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Page number for pagination.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Page size limit. Maximum allowed is 100 items.

  • Name
    sort_by
    Type
    string
    Description

    Field to sort by. Available values:

    • +created_at: Sort by creation time in ascending order.
    • -created_at: Sort by creation time in descending order.

Returns

Returns a paginated list of The Convert Task Objects.

Request

GET
/openapi/v1/convert
curl https://api.meshy.ai/openapi/v1/convert?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]
GET/openapi/v1/convert/:id/stream

Stream a Convert Task

This endpoint streams real-time updates for a convert task using Server-Sent Events (SSE).

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the convert task to stream.

Returns

Returns a stream of The Convert Task Objects as Server-Sent Events.

For PENDING or IN_PROGRESS tasks, the response stream will only include necessary progress and status fields.

Request

GET
/openapi/v1/convert/:id/stream
curl -N https://api.meshy.ai/openapi/v1/convert/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

The Convert Task Object

The Convert Task object represents a format conversion job.

Properties

  • id · string

Unique identifier for the task.

  • type · string

Type of the task. The value is convert.

  • model_urls · object

Downloadable URLs for the converted model files. Only the formats specified in target_formats will have URLs. Other format properties will be empty strings.

  • progress · integer

Progress of the task (0-100).

  • status · string

Status of the task. Possible values: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • preceding_tasks · integer

The count of preceding tasks. Meaningful only when status is PENDING.

  • created_at · timestamp

Timestamp of when the task was created, in milliseconds.

  • started_at · timestamp

Timestamp of when the task was started, in milliseconds. 0 if not started.

  • finished_at · timestamp

Timestamp of when the task was finished, in milliseconds. 0 if not finished.

  • task_error · object

Error object if the task failed. See Errors for more details.

  • consumed_credits · integer

The number of credits consumed by this task (1 credit per convert task). Returns 0 for FAILED tasks.