调整尺寸 API

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

POST/openapi/v1/resize

创建调整尺寸任务

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

参数

只需提供 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
可公开访问的 URL 或数据 URI，指向一个3D模型文件。支持的格式：.glb、.gltf、.obj、.fbx、.stl。对于 Data URI，请使用 MIME 类型：application/octet-stream。输出格式将保持与输入模型一致。

必须且只能指定一种缩放模式（必选）：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，否则原点将默认为 bottom。

Name
origin_at
Type
string
默认值 bottom
Description
缩放后的原点位置。
可选值：bottom、center。

返回值

响应的 result 字段包含新建调整尺寸任务的 id。

失败模式

400 - Bad Request

请求不合法。常见原因：

缺少参数：必须提供 model_url 或 input_task_id 其中之一。
缺少缩放模式：必须指定 resize_height、resize_longest_side 或 auto_size 其中之一。
互斥参数冲突：resize_height、resize_longest_side 和 auto_size 不能同时使用。
输入任务无效：input_task_id 必须引用一个成功的任务。
模型格式无效：model_url 指向的文件扩展名不受支持。
URL 不可访问：model_url 无法下载。

401 - Unauthorized

认证失败。请检查您的 API 密钥。

402 - Payment Required

积分不足，无法执行此任务。

429 - Too Many Requests

您已超出请求频率限制。

请求

POST

/openapi/v1/resize

# 简单示例：指定高度
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
  }'

# 进阶示例：指定最长边并设置原点
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"
  }'

响应

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

GET/openapi/v1/resize/:id

获取调整尺寸任务

此端点用于通过 ID 获取调整尺寸任务。

参数

Name
id
Type
path
Description
要获取的调整尺寸任务 ID。

返回值

返回调整尺寸任务对象。

请求

GET

/openapi/v1/resize/:id

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

响应

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

DELETE/openapi/v1/resize/:id

删除调整尺寸任务

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

路径参数

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

返回值

成功则返回 200 OK。

请求

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

响应

// 成功则返回 200 Ok。

GET/openapi/v1/resize

列出调整尺寸任务

此端点允许您获取调整尺寸任务的列表。

参数

Name
page_num
Type
integer
默认值 1
Description
分页的页码。

Name
page_size
Type
integer
默认值 10
Description
每页返回的任务数量。最大允许为 50。

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

返回值

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

请求

GET

/openapi/v1/resize

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

响应

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

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

流式调整尺寸任务

此端点通过 Server-Sent Events (SSE) 流式返回调整尺寸任务的实时进度更新。

参数

Name
id
Type
path
Description
要流式获取的调整尺寸任务 ID。

返回值

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

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

请求

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

响应流

// 消息事件示例展示任务进度。
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
}

调整尺寸任务对象

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

属性

id · string

任务的唯一标识符。

type · string

任务类型。值为 resize。

model_urls · object

调整尺寸后的模型文件的可下载 URL。使用 input_task_id 时输出为 GLB 格式，使用 model_url 时保持原始格式。

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

此任务消耗的积分数（每个调整尺寸任务消耗1个积分）。FAILED 任务返回 0。