lowpoly 将于 2026年10月30日 下线。 meshy-7 作为 3D 生成模型将于 2026年12月31日 下线;作为贴图模型仍可使用。 请在这些日期前切换模型,以免请求报错。 查看所有弃用信息

任务生命周期

了解任务如何从请求发展到结果、通常需要多长时间,以及你的代码应该为此等待多久。


任务如何运行

创建请求会返回一个任务 ID,而无需等待任务运行完成。该任务随后在后台运行,你可以通过以下三种方式之一来跟踪它:轮询其 GET endpoint、打开其流式 endpoint,或接收一个 webhook。

创建请求会以 PENDING 状态启动一个任务。工作进程接手后,任务会进入 IN_PROGRESS 状态,大部分时间都处于该状态。最终任务会以 SUCCEEDED 或 FAILED 结束,最终状态不会再发生变化。
创建请求
PENDING
在队列中等待
IN_PROGRESS
正在生成结果
SUCCEEDED
下载结果
FAILED
积分已退还

任务会在其 created_at、started_at 和 finished_at 字段中记录每个步骤。

下表展示了在每种状态下你的代码应执行的操作。

状态你的代码应执行的操作
PENDING继续等待。
IN_PROGRESS跟踪 progress:已完成工作的百分比,范围从 0 到 100。
SUCCEEDED下载结果。Meshy 会在有限的时间内保留文件。参见资产保留期。
FAILED读取 task_error,然后修复输入或创建新任务。参见 Errors。
CANCELED停止等待。该任务不会产生结果。只有 Creative Lab 任务会使用此状态。

SUCCEEDED、FAILED 和 CANCELED 都是最终状态。任务一旦达到其中之一,其状态就不会再发生变化。

从你的代码角度来看,流程如下:

创建一个任务,然后轮询它直到完成。
  1. 请求: POST/image-to-3d

  2. 响应: 202{ "result": "<task_id>" }任务已创建

  3. 每隔几秒重复一次
    1. 请求: GET/image-to-3d/<task_id>

    2. 响应: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5

  4. 请求: GET/image-to-3d/<task_id>

  5. 响应: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }

如果你的应用停止等待,任务仍会继续运行。之后可使用相同的任务 ID 对其执行 GET。

处理时间

下表显示的是 2026 年 9 月生产环境 API 流量中的中位耗时。

时间从任务创建开始计算,直至达到最终状态。由于任务通常只会在 PENDING 状态停留几秒钟,所以几乎所有时间都用于处理。当队列繁忙时,任务在开始前可能需要等待更长时间,而使用更高优先顺序套餐的任务通常会更快开始。

低于 2 分钟的时间以秒(s)为单位,更长的时间以分钟(min)为单位。“不支持”表示该模型下 API 不提供该选项。

3D 生成

API配置meshy-7.1(latest)meshy-6meshy-6-litemeshy-t2
Text to 3D (Preview)仅 Mesh75 秒90 秒45 秒10 秒
Image to 3D仅 Mesh75 秒90 秒40 秒4 秒
带 2K texture 的 Mesh2 分钟3 分钟75 秒60 秒
带 4K texture 的 Mesh2.5 分钟3.5 分钟不支持80 秒
带 8K texture 的 Mesh3.5 分钟4 分钟不支持2.5 分钟
Multi-Image to 3D仅 Mesh65 秒2 分钟30 秒不支持
带 2K texture 的 Mesh2.5 分钟3.5 分钟85 秒不支持
带 4K texture 的 Mesh3 分钟4 分钟不支持不支持
带 8K texture 的 Mesh3.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 生成

APITexture 分辨率典型耗时
Text to 3D (Refine)2K 或 4K80 秒
8K3.5 分钟
Retexture2K55 秒
4K90 秒
8K2.5 分钟

影像生成

APInano-banananano-banana-2nano-banana-proGPT Image 模型
Text to Image20 秒15 秒25 秒20 到 35 秒
Image to Image40 秒20 秒30 秒20 到 40 秒

Rigging 与 Animation

API配置典型耗时
Auto-Rigging自动 rigging40 秒
Animation每次请求15 秒
Text to Motionprime mode15 秒
swift mode10 秒

后处理

API典型耗时
Remesh2 分钟
UV Unwrap35 秒
Convert7 秒
Resize15 秒

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)timeout60 秒
文件大小超过 100 MB 的 model_url 创建请求(POST)timeout120 秒。Meshy 会先下载文件,然后再做出响应。
状态请求(GET)timeout30 秒
轮询间隔Retry-After 响应头指定的值,若缺失则为 5 秒。轮询会计入你的速率限制。
失败的状态请求(timeout、429 或 5xx)在下一次轮询时重试。这并不意味着任务失败。
每个任务的总等待时间从 created_at 起至少 60 分钟。重新连接流时不要重新计时。
流式连接流可能会在任务完成前关闭。如果关闭时尚未得到最终状态,请重新连接或改用轮询。

如果需要同时处理大量任务,建议使用 webhooks,而不是逐一轮询。如果某个任务的最终事件在其典型耗时的大约两倍之后仍未到达,请通过其 GET endpoint 获取该任务。