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を統合する際に最も重要なルールは、タスクの status が SUCCEEDED になるまで、結果のURLを取得または使用しないことです。タスクがまだ PENDING または IN_PROGRESS の間に結果を読み取ることは、「モデルの取得エラー」報告の最も一般的な原因です。
ポーリングのサンプル
ポーリングとは、タスクIDに対して「タスク取得」エンドポイントを繰り返し呼び出し、終端状態（SUCCEEDED、FAILED、または CANCELED）に達するまで待つことです。シンプルなポーリングループは次のようになります:
生成リクエストを送信し、返されたタスクの
idを保存します。対応する「タスク取得」エンドポイント（例: Text to 3DまたはImage to 3Dのタスクby-idエンドポイント）を一定間隔で呼び出します。通常は数秒間隔です。
各レスポンスの
statusフィールドを確認します。PENDINGまたはIN_PROGRESSの間はポーリングを続けます。statusがSUCCEEDED（結果のURLを読み取る）、FAILED、またはCANCELEDになったらすぐにポーリングを停止します。停止したタスクが永久にポーリングし続けないよう、クライアントに適切なタイムアウト/最大試行回数のガードを追加します。
ポーリングはシンプルで、スクリプト、バッチジョブ、低ボリュームの統合に適しています。高ボリュームやレイテンシが重要な統合には、通常Webhookの方が適しています。
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
"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の営業チームにお問い合わせください。
FAQ
1. API経由で生成結果からモデルを取得する際、なぜ一貫してエラーが発生するのですか？
これはほとんどの場合、タスクが完了する前にコードが結果を読み取ろうとしているために発生します。モデルURLを取得する前に、必ず status が SUCCEEDED（かつ progress が100）であることを確認してください。
2. ポーリングとWebhookのどちらを使うべきですか？
ポーリングは設定がよりシンプルで、低ボリュームや使い捨てのスクリプトに適しています。Webhookは、多くの同時タスクを扱う本番統合に適しています。不要な繰り返しリクエストを避け、タスク完了時に即座に通知できるためです。
3. サーバーが同じWebhookを2回受信した場合、どうすればよいですか？
冪等に処理してください。タスクの id をすでに処理済みのものと照合し、すでに処理されていれば再処理をスキップします。
4. Webhookが届きません — どうすればよいですか？
id でタスクを直接ポーリングすることにフォールバックしてください。また、エンドポイントがHTTPS経由で公開的に到達可能であり、迅速に2xxレスポンスを返すことを確認してください。遅い、または到達不能なエンドポイントは配信の問題を引き起こす可能性があります。
5. 失敗した、または不満足な生成をAPI経由で直接リトライできますか？
現在はできません。新しい生成リクエストを送信する必要があり、通常どおりクレジットを消費します。組み込みのリトライサポートが必要な場合は、エンタープライズオプションについて営業までお問い合わせください。
6. ステータスがSUCCEEDEDになった後、結果をダウンロードできる期間はどのくらいですか？
結果ファイルはタスク完了後、Meshyのサーバー上に限られた期間のみ保持されるため、待機せずにタスクが成功したらすぐにご自身のストレージへ出力をダウンロードしてください。
関連記事