> **Reading as an AI agent?** This is the Markdown version of https://docs.meshy.ai/api/remesh.
>
> - Full docs index: https://docs.meshy.ai/llms.txt
> - Single-fetch full content: https://docs.meshy.ai/llms-full.txt
> - Tool-calling access via MCP server: https://docs.meshy.ai/api/ai

---
# 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.

The task runs in the background. For how long it usually takes, see [Processing Times](/api/task-lifecycle#processing-times).

> **Note:** For format conversion and resizing, use the dedicated [Convert API](/api/convert) and [Resize API](/api/resize). The deprecated parameters below will continue to work, but we recommend the new endpoints for new integrations.

### Parameters

> **Note:** Only one of `input_task_id` or `model_url` is **required**. If both are provided, `input_task_id` takes priority.

  - `input_task_id` · *string* · **required**

  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 have a status of `SUCCEEDED`.

  - `model_url` · *string* · **required**

  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`.

  - `target_formats` · *string[]* · default: `["glb"]`

  A list of target formats for the remeshed model. When omitted, only GLB is generated.

  Available values: `glb`, `fbx`, `obj`, `usdz`, `blend`, `stl`, `3mf`.

  - `topology` · *string* · default: `triangle`

  Specify the topology of the generated model.

  Available values:
  * `quad`: Generate a quad-dominant mesh.
  * `triangle`: Generate a decimated triangle mesh.

  - `target_polycount` · *integer* · default: `30,000`

  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)

  - `decimation_mode` · *integer*

  Enable adaptive decimation by setting a polycount level. When set, `target_polycount` is ignored.

  Available values:
  * `1`: Adaptive — ultra polycount.
  * `2`: Adaptive — high polycount.
  * `3`: Adaptive — medium polycount.
  * `4`: Adaptive — low polycount.

  - `resize_height` · *number* · default: `0` · **deprecated**

  Resize the model to a certain height measured in meters. We recommend using the dedicated [Resize API](/api/resize) instead.

  > **Note:** `auto_size`, `resize_height`, and `resize_longest_side` are mutually exclusive.

  - `resize_longest_side` · *number* · default: `0` · **deprecated**

  Resize the model so the longest bounding-box dimension equals the specified value in meters. We recommend using the dedicated [Resize API](/api/resize) instead.

  > **Note:** `auto_size`, `resize_height`, and `resize_longest_side` are mutually exclusive.

  - `auto_size` · *boolean* · default: `false` · **deprecated**

  When set to `true`, the service uses AI vision to automatically estimate the real-world height of the object and resize the model accordingly. We recommend using the dedicated [Resize API](/api/resize) instead.

  > **Note:** `auto_size`, `resize_height`, and `resize_longest_side` are mutually exclusive.

**Only when `auto_size` is set:**
  - `origin_at` · *string* · default: `bottom` · **deprecated**

  Position of the origin. We recommend using the dedicated [Resize API](/api/resize) instead.

  Available values: `bottom`, `center`.

  - `convert_format_only` · *boolean* · **deprecated**

  If `true`, the service will only change the format of the input model file, ignoring other inputs like `topology`, `resize_height`, and `target_polycount`. We recommend using the dedicated [Convert API](/api/convert) instead.

  > **Note:** `target_formats` must be provided if `convert_format_only` is set to `true`.

  - `alpha_thumbnail` · *boolean* · default: `false`

  When set to `true`, the task additionally renders a transparent-background (RGBA) version of the preview and returns it as `alpha_thumbnail_url` on the GET response. The existing `thumbnail_url` field is unchanged.

### Returns

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

### Failure Modes

  - `400 - Bad Request`

  The request was unacceptable. Common causes:
  * **Missing parameter**: Either `model_url` or `input_task_id` must be provided.
  * **Invalid input task**: The `input_task_id` must refer to a successful task from a supported model.
  * **Invalid model format**: The `model_url` points to a file with an unsupported extension.
  * **Unreachable URL**: The `model_url` could not be downloaded.
  * **Invalid topology**: The `topology` parameter is invalid.
  * **Mutually exclusive parameters**: `auto_size` and `resize_height` cannot both be set.

  - `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.

  **cURL**

  ```bash
  # Basic remesh with custom formats and resize
  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"
    }'

  # Quad remesh with auto-size
  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,
      "auto_size": true
    }'
  ```

  ```javascript
  import axios from 'axios'

  const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

  // Basic remesh with custom formats and resize
  const payload = {
      input_task_id: "018a210d-8ba4-705c-b111-1f1776f7f578",
      target_formats: ["glb", "fbx"],
      topology: "quad",
      target_polycount: 50000,
      resize_height: 1.0,
      origin_at: "bottom"
  };

  try {
      const response = await axios.post(
      'https://api.meshy.ai/openapi/v1/remesh',
      payload,
    { headers }
  );
      console.log(response.data);
  } catch (error) {
      console.error(error);
  }

  // Quad remesh with auto-size
  const autoSizePayload = {
      input_task_id: "018a210d-8ba4-705c-b111-1f1776f7f578",
      target_formats: ["glb", "fbx"],
      topology: "quad",
      target_polycount: 50000,
      auto_size: true
  };

  try {
      const response = await axios.post(
      'https://api.meshy.ai/openapi/v1/remesh',
      autoSizePayload,
    { headers }
  );
      console.log(response.data);
  } catch (error) {
      console.error(error);
  }
  ```

  ```python
  import requests

  headers = {
      "Authorization": f"Bearer {YOUR_API_KEY}"
  }

  # Basic remesh with custom formats and resize
  payload = {
      "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 = requests.post(
      "https://api.meshy.ai/openapi/v1/remesh",
      headers=headers,
      json=payload,
  )
  response.raise_for_status()
  print(response.json())

  # Quad remesh with auto-size
  auto_size_payload = {
      "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
      "target_formats": ["glb", "fbx"],
      "topology": "quad",
      "target_polycount": 50000,
      "auto_size": True
  }

  response = requests.post(
      "https://api.meshy.ai/openapi/v1/remesh",
      headers=headers,
      json=auto_size_payload,
  )
  response.raise_for_status()
  print(response.json())
  ```

**Response**

```json
{
  "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

  - `id` · *path*

  The ID of the remesh task to retrieve.

### Returns

The Remesh Task object.

  **cURL**

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

  ```javascript
  import axios from 'axios'

  const taskId = 'a43b5c6d-7e8f-901a-234b-567c890d1e2f';
  const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

  try {
      const response = await axios.get(
      `https://api.meshy.ai/openapi/v1/remesh/${taskId}`,
    { headers }
  );
      console.log(response.data);
  } catch (error) {
      console.error(error);
  }
  ```

  ```python
  import requests

  task_id = "a43b5c6d-7e8f-901a-234b-567c890d1e2f"
  headers = {
      "Authorization": f"Bearer {YOUR_API_KEY}"
  }

  response = requests.get(
      f"https://api.meshy.ai/openapi/v1/remesh/{task_id}",
      headers=headers,
  )
  response.raise_for_status()
  print(response.json())
  ```

**Response**

```json
{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "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=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?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

  - `id` · *path*

  The ID of the remesh 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`.

  **cURL**

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

  ```javascript
  import axios from 'axios'

  const taskId = 'a43b5c6d-7e8f-901a-234b-567c890d1e2f'
  const headers = { Authorization: `Bearer ${YOUR_API_KEY}` }

  try {
    await axios.delete(
      `https://api.meshy.ai/openapi/v1/remesh/${taskId}`,
      { headers }
    )
  } catch (error) {
    console.error(error)
  }
  ```

  ```python
  import requests

  task_id = "a43b5c6d-7e8f-901a-234b-567c890d1e2f"
  headers = {
      "Authorization": f"Bearer {YOUR_API_KEY}"
  }

  response = requests.delete(
      f"https://api.meshy.ai/openapi/v1/remesh/{task_id}",
      headers=headers,
  )
  response.raise_for_status()
  ```

**Response**

```json
// 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/remesh -- List Remesh Tasks

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

### Parameters

  - `page_num` · *integer* · default: `1`

  Page number for pagination.

  - `page_size` · *integer* · default: `10`

  Page size limit. Maximum allowed is `100` items.

  - `sort_by` · *string*

  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](#the-remesh-task-object).

  **cURL**

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

  ```javascript
  import axios from 'axios'

  const headers = { Authorization: `Bearer ${YOUR_API_KEY}` };

  try {
   const response = await axios.get(
     `https://api.meshy.ai/openapi/v1/remesh?page_size=10`,
     { headers }
   );
   console.log(response.data);
  } catch (error) {
   console.error(error);
  }
  ```

  ```python
  import requests

  headers = {
      "Authorization": f"Bearer {YOUR_API_KEY}"
  }

  response = requests.get(
      "https://api.meshy.ai/openapi/v1/remesh",
      headers=headers,
      params={"page_size": 10}
  )
  response.raise_for_status()
  print(response.json())
  ```

**Response**

```json
[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "remesh",
    "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=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?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

  - `id` · *path*

  Unique identifier for the Remesh task to stream.

### Returns
Returns a stream of [The Remesh Task Objects](#the-remesh-task-object) as Server-Sent Events.

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

  **cURL**

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

  ```javascript
  const response = await fetch(
    'https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream',
    {
      headers: { Authorization: `Bearer ${YOUR_API_KEY}` }
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop();

    for (const line of lines) {
      if (line.startsWith('data:')) {
        const data = JSON.parse(line.slice(5));
        console.log(data);

        if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(data.status)) {
          reader.cancel();
        }
      }
    }
  }
  ```

  ```python
  import requests
  import json

  headers = {
      "Authorization": f"Bearer {YOUR_API_KEY}",
      "Accept": "text/event-stream"
  }

  response = requests.get(
      'https://api.meshy.ai/openapi/v1/remesh/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream',
      headers=headers,
      stream=True
  )

  for line in response.iter_lines():
      if line:
          if line.startswith(b'data:'):
              data = json.loads(line.decode('utf-8')[5:])
              print(data)

              if data['status'] in ['SUCCEEDED', 'FAILED', 'CANCELED']:
                  break

  response.close()
  ```

**Response Stream**

```javascript
// 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",
  "type": "remesh",
  "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=***",
    "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?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

  - `id` · *string*

  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.

  - `type` · *string*

  Type of the Remesh task. The value is `remesh`.

  - `model_urls` · *object*

  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.

- `glb` · *string*

  Downloadable URL to the GLB file.

- `fbx` · *string*

  Downloadable URL to the FBX file.

- `obj` · *string*

  Downloadable URL to the OBJ file.

- `usdz` · *string*

  Downloadable URL to the USDZ file.

- `blend` · *string*

  Downloadable URL to the Blender file.

- `stl` · *string*

  Downloadable URL to the STL file.

- `3mf` · *string*

  Downloadable URL to the 3MF file. Only present when `3mf` was requested via `target_formats`.

  - `thumbnail_url` · *string*

  Downloadable URL to a preview image rendered from the remeshed model.

  - `alpha_thumbnail_url` · *string*

  Downloadable URL to a transparent-background (RGBA) version of `thumbnail_url`. Only present when the task was created with `alpha_thumbnail: true` and the transparent preview was successfully rendered; otherwise this field is omitted.

  - `progress` · *integer*

  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`.

  - `status` · *string*

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

  - `preceding_tasks` · *integer*

  The count of preceding tasks.

  > **Note:** The value of this field is meaningful only if the task 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. If the task is not started yet, this property will be `0`.

  - `finished_at` · *timestamp*

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

  - `task_error` · *object*

  Error details for failed tasks. See [Errors](/api/errors#task-errors) for the full `task_error` object reference.

  - `consumed_credits` · *integer*

  The number of credits consumed by this task. Present when the task status is `PENDING`, `IN_PROGRESS`, or `SUCCEEDED`. Returns `0` for `FAILED` tasks (credits are refunded on failure).

<span id="example-remesh-task-object" />

**Example Remesh Task Object**

```json
{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "remesh",
  "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=***",
      "blend": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.blend?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 5
}
```