# Meshy API Webhooks vs轮询：结果何时准备好 > URL: https://help.meshy.ai/zh-CN/articles/16102100-meshy-api-webhooks-vs-polling-when-results-are-ready > Language: zh-CN > Last updated: 2026-07-28T21:47:26Z 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。 ## 设置 Webhook 无需反复查询“完成了吗？”，也可让 Meshy 在任务完成时通知你的服务器。要使用 Webhook： - 配置一个 Meshy 可访问的 Webhook（回调）URL。具体可在账户 / API 设置中配置，或作为生成请求参数传入，取决于端点。 - 确保端点可通过 HTTPS 公开访问并快速响应：先立即返回 2xx，再异步处理负载。 - 任务进入终态时，Meshy 会向端点发送包含任务 `id` 和最终 `status` 的负载。 - 收到通知后，应通过 `id` 调用 API 查询完整任务详情，而不要只信任 Webhook 正文，以获得权威且最新的结果。 Webhooks减少不必要的API调用并提供近实时的通知，但您应该保留一个定期轮询备用方案，以防万一webhook传递可能被遗漏或延迟（例如由于您一方的瞬时网络问题）。 ## 幂等性 无论您使用轮询还是webhooks，您的结果处理代码应该是幂等的——对同一任务多次运行都是安全的，无副作用。这很重要，因为： - Webhook可能被多次传递给同一任务（发送方端重试、网络重复等）。 - 轮询循环和webhook处理程序可能都尝试处理同一已完成的任务（如果两者都在运行）。 要保持幂等性，请使用任务`id`对您的处理逻辑进行键入——例如，在再次执行之前检查您是否已为该`id`存储/下载了结果，并在您自己的数据库中进行"标记为已处理"为单个原子步骤。 ### 状态=SUCCEEDED 带有`"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销售团队联系有关企业计划选项。 ## 常见问题 ### 1. 通过API从生成结果检索模型时，为什么我一直得到错误？ 这几乎总是发生在代码尝试在任务完成之前读取结果时。在检索模型URL之前，始终确认`status`为`SUCCEEDED`（并且`progress`为100）。 ### 2. 我应该使用轮询还是webhooks？ 轮询更容易设置，适用于低容量或一次性脚本。Webhooks更适合生产集成，有许多并发任务，因为它们避免不必要的重复请求，并在任务完成时立即通知您。 ### 3. 如果我的服务器收到相同的webhook两次，应该怎样做？ 幂等地处理它——检查任务`id`是否与您已处理的内容相对，如果已被处理，则跳过重新处理。 ### 4. 我的webhook从未到达——我应该做什么？ 回退到直接通过`id`轮询任务。还要确认您的端点可通过HTTPS公开访问并返回快速的2xx响应，因为慢速或不可到达的端点会导致传递问题。 ### 5. 我能直接通过API重试失败或不令人满意的生成吗？ 目前不能——您需要提交新的生成请求，这正常消耗积分。如果您需要内置重试支持，请联系销售部门了解企业选项。 ### 6. 状态为SUCCEEDED后，我有多长时间下载结果？ 结果文件仅在任务完成后在Meshy的服务器上保留有限的时间，因此一旦任务成功就立即下载输出到您自己的存储，而不是等待。 ## 相关文章 - [使用API从生成结果检索模型时为什么我一直遇到错误？](/zh-CN/articles/9992036-why-do-i-consistently-encounter-errors-when-retrieving-the-models-from-generation-result-using-api)