任务生命周期
了解任务如何从请求发展到结果、通常需要多长时间,以及你的代码应该为此等待多久。
任务如何运行
创建请求会返回一个任务 ID,而无需等待任务运行完成。该任务随后在后台运行,你可以通过以下三种方式之一来跟踪它:轮询其 GET endpoint、打开其流式 endpoint,或接收一个 webhook。
PENDING 状态启动一个任务。工作进程接手后,任务会进入 IN_PROGRESS 状态,大部分时间都处于该状态。最终任务会以 SUCCEEDED 或 FAILED 结束,最终状态不会再发生变化。PENDINGIN_PROGRESSSUCCEEDEDFAILED任务会在其 created_at、started_at 和 finished_at 字段中记录每个步骤。
下表展示了在每种状态下你的代码应执行的操作。
| 状态 | 你的代码应执行的操作 |
|---|---|
PENDING | 继续等待。 |
IN_PROGRESS | 跟踪 progress:已完成工作的百分比,范围从 0 到 100。 |
SUCCEEDED | 下载结果。Meshy 会在有限的时间内保留文件。参见资产保留期。 |
FAILED | 读取 task_error,然后修复输入或创建新任务。参见 Errors。 |
CANCELED | 停止等待。该任务不会产生结果。只有 Creative Lab 任务会使用此状态。 |
SUCCEEDED、FAILED 和 CANCELED 都是最终状态。任务一旦达到其中之一,其状态就不会再发生变化。
从你的代码角度来看,流程如下:
请求: POST/image-to-3d
响应: 202{ "result": "<task_id>" }任务已创建
- 每隔几秒重复一次
请求: GET/image-to-3d/<task_id>
响应: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5
请求: GET/image-to-3d/<task_id>
响应: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }
GET。处理时间
下表显示的是 2026 年 9 月生产环境 API 流量中的中位耗时。
时间从任务创建开始计算,直至达到最终状态。由于任务通常只会在 PENDING 状态停留几秒钟,所以几乎所有时间都用于处理。当队列繁忙时,任务在开始前可能需要等待更长时间,而使用更高优先顺序套餐的任务通常会更快开始。
低于 2 分钟的时间以秒(s)为单位,更长的时间以分钟(min)为单位。“不支持”表示该模型下 API 不提供该选项。
3D 生成
| API | 配置 | meshy-7.1(latest) | meshy-6 | meshy-6-lite | meshy-t2 |
|---|---|---|---|---|---|
| Text to 3D (Preview) | 仅 Mesh | 75 秒 | 90 秒 | 45 秒 | 10 秒 |
| Image to 3D | 仅 Mesh | 75 秒 | 90 秒 | 40 秒 | 4 秒 |
| 带 2K texture 的 Mesh | 2 分钟 | 3 分钟 | 75 秒 | 60 秒 | |
| 带 4K texture 的 Mesh | 2.5 分钟 | 3.5 分钟 | 不支持 | 80 秒 | |
| 带 8K texture 的 Mesh | 3.5 分钟 | 4 分钟 | 不支持 | 2.5 分钟 | |
| Multi-Image to 3D | 仅 Mesh | 65 秒 | 2 分钟 | 30 秒 | 不支持 |
| 带 2K texture 的 Mesh | 2.5 分钟 | 3.5 分钟 | 85 秒 | 不支持 | |
| 带 4K texture 的 Mesh | 3 分钟 | 4 分钟 | 不支持 | 不支持 | |
| 带 8K texture 的 Mesh | 3.5 分钟 | 4.5 分钟 | 不支持 | 不支持 |
对于 Image to 3D 和 Multi-Image to 3D,“仅 Mesh”表示 should_texture: false。以下选项和输入会改变耗时:
- PBR 贴图(
enable_pbr)会增加 30 到 60 秒。 - 超精细 geometry(
geometry_resolution: "2k"或"4k")最多会增加 1 分钟。 - 在相同设置下,更复杂的输入图像耗时更长。
Texture 生成
| API | Texture 分辨率 | 典型耗时 |
|---|---|---|
| Text to 3D (Refine) | 2K 或 4K | 80 秒 |
| 8K | 3.5 分钟 | |
| Retexture | 2K | 55 秒 |
| 4K | 90 秒 | |
| 8K | 2.5 分钟 |
影像生成
| API | nano-banana | nano-banana-2 | nano-banana-pro | GPT Image 模型 |
|---|---|---|---|---|
| Text to Image | 20 秒 | 15 秒 | 25 秒 | 20 到 35 秒 |
| Image to Image | 40 秒 | 20 秒 | 30 秒 | 20 到 40 秒 |
Rigging 与 Animation
| API | 配置 | 典型耗时 |
|---|---|---|
| Auto-Rigging | 自动 rigging | 40 秒 |
| Animation | 每次请求 | 15 秒 |
| Text to Motion | prime mode | 15 秒 |
swift mode | 10 秒 |
后处理
3D 打印
| API | 配置 | 典型耗时 |
|---|---|---|
| 可打印性分析 | 仅 Mesh 检查 | 1 秒 |
| Mesh 与薄壁检查 | 10 秒 | |
| Multi-Color | 每次请求 | 30 秒 |
| 可打印性修复 | 仅 Mesh 修复 | 10 秒 |
| 薄壁检查,保留壁厚 | 20 秒 | |
| 薄壁检查,加厚壁体 | 100 秒 | |
| Auto Split | 纯色部件 | 70 秒 |
带 texture 的部件(keep_texture: true) | 170 秒 |
在 v2 中,可打印性修复 和 可打印性分析 始终会运行薄壁检查。在 v1 中,只有当你提供打印机类型或打印尺寸时才会运行该检查。
应等待多久
即使你的代码停止等待,任务仍会继续运行。如果你的请求超时、连接断开,或流式连接关闭,任务并不会因此失败,也不会被取消。
- 从任务的
created_at开始计算,至少等待 60 分钟后再停止等待。如果你过早停止,可能会错过之后成功完成的任务。这种情况主要发生在繁忙期间。 - 保留任务 ID。你可以随时再次获取该任务。如果 60 分钟后仍未达到最终状态,请稍后再次检查。如果情况依旧如此,请联系支持团队。
- 只有
FAILED才表示任务失败。Meshy 会自动为失败的任务退还积分。
请在你的代码中使用以下值:
| 设置 | 建议值 |
|---|---|
创建请求(POST)timeout | 60 秒 |
文件大小超过 100 MB 的 model_url 创建请求(POST)timeout | 120 秒。Meshy 会先下载文件,然后再做出响应。 |
状态请求(GET)timeout | 30 秒 |
| 轮询间隔 | Retry-After 响应头指定的值,若缺失则为 5 秒。轮询会计入你的速率限制。 |
失败的状态请求(timeout、429 或 5xx) | 在下一次轮询时重试。这并不意味着任务失败。 |
| 每个任务的总等待时间 | 从 created_at 起至少 60 分钟。重新连接流时不要重新计时。 |
| 流式连接 | 流可能会在任务完成前关闭。如果关闭时尚未得到最终状态,请重新连接或改用轮询。 |
如果需要同时处理大量任务,建议使用 webhooks,而不是逐一轮询。如果某个任务的最终事件在其典型耗时的大约两倍之后仍未到达,请通过其 GET endpoint 获取该任务。