Remesh API

使用新的 topology 和面数重建 3D 模型的 mesh，并将其导出为你所选择的格式。模型可以来自另一个 Meshy 任务（例如 Image to 3D 或 Text to 3D），也可以来自模型文件。

POST/openapi/v1/remesh

创建 Remesh 任务

创建一个 Remesh 任务。该任务在后台运行。关于任务通常需要多长时间，请参阅处理时间。

如需转换模型格式或调整其尺寸，请使用 Convert API 或 Resize API。本页中已 deprecated 的参数仍可使用，但新的集成应使用这些 endpoint。

Request

POST

/openapi/v1/remesh

# 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
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

参数

Name
input_task_id
Type
string
必选
Description
除非你发送 model_url，否则为必填项。要进行 remesh 的模型所属任务的 ID，例如 Text to 3D、Image to 3D、Retexture 或 Remesh 任务。该任务必须是你通过 API 创建的，且状态为 SUCCEEDED。

Name
model_url
Type
string
必选
Description
除非你发送 input_task_id，否则为必填项。要进行 remesh 的模型，可以是公开 URL 或 data URI。如果两者都发送，Meshy 会使用 input_task_id。
模型文件必须是 GLB、glTF、OBJ、FBX 或 STL 格式，通过 http 或 https URL 提供时最大为 400 MB，作为 data URI 提供时最大为 100 MB。对于 data URI，请使用 MIME type application/octet-stream。
超过 100 MB 的文件还必须遵循以下规则：
- GLB、glTF、FBX 或 OBJ 文件最多可包含 10,000,000 个面。Meshy 以三角形计数面数，因此一个四边形计为 2，而被绘制多次的 mesh 每份副本计一次。
- FBX 文件必须是 7.1 或更高版本的二进制 FBX。
- GLB 或 glTF 文件不得使用 Draco 压缩。

Name
target_formats
Type
string[]
默认值 ["glb"]
Description
要生成的文件格式。
可用值：
- glb
- fbx
- obj
- usdz
- blend
- stl
- 3mf
Name
topology
Type
string
默认值 triangle
Description
重新生成后的模型的面类型。
可用值：
- quad：以四边形为主的 mesh
- triangle：经过精简的三角形 mesh
Name
target_polycount
Type
integer
默认值 30000
Description
目标面数，范围从 100 到 300000。根据模型的 geometry 不同，实际结果可能与目标值有所差异。超出该范围的值会返回 400。
Name
decimation_mode
Type
integer
Description
按级别设置的自适应面数。设置该参数后，Meshy 会忽略 target_polycount。
可用值：
- 1：超高
- 2：高
- 3：中
- 4：低
Name
resize_height
Type
number
⚠ 已弃用
默认值 0
Description
请改用 Resize API。将模型调整到的高度，单位为米。resize_height、resize_longest_side 和 auto_size 最多只能发送其中一个。
Name
resize_longest_side
Type
number
⚠ 已弃用
默认值 0
Description
请改用 Resize API。将模型包围盒最长边调整到的长度，单位为米。resize_height、resize_longest_side 和 auto_size 最多只能发送其中一个。
Name
auto_size
Type
boolean
⚠ 已弃用
默认值 false
Description
请改用 Resize API。是否使用 AI 视觉估算物体的真实世界高度，并将模型调整到该高度。resize_height、resize_longest_side 和 auto_size 最多只能发送其中一个。
Name
origin_at
Type
string
⚠ 已弃用
默认值 bottom
Description
请改用 Resize API。模型 origin 的放置位置，bottom 或 center。当你发送 resize_height、resize_longest_side 或 auto_size 时，适用默认值。如果未发送其中任何一个，Meshy 只有在你发送了 origin_at 时才会移动 origin。

Name
convert_format_only
Type
boolean
⚠ 已弃用
Description
请改用 Convert API。是否仅将模型转换为 target_formats。为 true 时，Meshy 会忽略 topology、target_polycount、decimation_mode、resize_height、resize_longest_side 和 auto_size，但仍会校验这些值，因此无效的值会返回 400。当 convert_format_only: true 时，如果 target_formats 为空或 null，会返回 400。

Name
alpha_thumbnail
Type
boolean
默认值 false
Description
是否同时渲染一个带透明背景（RGBA）的预览图，在获取任务时通过 alpha_thumbnail_url 返回。thumbnail_url 不会改变。

返回值

响应中的 result 字段保存了新 Remesh 任务的 ID。

失败模式

Name
400 - Bad Request
Description
请求无法运行。错误消息会说明发现了什么问题。例如：
- 缺少参数：既没有发送 model_url，也没有发送 input_task_id。
- 输入任务无效：input_task_id 不是一个成功的 API 任务，或者其 AI 模型不支持 remesh。
- 模型格式无效：model_url 文件的扩展名不受支持。
- URL 无法访问：Meshy 无法下载 model_url 文件。
- 模型文件过大：model_url 文件通过 http 或 https URL 提供时超过 400 MB，或作为 data URI 提供时超过 100 MB。
- 面数过多：model_url 文件超过 100 MB，且面数超过 10,000,000。请减少面数后重新发送文件。
- ASCII FBX 超过 100 MB：model_url 文件是超过 100 MB 的 ASCII FBX。请将其以二进制 FBX 或 GLB 格式发送。
- 模型文件无法读取：model_url 文件超过 100 MB，且 Meshy 无法读取其文件头。例如，它是经过 Draco 压缩的 GLB 或 glTF 文件，或是早于 7.1 版本的二进制 FBX 文件。
- 模型文件头过于复杂：model_url 文件超过 100 MB，其文件头中包含的 mesh、节点或记录数量过多，无法完成检查。请减少文件中的对象数量后重新发送。
- topology 无效：topology 既不是 quad 也不是 triangle。
- 参数互斥：请求中同时包含了 auto_size、resize_height 和 resize_longest_side 中的多个。请仅发送其中一个。
请修正请求后重新发送。参见错误。
Name
401 - Unauthorized
Description
API key 缺失或无效。请检查 Authorization 请求头。
Name
402 - Payment Required
Description
例如：
- 积分不足：账户没有足够的积分来执行此任务，或账户已达到积分限额。请检查你的积分余额，然后重试。
- 免费计划：创建任务需要付费计划。请在订阅设置中升级你的计划，然后重试。
Name
403 - Forbidden
Description
input_task_id 是一个浮雕模型，此 endpoint 无法对其进行 remesh。错误消息为 This model type does not support this operation。请发送其他模型。
Name
404 - Not Found
Description
input_task_id 与你的任何任务都不匹配。请检查任务 ID 后重新发送请求。
Name
429 - Too Many Requests
Description
你已超出速率限制。请稍候后重试。参见速率限制。

