lowpoly 将于 2026年10月30日 下线。 请在这些日期前切换模型，以免请求报错。 查看所有弃用信息

Convert API

将 3D 模型从 Meshy 任务或模型文件 Convert 为其他文件格式。

POST/openapi/v1/convert

创建 Convert 任务

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

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

参数

  • Name
    input_task_id
    Type
    string
    必选
    Description

    除非你发送 model_url，否则此项为必填。要转换其模型的 Meshy 任务的 ID。该任务的状态必须为 SUCCEEDED。

  • Name
    model_url
    Type
    string
    必选
    Description

    除非你发送 input_task_id，否则此项为必填。要转换的模型，以公开 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[]
    必选
    Description

    要生成的文件格式。至少列出一个。若列表缺失或为空，将返回 400。

    可用值：

    • glb
    • fbx
    • obj
    • usdz
    • blend
    • stl
    • 3mf

返回值

响应的 result 字段保存新 Convert 任务的 ID。

失败模式

  • Name
    400 - Bad Request
    Description

    请求无法运行。错误消息会说明发现的问题。例如：

    • 缺少参数：既没有发送 model_url，也没有发送 input_task_id。
    • 缺少 target_formats：target_formats 缺失或未列出任何格式。
    • 输入任务无效：input_task_id 不是一个成功的任务。
    • 模型格式无效：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、节点或记录过多，无法检查。请减少文件中的对象数量，然后重新发送。

    修复请求后重新发送。请参阅Errors。

  • Name
    401 - Unauthorized
    Description

    API key 缺失或无效。请检查 Authorization 请求头。

  • Name
    402 - Payment Required
    Description

    例如：

    • credits 不足：账户没有足够的 credits 来执行此任务，或账户已达到 credit 限额。请检查你的 credit balance，然后重试。
    • 免费计划：创建任务需要付费计划。请在你的subscription 设置中升级计划，然后重试。
  • Name
    403 - Forbidden
    Description

    input_task_id 是一个浮雕模型，此 endpoint 无法转换该类型。消息为 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/convert/:id

获取 Convert 任务

根据 ID 返回一个 Convert 任务。

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
}

参数

  • Name
    id
    Type
    path
    Description

    来自创建响应的任务 ID。

返回值

Convert 任务对象。

DELETE/openapi/v1/convert/:id

删除 Convert 任务

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

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

路径参数

  • Name
    id
    Type
    path
    Description

    要删除的任务的 ID。

任务状态

删除一个 PENDING 任务会退还你在创建该任务时所使用的 credits。

IN_PROGRESS 任务无法被删除。该请求会返回 409 Conflict， 并且任务会继续运行。Meshy 不会为已经开始的任务退款， 因此删除它既会损失 credits，也会损失结果。请等待它 变为 SUCCEEDED、FAILED 或 CANCELED 状态后再删除。

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

返回值

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

GET/openapi/v1/convert

获取 Convert 任务列表

返回你的 Convert 任务列表。

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

参数

  • 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：最新的排在前面

返回值

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

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

流式获取 Convert 任务

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

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
}

参数

  • Name
    id
    Type
    path
    Description

    来自创建响应的任务 ID。

返回值

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

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

Convert 任务对象

Convert 任务对象描述了一次 3D 模型的格式转换。它保存了任务的状态、进度，以及任务成功后的模型文件。

属性

  • Name
    id
    Type
    string
    Description

    任务 ID。请将其视为不透明字符串，不要依赖其格式。

  • Name
    type
    Type
    string
    Description

    任务类型，始终为 convert。

  • Name
    model_urls
    Type
    object
    Description

    转换后模型的下载链接，每种文件格式对应一个。只有 target_formats 中的格式才有链接。你未请求的格式不会有对应的键，而不是一个空字符串。

  • Name
    progress
    Type
    integer
    Description

    任务完成的百分比。任务开始前为 0，成功后为 100。

  • Name
    status
    Type
    string
    Description

    任务状态，为 PENDING、IN_PROGRESS、SUCCEEDED、FAILED 或 CANCELED 之一。

  • 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

    任务消耗的 credits 数量，Convert 任务为 1。FAILED 任务则为 0。