lowpoly は 2026/10/30 に廃止されます。 3D 生成モデルとしての meshy-7 は 2026/12/31 に廃止されます。テクスチャモデルとしては引き続き利用できます。 リクエストエラーを避けるため、これらの日付までにモデルを切り替えてください。 非推奨の一覧を見る

Webhooks

APIタスクがprogressを進めたり完了したりしたときに、MeshyがあなたのサーバーにPOSTリクエストを送るようにして、ポーリングの必要をなくせます。


Webhooksを使う理由

Webhooksは、各タスクのステータスをAPIにポーリングするよりも手間が少なく、コストも低く済みます。Meshyは更新が発生するたびに送信するため、より早く情報を受け取れますし、Webhooksはポーリングよりもスケールします。送信するリクエストの数も減るため、レート制限からより余裕を持てます。


Webhookを設定する

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

  1. Developer PlatformのWebhooksページを開き、Create Webhookをクリックします。
  2. Payload URLに、配信を受け取るURLを入力します。Meshyはhttps://経由でのみ配信します。
  3. ダイアログが入力するWebhook Secretのコピーを保管してください。すべての配信にこれが付与されるため、サーバー側でリクエストがMeshyから来たものかを確認できます。既存のWebhookについては、Secret列の目のアイコンをクリックすると確認できます。
  4. Activeを選択し、Confirmをクリックします。

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

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


配信を処理する

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

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

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

  • 配信は順序どおりに届かないことがあります。IN_PROGRESSの配信が最終配信の後に届くことがあるため、それによって最終ステータスを上書きしないようにしてください。
  • 同じ更新が複数回届くことがあります。idとstatusの組み合わせごとに一度だけ処理してください。
  • あなたのURLを知っている人なら誰でもリクエストを送信できます。X-MESHY-API-WEBHOOK-SECRET-KEYを手元のシークレットのコピーと比較し、一致しないリクエストは拒否してください。

タスクの最終配信が、そのタスクの典型的な所要時間のおよそ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プロキシURLに置き換えてください。

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

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

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

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

  4. Webhooksページで、WebhookプロキシURLをPayload URLとしたWebhookを作成してください。


配信ペイロード

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

各配信は、以下のヘッダーを伴ったPayload URLへのPOSTです。

HeaderValue
X-MESHY-API-WEBHOOK-SECRET-KEYwebhookのシークレット
X-MESHY-API-WEBHOOK-USER-IDwebhookを所有するMeshyユーザーのID
Meshy-Webhook-Versionv1(ボディの形式)
Content-Typeapplication/json
User-AgentMeshyAPIWebhook/1.0.0

JSONボディはタスクオブジェクトです。これは、そのタスクのGETエンドポイントが返すものと同じオブジェクトですが、progressだけは異なります。配信におけるprogressは、以下のいずれかの値で送られます。

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

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