尺寸调整 API
将 3D 模型调整为以米为单位的真实世界尺寸。设置其高度或最长边的长度,或让 Meshy 估算该物体的真实世界高度。
创建 Resize 任务
创建一个 Resize 任务。该任务将在后台运行。有关任务通常耗时多久,请参阅处理时间。
Request
# 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或httpsURL 提供,大小最多为 400 MB,若以 data URI 提供,则最多为 100 MB。对于 data URI,请使用 MIME typeapplication/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或httpsURL 提供的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
你已超出速率限制。请稍候后重试。参见速率限制。
获取尺寸调整任务
根据 ID 返回一个尺寸调整任务。
Request
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
}
删除一个尺寸调整任务
永久删除一个尺寸调整任务,包括其模型和数据。删除操作无法撤销。
Request
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。
获取 尺寸调整 任务列表
返回你的 尺寸调整 任务列表。
Request
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:最新优先
返回值
一个分页的尺寸调整任务对象列表。
流式获取尺寸调整任务
以服务器发送事件(SSE)的形式流式传输尺寸调整任务的更新。
Request
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_colorURL,还可以包含metallic、roughness、normal、emission和metallic_roughness的 URL。任务成功前该值为null,若模型没有纹理贴图,则为空数组。
- Name
- task_error
- Type
- object
- Description
任务失败时的错误详情。参见 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
任务消耗的积分数量,调整尺寸任务为
1。对于FAILED任务,该值为0。