lowpoly 将于 2026年10月30日 下线。 请在这些日期前切换模型，以免请求报错。 查看所有弃用信息

任务生命周期

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

任务如何运行

创建请求会返回一个任务 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 不提供该选项。

这些只是典型时间，并非保证的完成时间。在繁忙期间，部分任务耗时更长，但仍会成功完成。要查看 Meshy 的状态，请参见状态页面。请勿在你的代码中将这些时间用作 timeout。有关 timeout 值，请参见应等待多久。

3D 生成

API配置meshy-7.1（latest）meshy-6meshy-6-litemeshy-t2
Text to 3D (Preview)仅 mesh75 s90 s45 s10 s
Image to 3D仅 mesh75 s90 s40 s4 s
带 2K texture 的 mesh2 min3 min75 s60 s
带 4K texture 的 mesh2.5 min3.5 min不支持80 s
带 8K texture 的 mesh3.5 min4 min不支持2.5 min
Multi-Image to 3D仅 mesh65 s2 min30 s不支持
带 2K texture 的 mesh2.5 min3.5 min85 s不支持
带 4K texture 的 mesh3 min4 min不支持不支持
带 8K texture 的 mesh3.5 min4.5 min不支持不支持

对于 Image to 3D 和 Multi-Image to 3D，"仅 mesh" 表示 should_texture: false。以下选项和输入会影响耗时：

  • PBR 贴图（enable_pbr）会增加 30 到 60 秒。
  • 超高 geometry（geometry_resolution: "2k" 或 "4k"）最多会增加 1 分钟。
  • 在相同设置下，输入图像越复杂，耗时越长。

纹理贴图

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

图像生成

APInano-banananano-banana-2nano-banana-proGPT Image 模型
文字生成影像20 s15 s25 s20 到 35 s
影像生成影像40 s20 s30 s20 到 40 s

Rigging 与 Animation

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

后处理

API典型耗时
Remesh2 min
UV Unwrap35 s
Convert7 s
尺寸调整15 s

3D 打印

API配置典型耗时
可打印性分析仅 mesh 检查1 s
mesh 与薄壁检查10 s
Multi-Color每次请求30 s
可打印性修复仅 mesh 修复10 s
薄壁检查，保留壁厚20 s
薄壁检查，壁厚增厚100 s
Auto Split每次请求70 s

在 v2 中，可打印性修复与可打印性分析始终会运行薄壁检查。在 v1 中，只有在发送打印机类型或打印尺寸时才会运行该检查。

应等待多久

即使你的代码停止等待，任务仍会继续运行。如果你的请求超时、连接中断，或流关闭，任务既不会失败，也不会被取消。

  • 从任务的 created_at 开始计算，至少等待 60 分钟后再停止等待。如果提前停止，你可能会错过稍后成功完成的任务。这种情况多发生在繁忙期间。
  • 保留任务 ID。你可以随时重新获取该任务。如果 60 分钟后仍未达到最终状态，请稍后再次检查。如果情况持续如此，请联系支持团队。
  • 只有 FAILED 才意味着任务失败。Meshy 会自动为失败的任务退还积分。

请在你的代码中使用以下数值：

设置推荐值
创建请求（POST）timeout60 秒
model_url 文件超过 100 MB 时的创建请求（POST）timeout120 秒。Meshy 会先下载该文件，然后再响应。
状态请求（GET）timeout30 秒
轮询间隔Retry-After 标头指定的值，若缺失则为 5 秒。轮询会计入你的速率限制。
状态请求失败（timeout、429 或 5xx）在下一次轮询时重试。这并不意味着任务失败。
单个任务的总体等待时间从 created_at 起至少 60 分钟。重新连接流时不要重新计时。
流流可能会在任务完成前关闭。如果关闭时没有最终状态，请重新连接或改用轮询。

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