Convert API
将 3D 模型从 Meshy 任务或模型文件 Convert 为其他文件格式。
创建 Convert 任务
创建一个 Convert 任务。该任务在后台运行。关于任务通常需要多长时间,请参阅处理时间。
Request
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,否则此项为必填。该参数是生成了 3D 模型的任务的 ID,例如 Text to 3D、Image to 3D、Remesh、尺寸调整或 Retexture 任务。该任务必须来自 API,且状态为SUCCEEDED。
- 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 压缩。
- Name
- target_formats
- Type
- string[]
- 必选
- Description
要生成的文件格式。至少列出一个。列表缺失或为空将返回
400。可用值:
glbfbxobjusdzblendstl3mf
返回值
响应中的 result 字段保存新 Convert 任务的 ID。
失败模式
- Name
400 - Bad Request- Description
该请求无法运行。错误消息会说明发现了什么问题。例如:
- 缺少参数:既未发送
model_url,也未发送input_task_id。 - 缺少
target_formats:target_formats缺失或未列出任何格式。 - 输入任务无效:
input_task_id不是带有模型文件的成功 API 任务。 - 模型格式无效:
model_url文件的扩展名不受支持。 - URL 不可访问:Meshy 无法下载
model_url文件。 - 模型文件过大:
model_url文件来自http或httpsURL 时超过 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
例如:
- 积分不足:账户没有足够的积分来完成此任务,或账户已达到积分限额。请检查你的 积分 balance,然后重试。
- 免费计划:创建任务需要付费计划。请在你的订阅设置中升级计划,然后重试。
- 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
你已超出速率限制。请等待后重试。参阅速率限制。
获取 Convert 任务
根据 ID 返回一个 Convert 任务。
Request
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
}
删除 Convert 任务
永久删除一个 Convert 任务,包括其模型和数据。删除操作无法撤销。
Request
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 任务会退还你在创建该任务时所使用的积分。
IN_PROGRESS 任务无法被删除。该请求会返回 409 Conflict,
并且任务会继续运行。Meshy 不会为已经开始的任务退款,
因此删除它既会损失积分,也会损失结果。请等待它
变为 SUCCEEDED、FAILED 或 CANCELED 状态后再删除。
删除处于最终状态(SUCCEEDED、FAILED 或 CANCELED)的任务
不会退还其积分。
返回值
任务被删除时返回 200 OK;当任务处于
IN_PROGRESS 状态时返回 409 Conflict。
获取 Convert 任务列表
返回你的 Convert 任务列表。
Request
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
要返回的页码,最大为
255。更大的值将返回400。
- Name
- page_size
- Type
- integer
- 默认值 10
- Description
每页的任务数量,最大为
100。
- Name
- sort_by
- Type
- string
- Description
排序顺序。
可用值:
+created_at:从最早开始-created_at:从最新开始
返回值
一个分页的 Convert 任务对象列表。
流式获取 Convert 任务
以服务器发送事件(SSE)的形式,流式获取 Convert 任务的更新。
Request
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
- expires_at
- Type
- timestamp
- Description
任务下载链接过期的时间,以 Unix 毫秒数表示。在任务结束前为
0。
- Name
- texture_urls
- Type
- array
- Description
任务成功时,模型的 texture 贴图下载链接:一个对象数组,每个 texture 集合对应一个对象。每个对象都有一个
base_color链接,还可以有metallic、roughness、normal、emission和metallic_roughness链接。在任务成功前为null;当模型没有 texture 贴图时为空数组。
- Name
- task_error
- Type
- object
- Description
任务失败时的错误详情。参见 Errors。
- Name
- consumed_credits
- Type
- integer
- Description
任务消耗的积分数量,Convert 任务为
1。对于FAILED任务,该值为0。