GET/openapi/v1/remesh/:id

获取一个 Remesh 任务

通过 ID 返回一个 Remesh 任务。

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

参数

Name
id
Type
path
Description
创建响应中的任务 ID。

返回值

Remesh 任务对象。

DELETE/openapi/v1/remesh/:id

删除一个 Remesh 任务

永久删除一个 Remesh 任务，包括它的模型和数据。删除操作无法撤销。

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

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

路径参数

Name
id
Type
path
Description
要删除的任务的 ID。

任务状态

删除一个 PENDING 任务会退还你创建它时所使用的积分。

IN_PROGRESS 的任务无法被删除。该请求会返回 409 Conflict，任务会继续运行。Meshy 不会为已经开始的任务退款，因此删除它会让你同时损失积分和结果。请等待任务进入 SUCCEEDED、FAILED 或 CANCELED 状态后再删除。

删除处于最终状态（SUCCEEDED、FAILED 或 CANCELED）的任务不会退还其积分。

返回值

任务被删除时返回 200 OK，当任务处于 IN_PROGRESS 时返回 409 Conflict。

GET/openapi/v1/remesh

获取 Remesh 任务列表

返回您的 Remesh 任务列表。

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

参数

Name
page_num
Type
integer
默认值 1
Description
要返回的页码。
Name
page_size
Type
integer
默认值 10
Description
每页的任务数量，最多为 100。
Name
sort_by
Type
string
Description
排序方式。
可用值：
- +created_at：从最早到最新
- -created_at：从最新到最早

一个分页的 Remesh 任务对象列表。

GET/openapi/v1/remesh/:id/stream

流式获取 Remesh 任务

以服务器发送事件（SSE）的形式，流式获取 Remesh 任务的更新。

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.
// These examples are shortened. Each event holds the full task object.
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,
}

参数

Name
id
Type
path
Description
创建响应中返回的任务 ID。

返回值

以服务器发送事件形式返回的 Remesh 任务对象流。

每个事件都包含完整的任务对象，其结构与 Get endpoint 返回的结构相同。当任务处于 PENDING 或 IN_PROGRESS 状态时，其结果字段还没有值。

重拓扑任务对象

一个重拓扑任务对象描述了对某个 3D 模型的一次重拓扑操作。它保存着任务状态、进度，以及任务成功时的模型文件。

属性

Example Remesh Task Object

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

Name
id
Type
string
Description
任务 ID。请将其视为一个不透明的字符串，不要依赖其格式。
Name
type
Type
string
Description
任务类型，始终为 remesh。
Name
model_urls
Type
object
Description
重拓扑后模型的下载 URL，每种文件格式对应一个。任务未生成的格式不会有对应的键，而不是空字符串。
- Name
  glb
  Type
  string
  Description
  GLB 文件。
- Name
  fbx
  Type
  string
  Description
  FBX 文件。
- Name
  obj
  Type
  string
  Description
  OBJ 文件。
- Name
  usdz
  Type
  string
  Description
  USDZ 文件。
- Name
  blend
  Type
  string
  Description
  Blender 文件。
- Name
  stl
  Type
  string
  Description
  STL 文件。
- Name
  3mf
  Type
  string
  Description
  3MF 文件。仅当 target_formats 包含 3mf 时才会出现。
Name
thumbnail_url
Type
string
Description
重拓扑后模型预览图的下载 URL。
Name
alpha_thumbnail_url
Type
string
Description
thumbnail_url 的透明背景版本（RGBA）的下载 URL。仅当你在创建任务时设置了 alpha_thumbnail: true，且 Meshy 渲染了透明预览图时才会出现。
Name
progress
Type
integer
Description
任务完成的百分比。任务开始前为 0，成功后为 100。
Name
status
Type
string
Description
任务状态，取值为 PENDING、IN_PROGRESS、SUCCEEDED 或 FAILED 之一。
Name
preceding_tasks
Type
integer
Description
排在此任务之前的任务数量。该值仅在任务处于 PENDING 状态时才有意义。
Name
created_at
Type
timestamp
Description
任务创建时间，单位为 Unix 毫秒。
Name
started_at
Type
timestamp
Description
任务开始时间，单位为 Unix 毫秒。任务开始前为 0。
Name
finished_at
Type
timestamp
Description
任务完成时间，单位为 Unix 毫秒。任务完成前为 0。
Name
task_error
Type
object
Description
任务失败时的错误详情。参见 Errors。
Name
consumed_credits
Type
integer
Description
任务消耗的积分数量。当状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时会出现该字段。对于 FAILED 任务，其值为 0，因为 Meshy 会在任务失败时退还积分。