lowpoly 将于 2026年10月30日 下线。 meshy-7 作为 3D 生成模型将于 2026年12月31日 下线;作为贴图模型仍可使用。 请在这些日期前切换模型,以免请求报错。 查看所有弃用信息

尺寸调整 API

将 3D 模型调整为以米为单位的真实世界尺寸。设置其高度或最长边的长度,或让 Meshy 估算该物体的真实世界高度。


POST/openapi/v1/resize

创建 Resize 任务

创建一个 Resize 任务。该任务将在后台运行。有关任务通常耗时多久,请参阅处理时间。

Request

POST
/openapi/v1/resize
# Simple: resize to a specific height
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "resize_height": 1.8
  }'

# Advanced: resize longest side with custom origin
curl https://api.meshy.ai/openapi/v1/resize \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.glb",
    "resize_longest_side": 2.0,
    "origin_at": "center"
  }'

Response

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

参数

  • Name
    input_task_id
    Type
    string
    必选
    Description

    除非发送 model_url,否则此参数为必填项。生成 3D 模型的任务的 ID,例如 Text to 3D、Image to 3D、Remesh 或 Retexture 任务。该任务必须来自 API,且状态为 SUCCEEDED。Meshy 会以 GLB 文件形式返回调整尺寸后的模型。

  • 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 压缩。

    GLB、OBJ、FBX 或 STL 文件在结果中会保留其原始格式。.gltf 文件或 data URI 返回时将转换为 GLB。

请在 resize_height、resize_longest_side 或 auto_size 中恰好发送一个。一个都不发送,或发送多个,都会返回 400。

  • Name
    resize_height
    Type
    number
    Description

    模型的新高度,以米为单位,必须大于 0。负值会返回 400。

  • Name
    resize_longest_side
    Type
    number
    Description

    模型最长边的新长度,以米为单位,必须大于 0。负值会返回 400。Meshy 会保持模型的宽高比。

  • Name
    auto_size
    Type
    boolean
    Description

    是否使用 AI 视觉估算物体的真实世界高度,并据此调整模型尺寸。除非设置了 origin_at,否则 Meshy 会将原点放在底部。

  • Name
    origin_at
    Type
    string
    默认值 bottom
    Description

    调整尺寸后模型原点的位置,bottom 或 center。

返回值

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

失败模式

  • Name
    400 - Bad Request
    Description

    请求无法执行。错误消息会说明发现了哪种问题。例如:

    • 缺少参数:既未发送 model_url,也未发送 input_task_id。
    • 缺少 Resize mode:未发送 resize_height、resize_longest_side 和 auto_size 中的任何一个。
    • 参数互斥:请求中包含了 resize_height、resize_longest_side 和 auto_size 中的多个。请只发送一个。
    • 尺寸为负数:resize_height 或 resize_longest_side 为负数。
    • 输入任务无效:input_task_id 不是带有模型文件的成功 API 任务。
    • 模型格式无效:model_url 文件的扩展名不受支持。
    • URL 无法访问:Meshy 无法下载 model_url 文件。
    • 模型文件过大:通过 http 或 https URL 提供的 model_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、节点或记录。请减少文件中的对象数量后重新发送。

    请修正请求后重新发送。参见错误。

  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    例如:

    • 积分不足:账户没有足够的积分来执行此任务,或账户已达到积分限额。请检查你的积分余额,然后重试。
    • 免费计划:创建任务需要付费计划。请在订阅设置中升级你的计划,然后重试。
  • 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/resize/:id

获取尺寸调整任务

根据 ID 返回一个尺寸调整任务。

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "resize",
  "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?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。

返回值

尺寸调整任务对象。


DELETE/openapi/v1/resize/:id

删除一个尺寸调整任务

永久删除一个尺寸调整任务,包括其模型和数据。删除操作无法撤销。

Request

DELETE
/openapi/v1/resize/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/resize/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/resize

获取 尺寸调整 任务列表

返回你的 尺寸调整 任务列表。

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "resize",
    "model_urls": {
      "glb": "https://assets.meshy.ai/.../model.glb?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

    要返回的页码,最大为 255。更大的值将返回 400。

  • Name
    page_size
    Type
    integer
    默认值 10
    Description

    每页的任务数量,最大为 100。

  • Name
    sort_by
    Type
    string
    Description

    排序方式。

    可用值:

    • +created_at:最早优先
    • -created_at:最新优先

返回值

一个分页的尺寸调整任务对象列表。


GET/openapi/v1/resize/:id/stream

流式获取尺寸调整任务

以服务器发送事件(SSE)的形式流式传输尺寸调整任务的更新。

Request

GET
/openapi/v1/resize/:id/stream
curl -N https://api.meshy.ai/openapi/v1/resize/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": "resize",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb?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。

返回

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

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


调整尺寸任务对象

一个调整尺寸任务对象描述了一次 3D 模型的尺寸调整。它保存着任务的状态、progress,以及任务成功后的模型文件。

属性

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    任务类型,始终为 resize。

  • Name
    model_urls
    Type
    object
    Description

    调整尺寸后的模型文件的下载 URL。对于 input_task_id,该文件始终为 GLB。对于 model_url,GLB、OBJ、FBX 或 STL 文件会保留其原有格式,而 .gltf 文件或 Data URI 会以 GLB 格式返回。

  • 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
    expires_at
    Type
    timestamp
    Description

    任务下载 URL 过期的时间,以 Unix 毫秒数表示。任务完成前为 0。

  • Name
    texture_urls
    Type
    array
    Description

    任务成功后模型纹理贴图的下载 URL:一个对象数组,每个 texture 集合对应一个对象。每个对象都有一个 base_color URL,还可以包含 metallic、roughness、normal、emission 和 metallic_roughness 的 URL。任务成功前该值为 null,若模型没有纹理贴图,则为空数组。

  • Name
    task_error
    Type
    object
    Description

    任务失败时的错误详情。参见 Errors。

  • Name
    consumed_credits
    Type
    integer
    Description

    任务消耗的积分数量,调整尺寸任务为 1。对于 FAILED 任务,该值为 0。