Meshy API Webhooks vs轮询：结果何时准备好

Meshy API 的生成任务（文本转 3D、图像转 3D、绑定等）均为异步任务：提交后，需要先确认任务完成才能获取结果。本文说明任务生命周期，以及两种获知完成状态的方法：轮询与 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。

• 每隔数秒调用相应的“获取任务”端点，例如文本转 3D 或图像转 3D 的按 ID 查询端点。

• 检查每个响应的 status 字段；为 PENDING 或 IN_PROGRESS 时继续轮询。

• status 变为 SUCCEEDED（可读取结果 URL）、FAILED 或 CANCELED 时停止轮询。

• 在客户端设置合理的超时或最大尝试次数，避免任务卡住后无限轮询。

轮询简单，适合脚本、批处理任务和低调用量集成。高调用量或对延迟敏感的集成通常更适合使用 Webhook。

无需反复查询“完成了吗？”，也可让 Meshy 在任务完成时通知你的服务器。要使用 Webhook：

• 配置一个 Meshy 可访问的 Webhook（回调）URL。具体可在账户 / API 设置中配置，或作为生成请求参数传入，取决于端点。

• 确保端点可通过 HTTPS 公开访问并快速响应：先立即返回 2xx，再异步处理负载。

• 任务进入终态时，Meshy 会向端点发送包含任务 id 和最终 status 的负载。

• 收到通知后，应通过 id 调用 API 查询完整任务详情，而不要只信任 Webhook 正文，以获得权威且最新的结果。

Webhooks减少不必要的API调用并提供近实时的通知，但您应该保留一个定期轮询备用方案，以防万一webhook传递可能被遗漏或延迟（例如由于您一方的瞬时网络问题）。

无论您使用轮询还是webhooks，您的结果处理代码应该是幂等的——对同一任务多次运行都是安全的，无副作用。这很重要，因为：

• Webhook可能被多次传递给同一任务（发送方端重试、网络重复等）。

• 轮询循环和webhook处理程序可能都尝试处理同一已完成的任务（如果两者都在运行）。

要保持幂等性，请使用任务id对您的处理逻辑进行键入——例如，在再次执行之前检查您是否已为该id存储/下载了结果，并在您自己的数据库中进行"标记为已处理"为单个原子步骤。

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

• 验证status === "SUCCEEDED"，然后再从result/模型URL字段中读取任何内容。

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

• 一旦SUCCEEDED，立即下载结果文件——生成的资产仅在Meshy的服务器上保留有限的时间，之后URL将不再解析。

大多数"我无法检索我的模型"报告都可以追溯到以下原因之一：

• 过早获取。 在status为SUCCEEDED之前调用结果URL或读取模型字段。这是迄今为止最频繁的原因。

• 资产过期。 在SUCCEEDED后等待太长时间才下载——结果URL在该任务类型的保留窗口过后停止工作。

• 使用过时或错误的任务ID ——例如，重复使用来自先前、无关请求的ID。

• 将FAILED视为瞬态 并继续轮询已失败的任务，而不是重新提交。

• 您的服务器和Meshy之间的网络/超时问题被误读为生成问题。

如果生成不符合您的期望，或请求完全失败，请记住以下内容：

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

• 对于调用API时的瞬时网络故障（超时、5xx响应），在重新提交请求之前进行短的指数退避是合理的。

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

• 如果您需要生成的内置重试功能，请与Meshy销售团队联系有关企业计划选项。

这几乎总是发生在代码尝试在任务完成之前读取结果时。在检索模型URL之前，始终确认status为SUCCEEDED（并且progress为100）。

轮询更容易设置，适用于低容量或一次性脚本。Webhooks更适合生产集成，有许多并发任务，因为它们避免不必要的重复请求，并在任务完成时立即通知您。

幂等地处理它——检查任务id是否与您已处理的内容相对，如果已被处理，则跳过重新处理。

回退到直接通过id轮询任务。还要确认您的端点可通过HTTPS公开访问并返回快速的2xx响应，因为慢速或不可到达的端点会导致传递问题。

目前不能——您需要提交新的生成请求，这正常消耗积分。如果您需要内置重试支持，请联系销售部门了解企业选项。

结果文件仅在任务完成后在Meshy的服务器上保留有限的时间，因此一旦任务成功就立即下载输出到您自己的存储，而不是等待。

• 使用API从生成结果检索模型时为什么我一直遇到错误？