Meshy API Webhooks 与轮询：结果何时就绪

Meshy API 生成任务（Text to 3D、Image to 3D、Rigging 等）以异步方式运行——您提交任务后，需要先确认任务何时完成，然后才能获取结果。本文将介绍任务生命周期，以及两种用于了解任务何时完成的受支持方式：轮询和 Webhook——并说明如何避免最常见的“获取模型时出错”问题。

每个生成任务都会经历一组状态，这些状态通过任务对象的 status 字段返回：

• PENDING — 任务已加入队列，但尚未开始处理。

• IN_PROGRESS — 任务正在处理中。progress 字段（0-100）会随着工作完成而增加。

• SUCCEEDED — 任务已成功完成，progress 为 100。此时响应中可获得结果 URL（模型文件、纹理、预览图）。

• FAILED — 任务无法完成。失败任务的积分将自动退还。

• CANCELED — 任务在完成前被取消。

集成 API 时最重要的一条规则：在任务的 status 变为 SUCCEEDED 之前，切勿尝试获取或使用结果 URL。在任务仍处于 PENDING 或 IN_PROGRESS 状态时读取结果，是报告"获取模型出错"最常见的原因。

轮询是指针对你的任务 ID 反复调用"获取任务"端点，直到任务达到终态（SUCCEEDED、FAILED 或 CANCELED）。一个简单的轮询循环如下所示：

• 提交生成请求，并保存返回的任务 id。

• 按一定的时间间隔调用对应的"检索任务"端点（例如 Text to 3D 或 Image to 3D 的按 ID 查询任务端点）——通常每隔几秒调用一次。

• 检查每次响应中的 status 字段。当状态为 PENDING 或 IN_PROGRESS 时继续轮询。

• 一旦 status 变为 SUCCEEDED（读取结果 URL）、FAILED 或 CANCELED，立即停止轮询。

• 在你的客户端中添加合理的超时/最大尝试次数保护，以免任务卡住时无限轮询。

轮询简单易用，非常适合脚本、批量作业和低调用量的集成场景。对于高调用量或对延迟敏感的集成，Webhook 通常是更合适的选择。

除了反复询问"完成了吗？"之外，你还可以让 Meshy 在任务完成的那一刻通知你的服务器。要使用 Webhook：

• 配置一个 Meshy 可以访问的 Webhook（回调）URL——这通常在账户/API 设置层面进行配置，或作为生成请求的参数传递，具体取决于端点。

• 确保你的端点可通过 HTTPS 公开访问，并能快速响应（立即返回 2xx 状态码，然后异步处理负载）。

• 当任务到达终态时，Meshy 会向你的端点发送一个负载，其中包含任务的 id 及其最终 status。

• 收到通知后，应通过 API 根据 id 查询完整的任务详情，而不是仅信任 Webhook 正文，以确保你获得的是权威的、最新的结果。

Webhook 可以减少不必要的 API 调用，并为你提供近乎即时的通知，但你仍应保留一个定期轮询的备用方案，以应对 Webhook 可能未送达或延迟的任务（例如由于你这边的临时网络问题）。

无论您使用轮询还是 Webhook，您的结果处理代码都应具备幂等性——即对同一任务可以安全地运行多次而不产生副作用。这一点很重要，因为：

• 同一个任务的 Webhook 可能会被多次送达（发送方重试、网络重复等）。

• 如果轮询循环和 Webhook 处理程序同时在运行，它们可能都会尝试处理同一个已完成的任务。

要保持幂等性，请以任务的 id 作为处理逻辑的键——例如，在再次执行之前，先检查您是否已经为该 id 存储/下载了结果，并将“标记为已处理”作为您自己数据库中的一个原子操作步骤。

带有 "status": "SUCCEEDED" 且 "progress": 100 的响应，是唯一能够保证结果负载（模型 URL、纹理、缩略图）完整且可安全使用的信号。具体来说，在你的代码中：

• 在从 result/模型 URL 字段中读取任何内容之前，请先验证 status === "SUCCEEDED"。

• 不要仅依赖 progress——同时也要始终检查 status，因为在任务完全完成之前，进度可能会短暂显示较高的值。

• 一旦状态为 SUCCEEDED，请立即下载结果文件——生成的资产只会在 Meshy 的服务器上保留有限的时间，之后这些 URL 将无法再访问。

大多数“无法获取模型”的反馈都可以追溯到以下原因之一：

• 获取过早。 在 status 变为 SUCCEEDED 之前就调用结果 URL 或读取模型字段。这是目前最常见的原因。

• 资产已过期。 在 SUCCEEDED 之后等待太久才下载——超过该任务类型的保留期限后，结果 URL 将失效。

• 使用了过期或错误的任务 ID——例如，重复使用了之前某个不相关请求中的 ID。

• 将 FAILED 当作暂时状态，继续轮询一个已经失败的任务，而不是重新提交。

• 网络/超时问题——您的服务器与 Meshy 之间的网络/超时问题被误认为是生成问题。

如果生成结果不符合您的预期，或者请求完全失败，请注意以下几点：

• Meshy API 目前不支持就地重试现有任务——如需重试，请提交新的生成请求，新请求将正常消耗积分。

• 对于调用 API 时出现的暂时性网络故障（超时、5xx 响应），在重新提交请求前采用短暂的指数退避是合理的做法。

• 对于轮询本身，在遇到暂时性网络错误时可以重试“获取任务”调用，但不要将单次失败的轮询视为生成失败——只有在获得成功的响应后，才应信任 status 字段。

这几乎总是因为代码试图在任务完成之前读取结果。在获取模型 URL 之前，请务必确认 status 为 SUCCEEDED（且 progress 为 100）。

轮询设置更简单，适合低频次或一次性脚本。Webhook 更适合有多个并发任务的生产环境集成，因为它可以避免不必要的重复请求，并在任务完成时立即通知你。

以幂等方式处理——将任务 id 与你已处理过的记录进行比对，如果已处理过则跳过重复处理。

回退到直接通过 id 轮询任务。同时确认你的端点可通过 HTTPS 公开访问，并能快速返回 2xx 响应，因为响应缓慢或无法访问的端点可能会导致送达问题。

目前不可以——你需要提交一个新的生成请求，该请求会正常消耗积分。如果你需要内置的重试支持，请联系销售了解企业版方案。

任务完成后，结果文件只会在 Meshy 的服务器上保留有限的时间，因此请在任务成功后尽快将输出文件下载到你自己的存储中，而不要等待。