Remesh API

The Remesh API allows you to remesh and export existing 3D models generated by other Meshy APIs (like Image to 3D or Text to 3D) into various formats. This section provides details on how to use the Remesh API.

POST/openapi/v1/remesh

Create a Remesh Task

This endpoint creates a new remesh task.

Parameters

Required attributes

  • Name
    input_task_id
    Type
    string
    Description

    The ID of the completed Image to 3D or Text to 3D task you wish to remesh. This task must be one of the following tasks: Text to 3D Preview, Text to 3D Refine, Image to 3D or Retexture. In addition, it must be run using the meshy-4 or meshy-5 AI model and have a status of SUCCEEDED.

    Required if model_url is not provided.

  • Name
    model_url
    Type
    string
    Description

    Please provide a 3D model for Meshy to remesh via a publicly accessible URL or data URI. Supported formats: .glb, .gltf, .obj, .fbx, .stl.

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

    Required if input_task_id is not provided.

Only one of input_task_id or model_url may be used as input for remeshing. If both are supplied, then the input_task_id will be used by default.

Optional attributes

  • Name
    target_formats
    Type
    array of strings
    Description

    A list of target formats for the remeshed model.

    Available values: glb, fbx, obj, usdz, blend, stl.

    Defaults to ["glb"] if not specified.

  • Name
    topology
    Type
    string
    Description

    Specify the topology of the generated model.

    Available values:

    • quad: Generate a quad-dominant mesh.
    • triangle: Generate a decimated triangle mesh.

    Default to triangle if not specified.

  • Name
    target_polycount
    Type
    integer
    Description

    Specify the target number of polygons in the generated model. The actual number of polygons may deviate from the target depending on the complexity of the geometry.

    The valid value range varies depending on the user tier:

    • 100 to 300,000 (inclusive)

    Default to 30,000 if not specified.

  • Name
    resize_height
    Type
    number
    Description

    Resize the model to a certain height measured in meters.

    Default to 0 (no resizing) if not specified.

  • Name
    origin_at
    Type
    string
    Description

    Position of the origin.

    Available values: bottom, center.

    Default to an empty string (with no effect) if not specified.

  • Name
    convert_format_only
    Type
    boolean
    Description

    If true, the service will only change the format of the input model file, ignoring other inputs like topology, resize_height, and target_polycount.

    target_formats must be provided if convert_format_only is set to true.

Returns

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

Request

POST
/openapi/v1/remesh
curl https://api.meshy.ai/openapi/v1/remesh \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["glb", "fbx"],
    "topology": "quad",
    "target_polycount": 50000,
    "resize_height": 1.0,
    "origin_at": "bottom"
  }'

Response

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

Retrieve a Remesh Task

This endpoint retrieves a remesh task by its ID.

Parameters

  • Name
    id
    Type
    path
    Description

    The ID of the remesh task to retrieve.

Returns

The Remesh Task object.

Request

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

Response

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

Delete a Remesh Task

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

Path Parameters

  • Name
    id
    Type
    path
    Description

    The ID of the remesh task to delete.

Returns

Returns 200 OK on success.

Request

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

Response

// Returns 200 Ok on success.
GET/v1/remesh

List Remesh Tasks

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

Parameters

Optional attributes

  • Name
    page_num
    Type
    integer
    Description

    Page number for pagination. Starts and defaults to 1.

  • Name
    page_size
    Type
    integer
    Description

    Page size limit. Defaults to 10 items. Maximum allowed is 50 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 Remesh Task Objects.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null
  }
]
GET/openapi/v1/remesh/:id/stream

Stream a Remesh Task

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

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the Remesh task to stream.

Returns

Returns a stream of The Remesh 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/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
}

The Remesh Task Object

The Remesh Task object represents a work unit that Meshy uses to remesh and export an existing 3D model into various formats. The object has the following properties:

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the task. While we use a k-sortable UUID for task ids as the implementation detail, you should not make any assumptions about the format of the id.

  • Name
    model_urls
    Type
    object
    Description

    Downloadable URL to the textured 3D model file generated by Meshy. The property for a format will be omitted if the format is not generated instead of returning an empty string.

    • Name
      glb
      Type
      string
      Description

      Downloadable URL to the GLB file.

    • Name
      fbx
      Type
      string
      Description

      Downloadable URL to the FBX file.

    • Name
      obj
      Type
      string
      Description

      Downloadable URL to the OBJ file.

    • Name
      usdz
      Type
      string
      Description

      Downloadable URL to the USDZ file.

    • Name
      blend
      Type
      string
      Description

      Downloadable URL to the Blender file.

    • Name
      stl
      Type
      string
      Description

      Downloadable URL to the STL file.

  • Name
    progress
    Type
    integer
    Description

    Progress of the task. If the task is not started yet, this property will be 0. Once the task has succeeded, this will become 100.

  • Name
    status
    Type
    string
    Description

    Status of the task. Possible values are one of PENDING, PROCESSING, SUCCEEDED, FAILED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    The count of preceding tasks.

    The value of this field is meaningful only if the task status is PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the task was created, in milliseconds.

  • Name
    started_at
    Type
    timestamp
    Description

    Timestamp of when the task was started, in milliseconds. If the task is not started yet, this property will be 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp of when the task was finished, in milliseconds. If the task is not finished yet, this property will be 0.

  • Name
    task_error
    Type
    object
    Description

    Error object that contains the error message if the task failed. The message property should be empty if the task succeeded.

    • Name
      message
      Type
      string
      Description

      Detailed error message.

Example Remesh Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.fbx?Expires=***",
      "obj": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.obj?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.usdz?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {
      "message": ""
  }
}