尺寸调整 API

尺寸调整 API 允许您将现有的 3D 模型调整为真实世界的尺寸。您可以指定一个精确的高度、一个最长边约束，或者让 AI 自动估算合适的尺寸。

POST/openapi/v1/resize

创建尺寸调整任务

此 endpoint 用于创建一个新的尺寸调整任务。

该任务在后台运行。关于通常所需的时间，请参阅处理时间。

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

参数

input_task_id 和 model_url 中只有一个是必需的。如果两者都提供了，则 input_task_id 具有更高的优先顺序。

Name
input_task_id
Type
string
必选
Description
您希望调整尺寸的、已完成的 Meshy 任务的 ID。该任务的状态必须为 SUCCEEDED。输出格式将为 GLB。

Name
model_url
Type
string
必选
Description
指向 3D 模型文件的公开可访问 URL 或 data URI。支持的格式：.glb、.gltf、.obj、.fbx、.stl。对于 Data URI，请使用 MIME type：application/octet-stream。 .glb、.obj、.fbx 或 .stl URL 在输出中会保留其原格式；.gltf URL 或 data URI 将生成 GLB。
最大文件大小：http 或 https URL 为 400 MB，data: URI 为 100 MB。
超过 100 MB 的 GLB、glTF、FBX 或 OBJ 文件最多可包含 10,000,000 个面。面以三角形计数：一个四边形计为 2 个，被多次绘制的 mesh 每份副本计为一次。超过 100 MB 时，FBX 文件必须是 7.1 或更新版本的二进制 FBX，且 GLB 或 glTF 文件不得使用 Draco 压缩。

必须且只能指定以下一种尺寸调整 mode：resize_height、resize_longest_side 或 auto_size。这三个参数互斥。

Name
resize_height
Type
number
Description
将模型调整为以米为单位的特定高度。

Name
resize_longest_side
Type
number
Description
调整模型尺寸，使其最长边匹配此值（以米为单位）。长宽比将保持不变。

Name
auto_size
Type
boolean
Description
设置为 true 时，服务将使用 AI 视觉自动估算该物体的真实世界高度，并据此调整模型尺寸。除非显式设置了 origin_at，否则 origin 默认设为 bottom。

Name
origin_at
Type
string
默认值 bottom
Description
调整尺寸后 origin 的位置。
可用值：bottom、center。

响应的 result 属性包含新创建的尺寸调整任务的 id。

失败模式

400 - Bad Request

请求不可接受。常见原因：

缺少参数：必须提供 model_url 或 input_task_id 其中之一。
缺少尺寸调整 mode：必须指定 resize_height、resize_longest_side 或 auto_size 中的至少一个。
互斥参数：resize_height、resize_longest_side 和 auto_size 不能同时组合使用。
无效的输入任务：input_task_id 必须指向一个成功的任务。
无效的模型格式：model_url 指向的文件扩展名不受支持。
URL 无法访问：无法下载 model_url 指定的内容。
模型文件过大：model_url 文件超过了 400 MB（http 或 https URL）或 100 MB（data: URI）的限制。
面数过多：model_url 文件超过 100 MB，且面数超过 10,000,000。请减少面数后重新发送文件。
ASCII FBX 超过 100 MB：model_url 文件是超过 100 MB 的 ASCII FBX。请以二进制 FBX 或 GLB 格式发送。
模型文件无法读取：model_url 文件超过 100 MB，且其文件头无法读取，例如经 Draco 压缩的 GLB 或 glTF，或早于 7.1 版本的二进制 FBX。
模型文件头过于复杂：model_url 文件超过 100 MB，且其文件头中包含过多需要检查的 mesh、节点或记录。请减少文件中的对象数量后重新发送。

401 - Unauthorized

Authentication 失败。请检查您的 API key。

402 - Payment Required

credits 不足，无法执行此任务。

429 - Too Many Requests

您已超出速率限制。

GET/openapi/v1/resize/:id

获取尺寸调整任务

此 endpoint 通过 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

删除一个尺寸调整任务

此 endpoint 将永久删除一个尺寸调整任务，包括所有相关的模型和数据。此操作不可逆。

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

路径参数

Name
id
Type
path
Description
要删除的尺寸调整任务的 ID。

任务状态

仍处于 PENDING 状态的任务会被删除，且创建时消耗的 credits 会被退还。

已处于 IN_PROGRESS 状态的任务无法删除：该请求会被拒绝并返回 409 Conflict，任务会继续运行。对于 worker 已经开始处理的任务，其 credits 不可退还，因此在运行过程中删除它会使你同时损失 credits 和结果。请等待任务到达 SUCCEEDED、FAILED 或 CANCELED 状态后再删除。

处于终止状态（SUCCEEDED、FAILED 或 CANCELED）的任务会被删除，且不予退款。

返回值

成功时返回 200 OK；当任务处于 IN_PROGRESS 状态时返回 409 Conflict。

GET/openapi/v1/resize

获取尺寸调整任务列表

此 endpoint 允许您获取尺寸调整任务列表。

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
用于分页的页码。

Name
page_size
Type
integer
默认值 10
Description
每页数量限制。最大允许 100 项。

Name
sort_by
Type
string
Description
用于排序的字段。可用值：
- +created_at：按创建时间升序排序。
- -created_at：按创建时间降序排序。

返回值

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

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

流式获取尺寸调整任务

此 endpoint 使用 Server-Sent Events (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
要进行流式传输的尺寸调整任务的唯一标识符。

返回值

以 Server-Sent Events 的形式返回尺寸调整任务对象流。

对于 PENDING 或 IN_PROGRESS 状态的任务，响应流中仅会包含必要的 progress 和 status 字段。

尺寸调整任务对象

尺寸调整任务对象表示一个尺寸调整作业。

属性

id · string

任务的唯一标识符。

type · string

任务的类型。此值为 resize。

model_urls · object

调整尺寸后的模型文件的可下载 URL。使用 input_task_id 时，输出始终为 GLB。使用 model_url 时，.glb、.obj、.fbx 或 .stl 格式的输入将保持其原格式，而 .gltf 格式的输入或 Data URI 将生成 GLB。

progress · integer

任务的进度（0-100）。

status · string

任务的状态。可能的值：PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED。

preceding_tasks · integer

排在前面的任务数量。仅当状态为 PENDING 时才有意义。

created_at · timestamp

任务创建时的时间戳，单位为毫秒。

started_at · timestamp

任务开始时的时间戳，单位为毫秒。如果尚未开始，则为 0。

finished_at · timestamp

任务完成时的时间戳，单位为毫秒。如果尚未完成，则为 0。

task_error · object

任务失败时的错误对象。更多详情请参见 Errors。

consumed_credits · integer

此任务消耗的 credits 数量（每个尺寸调整任务消耗 1 个 credit）。对于 FAILED 的任务，返回 0。