lowpoly 将于 2026年10月30日 下线。 meshy-7 作为 3D 生成模型将于 2026年12月31日 下线;作为贴图模型仍可使用。 请在这些日期前切换模型,以免请求报错。 查看所有弃用信息

Webhooks

让 Meshy 在 API 任务取得进展或完成时向你的服务器发送 POST 请求,这样你就无需轮询了。


为什么要使用 webhook

与为每个任务的状态轮询 API 相比,webhook 所需的工作更少、成本也更低。Meshy 会在更新发生时立即发送,因此你能更快收到更新,而且 webhook 比轮询更具可扩展性。同时你发送的请求也更少,可以让你离速率限制更远一些。


设置 webhook

要添加 webhook,请按以下步骤操作:

  1. 在开发者平台中打开 Webhooks 页面,然后点击 Create Webhook。
  2. 在 Payload URL 中,输入接收投递的地址。Meshy 只通过 https:// 进行投递。
  3. 保存对话框中自动填入的 Webhook Secret 副本。每次投递都会携带它,便于你的服务器验证请求确实来自 Meshy。对于你已有的 webhook,可以点击其 Secret 列中的眼睛图标来查看它。
  4. 勾选 Active,然后点击 Confirm。

每个账户最多可以有 5 个处于激活状态的 webhook,总数上限为 10 个。每个激活状态的 webhook 都会收到你所有 API 任务的状态更新。

如果要用本机上的服务器测试 webhook,请参阅在本机进行测试。


处理投递

要接受一次投递,请返回低于 400 的状态码进行响应,例如 200 或 202。Meshy 大约会等待 25 秒以获取响应,因此请先保存投递内容再进行响应,然后再去做比较耗时的工作,例如下载模型。

状态码为 400 及以上,或没有响应,都会被视为投递失败。Meshy 会以逐渐延长的间隔进行重试,对于 IN_PROGRESS 更新最多重试 4 次,对于最终状态最多重试 9 次。如果连续 20 次更新的每次重试都失败,Meshy 可能会停用该 webhook。要重新启用它,请在 Webhooks 页面编辑它并勾选 Active。

请针对以下情况编写你的代码:

  • 投递可能会乱序到达。一次 IN_PROGRESS 投递可能会在最终投递之后到达,因此不要让它覆盖最终状态。
  • 同一次更新可能会被投递多次。请确保每一对 id 和 status 只被处理一次。
  • 任何知道你地址的人都可以向其发送请求。请将 X-MESHY-API-WEBHOOK-SECRET-KEY 与你保存的密钥副本进行比较,拒绝不匹配的请求。

如果某个任务的最终投递在超过其典型耗时大约两倍的时间后仍未到达,请通过该任务的 GET endpoint 获取任务信息。关于典型耗时以及应等待多久,请参阅任务生命周期。


在本机进行测试

Meshy 只向公开的 https:// 地址进行投递,因此无法直接连接到你本机上的服务器。要在本机测试代码,可以使用 webhook 代理将公开地址转发到本机。以下步骤使用 smee.io,不过任何 webhook 代理服务的使用方式都是类似的。

  1. 打开 smee.io 并点击 Start a new channel。复制 Webhook Proxy URL 下方的地址。

  2. 如果你还没有安装 smee 客户端,请先安装它:

    npm install --global smee-client
    
  3. 将该通道转发到你的服务器。请将 WEBHOOK_PROXY_URL 替换为你的 Webhook 代理地址:

    smee --url WEBHOOK_PROXY_URL --path /webhook --port 3000
    

    输出内容如下所示,其中 WEBHOOK_PROXY_URL 是你的 Webhook 代理地址:

    Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/webhook
    Connected WEBHOOK_PROXY_URL
    

    在测试期间请保持其运行。要停止转发,请按 Ctrl+C。你的服务器会在端口 3000 的 /webhook 路径上接收投递,因此请将你的代码设置为监听该路径。

  4. 在 Webhooks 页面上,创建一个 webhook,并将 Webhook 代理地址作为其 Payload URL。


投递 payload

Meshy 会在任务处于 IN_PROGRESS 状态时发送一次投递,并在任务达到最终状态时再发送一次。一个任务也可能在没有 IN_PROGRESS 投递的情况下直接达到最终状态。

每次投递都是向你的回拨地址发送的一次 POST 请求,包含以下请求头:

Header值
X-MESHY-API-WEBHOOK-SECRET-KEY该 webhook 的密钥
X-MESHY-API-WEBHOOK-USER-ID拥有该 webhook 的 Meshy 用户的 ID
Meshy-Webhook-Versionv1,表示请求体的格式
Content-Typeapplication/json
User-AgentMeshyAPIWebhook/1.0.0

JSON 请求体就是任务对象。它与该任务的 GET endpoint 返回的对象相同,只是 progress 字段不同。一次投递中 progress 会是以下值之一:

  • 任务处于 IN_PROGRESS 状态时为 50
  • 任务成功时为 100
  • 任务失败或被取消时为 0

关于每种任务对象的字段及示例,请参阅以下各节: