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

Webhooks

Webhooksを使用すると、APIタスクが完了またはステータスが変化した際に、Meshyからリアルタイムの更新を受け取ることができます。設定が完了すると、Meshyは指定したURLにjson形式のイベントペイロードをPOSTします。

Webhooksを作成する理由

Webhooksを使用することには、特にAPIタスクのステータスを自動的に確認する点でいくつかの利点があります。Webhooksは、タスクのステータス更新を取得するためにAPIを継続的にポーリングするよりも、労力とコストを削減できます。また、Webhooksはほぼリアルタイムの更新を可能にし、APIポーリングよりも最終的にスケーラビリティに優れています。これにより、特に常にポーリングを行っている場合、レート制限をより適切に管理できるようになります。

セットアップと設定

Webhooksを有効にするには、Developer Platform内のWebhooksページを開き、「Create Webhook」ボタンをクリックしてください。Webhooksを受信したいhttps URLを入力し、Webhookを有効にすることで、Meshyからのタスク更新を自動的に受信できるようになります。 1つのMeshyアカウントにつき、最大5つのアクティブなWebhooksを設定できます。Webhookが有効になると、すべてのAPIタスクのステータス更新が自動的にペイロードURLへ送信されます。セキュリティ上の理由により、現時点ではhttps URLへのWebhook送信のみをサポートしています。ローカルテストを設定したい場合は、以下のセクションをご覧ください。

Webhook配信の要件

Webhookが正常に機能し、イベントを継続して受信するためには、以下の条件が必要です。

  • サーバーは400未満のHTTPステータスコード（例: 200 OK、202 Accepted）を返す必要があります。
  • >= 400のステータスコードを含むレスポンスは、配信失敗として扱われます。
  • 連続した複数回の失敗が発生すると、以下のような事態が起こる可能性があります。
    • progressの更新が遅延したり、順序どおりに届かなくなる
    • 繰り返しの試行後にWebhookが自動的に無効化される（自動無効化ポリシーを参照）

ヒント: 後続の処理が非同期で行われる場合でも、Webhookペイロードを検証・保存した後は、必ず成功レスポンスを返してください。

タスクの最終イベントが、通常かかる時間のおよそ2倍経過しても届かない場合は、GETエンドポイントを使用してタスクを取得してください。通常の処理時間と待機時間については、タスクのライフサイクルをご覧ください。

ローカルテスト用のWebhook転送

通常httpアドレスで動作するWebhookコードをローカルでテストしたい場合、WebhookプロキシURLを使用して、Webhooksをお使いのコンピューターやコードスペースへ転送できます。以下はsmee.ioを使用した推奨手順ですが、WebhookプロキシURLを生成できるものであれば、任意のサービスを使用して構いません。

WebhookプロキシURLを取得する:

  1. ブラウザでhttps://smee.io/にアクセスします
  2. 「Start a new channel」をクリックします
  3. 「Webhook Proxy URL」の下に表示されている完全なURLをコピーします。このURLは、以降のセットアップ手順で使用します。

Webhooksを転送する:

  1. smee-clientがまだインストールされていない場合は、ターミナルで以下のコマンドを実行してください。
npm install --global smee-client
  1. smee.ioから転送されたWebhooksを受信するには、ターミナルで以下のコマンドを実行します。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
  1. Webhookのテストを行っている間は、このプロセスを実行したままにしておいてください。Webhooksの転送を停止したい場合は、Ctrl+Cを入力してください。
    パスが/webhookで、ポートが3000であることに注意してください。これらの値は、後ほどWebhook配信を受信するための独自のコードを設定する際に役立つことがあります。

Webhookを作成する:

これで、WebhooksページでWebhookプロキシURLを使用して新しいWebhookを作成できます。

サンプルレスポンス

タスクのステータスが変化すると、Meshyは設定したURLへWebhookペイロードをPOSTします。このペイロードには、JSON形式でタスクオブジェクトが含まれています。すべてのタスクオブジェクトのプロパティとペイロードの例についての完全な説明は、以下をご覧ください。