Convert API

Convert a 3D model to other file formats, from a Meshy task or from a model file.

POST/openapi/v1/convert

Create a Convert task

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

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

Parameters

Name
input_task_id
Type
string
Required
Description
Required unless you send model_url. The ID of a task that produced a 3D model, for example a Text to 3D, Image to 3D, Remesh, Resize, or Retexture task. The task must come from the API and have the status SUCCEEDED.

Name
model_url
Type
string
Required
Description
Required unless you send input_task_id. The model to convert, as a public URL or a data URI. If you send both, Meshy uses input_task_id.
The model must be a GLB, glTF, OBJ, FBX, or STL file of 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 file over 100 MB must also follow these rules:
- A GLB, glTF, FBX, or OBJ file can have at most 10,000,000 faces. Meshy counts faces as triangles, so a quad counts as 2, and a mesh drawn more than once counts once per copy.
- An FBX file must be binary FBX 7.1 or newer.
- A GLB or glTF file must not use Draco compression.

Name
target_formats
Type
string[]
Required
Description
The file formats to generate. List at least one. A missing or empty list returns 400.
Available values:
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf

Returns

The result field of the response holds the ID of the new Convert 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 model_url nor input_task_id was sent.
- Missing target_formats: target_formats is missing or lists no format.
- Invalid input task: input_task_id isn't a successful API task with a model file.
- 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.
- 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 Meshy can't read its header. For example, it's 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.
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. 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 convert. 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/convert/:id

Get a Convert task

Returns a Convert task by its ID.

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

Parameters

Name
id
Type
path
Description
The task ID from the create response.

Returns

The Convert task object.

DELETE/openapi/v1/convert/:id

Delete a Convert task

Permanently deletes a Convert task, including its models and data. You can't undo a delete.

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

Path parameters

Name
id
Type
path
Description
The ID of the task to delete.

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.

Returns

200 OK when the task is deleted, or 409 Conflict when the task is IN_PROGRESS.

GET/openapi/v1/convert

List Convert tasks

Returns a list of your Convert tasks.

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

Parameters

Name
page_num
Type
integer
default 1
Description
The page number to return, up to 255. A larger value returns 400.

Name
page_size
Type
integer
default 10
Description
The number of tasks per page, up to 100.

Name
sort_by
Type
string
Description
The sort order.
Available values:
- +created_at: oldest first
- -created_at: newest first

Returns

A paginated list of Convert task objects.

GET/openapi/v1/convert/:id/stream

Stream a Convert task

Streams a Convert task's updates as Server-Sent Events (SSE).

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
}

Parameters

Name
id
Type
path
Description
The task ID from the create response.

Returns

A stream of Convert task objects as Server-Sent Events.

Each event holds the full task object, in the same shape the Get endpoint returns. While the task is PENDING or IN_PROGRESS, its result fields don't have values yet.

The Convert task object

A Convert task object describes one format conversion of a 3D model. It holds the status, the progress, and the model files when the task succeeds.

Properties

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 convert.
Name
model_urls
Type
object
Description
Download URLs for the converted model, one per file format. Only the formats in target_formats have URLs. A format you didn't request has no key, rather than an empty string.
Name
progress
Type
integer
Description
How much of the task is done, as a percentage. It's 0 until the task starts and 100 when it succeeds.
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. The value is meaningful only 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 task's download URLs expire, in Unix milliseconds. It's 0 until the task finishes.
Name
texture_urls
Type
array
Description
Download URLs for the model's texture maps, when the task succeeds: an array of objects, one per texture set. Each object has a base_color URL, and can also have metallic, roughness, normal, emission, and metallic_roughness URLs. It's null until the task succeeds, and an empty array when the model has no texture maps.
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, which is 1 for a Convert task. It's 0 for a FAILED task.