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 通常更合适。
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
只有当响应中包含 "status": "SUCCEEDED" 且 "progress": 100 时，才能保证结果负载（模型 URL、贴图、缩略图）已完整生成且可以安全使用。具体来说，在你的代码中：
在读取
result/模型 URL 字段中的任何内容之前，先确认status === "SUCCEEDED"。不要只依赖
progress——始终同时检查status，因为任务完全结束前，progress 可能会短暂显示较高的数值。一旦状态为
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. 我应该使用轮询还是 Webhook？
轮询更易于设置，适合低频率或一次性脚本。Webhook 更适合有许多并发任务的生产环境集成，因为它们可以避免不必要的重复请求，并在任务完成时立即通知你。
3. 如果服务器两次收到同一个 Webhook，应该怎么处理？
以幂等方式处理——检查任务 id 是否已在已处理列表中，如果已经处理过，就跳过重复处理。
4. 我的 Webhook 一直没有送达——该怎么办？
回退为直接按 id 轮询任务。同时确认你的端点可通过 HTTPS 公开访问，并快速返回 2xx 响应，因为端点响应缓慢或不可达可能导致投递问题。
5. 能否直接通过 API 重试失败或不理想的生成任务？
目前不支持——你需要提交新的生成请求，这会正常消耗额度。如果你需要内置的重试支持，请联系销售了解企业版方案。
6. 在 status 为 SUCCEEDED 之后，我有多少时间下载结果？
任务完成后，结果文件仅在 Meshy 服务器上保留有限时间，因此任务成功后应尽快将输出下载到你自己的存储，不要等待。