lowpoly は 2026/10/30 に廃止されます。 リクエストエラーを避けるため、これらの日付までにモデルを切り替えてください。 非推奨の一覧を見る

Webhooks

APIタスクが進行または完了したときに、MeshyからあなたのサーバーへPOSTリクエストを送信させることで、ポーリングが不要になります。

Webhooksを使う理由

Webhooksは、各タスクのステータスをAPIにポーリングするよりも手間がかからず、コストも抑えられます。Meshyは更新が発生するたびに送信するため、より早く受け取ることができ、Webhooksはポーリングよりもスケールしやすくなります。また、送信するリクエストの数も減るため、レート制限に対してより余裕を持つことができます。

Webhookを設定する

Webhookを追加するには、以下の手順に従ってください。

  1. Developer Platform内のWebhooksページを開き、Create Webhookをクリックします。
  2. Payload URLに、配信を受け取るURLを入力します。Meshyはhttps://経由でのみ配信します。
  3. Activeを選択し、Confirmをクリックします。

各アカウントは、アクティブなWebhookを5つまで、合計10個まで持つことができます。アクティブなWebhookはすべて、あなたのすべてのAPIタスクのステータス更新を受け取ります。

自分のコンピュータ上のサーバーでWebhookをテストするには、自分のコンピュータでテストするを参照してください。

配信を処理する

配信を受け付けるには、200や202など、400未満のステータスで応答してください。Meshyは応答を約25秒待つため、まず配信内容を保存してから応答してください。モデルのダウンロードなど、時間のかかる処理はその後に行ってください。

400以上のステータス、または応答がない場合は、配信失敗として扱われます。Meshyは試行間の待機時間を徐々に延ばしながら再試行し、IN_PROGRESS更新の場合は最大4回、最終ステータスの場合は最大9回再試行します。20回連続の更新がすべての試行で失敗した場合、Meshyはそのwebhookを無効化することがあります。再度有効にするには、Webhooksページで編集し、Activeを選択してください。

以下のケースに対応できるようにコードを書いてください。

  • 配信は順不同で届くことがあります。IN_PROGRESSの配信が最終配信の後に届くこともあるため、それによって最終ステータスを上書きしないようにしてください。
  • 同じ更新が複数回届くことがあります。idとstatusの組み合わせごとに1回だけ処理するようにしてください。

タスクの通常の所要時間のおよそ2倍が経過してもタスクの最終配信が届かない場合は、そのタスクのGETエンドポイントからタスクを取得してください。通常の所要時間と待機すべき時間については、タスクのライフサイクルを参照してください。

自分のコンピュータでテストする

Meshyは公開されたhttps://のURLにのみ配信するため、あなたのコンピュータ上のサーバーに直接届けることはできません。自分のコンピュータ上のコードをテストするには、webhookプロキシを使って公開URLをそのコンピュータに転送してください。以下の手順ではsmee.ioを使用しますが、どのwebhookプロキシサービスでも同様に動作します。

  1. smee.ioを開き、Start a new channelをクリックします。Webhook Proxy URLの下にあるURLをコピーします。

  2. smeeクライアントをまだインストールしていない場合は、インストールしてください。

    npm install --global smee-client

  3. チャンネルをあなたのサーバーに転送します。WEBHOOK_PROXY_URLをあなたのWebhook Proxy URLに置き換えてください。

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

    出力は次のようになります。ここでWEBHOOK_PROXY_URLはあなたのWebhook Proxy URLです。

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

    テスト中はこれを実行したままにしてください。転送を停止するには、Ctrl+Cを押します。あなたのサーバーはポート3000のパス/webhookで配信を受け取るため、そこでリッスンするようにコードを設定してください。

  4. Webhooksページで、Webhook Proxy URLをPayload URLとしてWebhookを作成します。

配信ペイロード

Meshyは、タスクがIN_PROGRESSの間に1回配信を送信し、タスクが最終ステータスに達したときにもう1回送信します。タスクはIN_PROGRESSの配信を経ずに最終ステータスに達することもあります。

各配信は、タスクオブジェクトをJSONボディとしてあなたのPayload URLへ送信されるPOSTです。これは、タスクのGETエンドポイントが返すものと同じオブジェクトですが、progressは例外です。配信では、progressは以下のいずれかの値として送信されます。

  • タスクがIN_PROGRESSの間は50
  • タスクが成功したときは100
  • タスクが失敗またはキャンセルされたときは0

各タスクオブジェクトのフィールドと例については、以下のセクションを参照してください。