Meshy APIのWebhookとポーリングの比較: 結果が準備できるタイミング

Meshy APIの生成タスク（Text to 3D、Image to 3D、Riggingなど）は非同期で実行されます。タスクを送信した後、結果を取得する前に、タスクが完了したタイミングを確認する必要があります。この記事では、タスクのライフサイクルと、タスクの完了を検知するための2つのサポートされた方法（ポーリングとWebhook）について説明します。さらに、最もよくある「モデル取得時のエラー」を回避する方法も説明します。

すべての生成タスクは、いくつかの状態を経て進行します。これらの状態はタスクオブジェクトの status フィールドで返されます。

• PENDING — タスクはキューに登録されていますが、処理はまだ開始されていません。

• IN_PROGRESS — タスクは処理中です。作業の完了に伴い、progress フィールド（0〜100）が増加します。

• SUCCEEDED — タスクは正常に完了し、progress は100になります。レスポンスで結果URL（モデルファイル、テクスチャ、プレビュー）が利用可能になります。

• FAILED — タスクを完了できませんでした。失敗したタスクのクレジットは自動的に返還されます。

• CANCELED — タスクは完了前にキャンセルされました。

APIを利用する際に最も重要なルールは次の1点です: タスクの 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の方が適しています。

「まだ完了していませんか？」と何度も問い合わせる代わりに、タスクが完了した瞬間にMeshyからサーバーへ通知するよう依頼できます。Webhookを使用するには:

• Meshyから到達可能なWebhook（コールバック）URLを設定します。これは通常、エンドポイントに応じてアカウント/API設定レベルで設定するか、生成リクエストのパラメータとして渡します。

• エンドポイントがHTTPS経由で公開されており、すばやく応答することを確認します（すぐに2xxステータスを返し、その後ペイロードを非同期で処理します）。

• タスクが終了状態に達すると、Meshyはタスクのidと最終的なstatusを含むペイロードをエンドポイントに送信します。

• 受信したら、Webhookの本文だけを信頼するのではなく、API経由でidによりタスクの詳細全体を取得し、信頼できる最新の結果を確実に入手してください。

Webhookは不要なAPI呼び出しを減らし、ほぼ即時の通知を実現しますが、Webhookの配信が欠落または遅延する可能性があるタスク（例: ご利用側の一時的なネットワーク問題）に備えて、定期的なポーリングのフォールバックを引き続き用意しておく必要があります。

ポーリングとWebhookのどちらを使用する場合でも、結果を処理するコードは冪等である必要があります。つまり、同じタスクに対して副作用なく複数回実行しても安全でなければなりません。これが重要な理由は次のとおりです。

• 同じタスクに対してWebhookが複数回配信される可能性があります（送信側でのリトライ、ネットワークによる重複など）。

• ポーリングループとWebhookハンドラーが同時に動作している場合、両方が同じ完了済みタスクを処理しようとする可能性があります。

冪等性を保つには、処理ロジックをタスクの id をキーにして設計してください。たとえば、その id の結果をすでに保存またはダウンロード済みかどうかを確認してから再度実行し、「処理済みとしてマーク」する操作を自らのデータベース内で単一のアトミックなステップにしてください。

"status": "SUCCEEDED" と "progress": 100 を含むレスポンスだけが、結果のペイロード（モデルURL、テクスチャ、サムネイル）が完全であり、安全に使用できることを保証するシグナルです。具体的には、コード内で次のようにしてください:

• result/モデルURLのフィールドから何かを読み取る前に、status === "SUCCEEDED" を検証してください。

• progress だけに依存しないでください。タスクが完全に確定する前に progress が一時的に高い値を示すことがあるため、必ず status も確認してください。

• SUCCEEDED になったら、結果ファイルを速やかにダウンロードしてください。生成されたアセットはMeshyのサーバー上に限られた期間しか保持されず、その後はURLが解決されなくなります。

「モデルを取得できない」という報告のほとんどは、次のいずれかが原因です:

• 取得が早すぎる。 status が SUCCEEDED になる前に、結果URLを呼び出したり、モデルフィールドを読み取ったりしている。これは最も頻繁な原因です。

• アセットの有効期限切れ。 SUCCEEDED の後、ダウンロードまでに時間がかかりすぎている — 結果URLは、そのタスクタイプの保持期間を過ぎると機能しなくなります。

• 古い、または誤ったタスクIDの使用 — たとえば、以前の無関係なリクエストのIDを再利用している。

• FAILED を一時的な状態として扱い、再送信せずに既に失敗したタスクのポーリングを続けている。

• サーバーとMeshyの間のネットワーク/タイムアウトの問題を、生成の問題と誤って解釈している。

生成結果が期待に沿わない場合、またはリクエストが完全に失敗した場合は、以下の点に留意してください。

• Meshy APIは現在、既存のタスクをその場でリトライすることをサポートしていません。再度試すには新しい生成リクエストを送信してください。その場合、クレジットは通常どおり消費されます。

• API呼び出し時の一時的なネットワーク障害（タイムアウト、5xxレスポンス）に対しては、リクエストを再送信する前に短い指数バックオフを挟むのが妥当です。

• ポーリング自体については、一時的なネットワークエラー時に「タスク取得」呼び出しをリトライしてください。ただし、1回のポーリング失敗を生成の失敗として扱わないでください。正常なレスポンスが得られて初めて、status フィールドを信頼してください。

• 生成に対する組み込みのリトライ機能が必要な場合は、エンタープライズプランのオプションについてMeshyの営業チームにお問い合わせください。

これはほとんどの場合、タスクが完了する前に結果を読み取ろうとしているコードが原因です。モデルのURLを取得する前に、必ず status が SUCCEEDED（および progress が100）であることを確認してください。

ポーリングは設定が簡単で、少量の処理や単発のスクリプトには適しています。Webhookは、多数のタスクを同時に処理する本番環境の連携に適しています。不要な繰り返しリクエストを避けられ、タスクの完了時にすぐ通知を受け取れるためです。

冪等に処理してください。タスクの id をすでに処理済みのものと照合し、すでに処理済みであれば再処理をスキップします。

id を指定したポーリングに切り替えて、タスクを直接確認してください。また、エンドポイントがHTTPS経由で公開されて到達可能であり、すばやく2xxレスポンスを返すことも確認してください。応答が遅い、または到達できないエンドポイントは配信に問題を引き起こす可能性があります。

現在はできません。新しい生成リクエストを送信する必要があり、その場合は通常どおりクレジットを消費します。組み込みのリトライ機能が必要な場合は、エンタープライズ向けのオプションについて営業担当者にお問い合わせください。

結果ファイルがMeshyのサーバーに保持されるのはタスク完了後一定期間のみです。そのため、タスクが成功したらすぐに出力を自分のストレージへダウンロードし、待たないようにしてください。