タスクのライフサイクル

タスクがリクエストから結果に至るまでの流れ、通常どのくらいの時間がかかるか、そしてコード側でどれくらい待機すべきかについて学びます。

タスクの実行方法

作成リクエストは、タスクの実行を待たずにタスクIDを返します。その後タスクはバックグラウンドで実行され、次の3つの方法のいずれかで追跡できます。GETエンドポイントをポーリングする、ストリームエンドポイントを開く、またはWebhookを受け取る、のいずれかです。

タスクは各ステップをcreated_at、started_at、finished_atの各フィールドに記録します。

次の表は、各ステータスにおいてコード側で行うべき対応を示しています。

SUCCEEDED、FAILED、CANCELEDは最終状態です。タスクがこれらのいずれかに達した後は、ステータスが再び変化することはありません。

コード側から見ると、次のようになります。

処理時間

次の表は、2026年9月の本番API トラフィックにおける中央値の時間を示しています。

時間はタスク作成から最終ステータスに至るまでをカウントしています。タスクは通常PENDINGの状態に数秒しか留まらないため、ほぼすべての時間は処理に費やされています。キューが混雑している場合、タスクが開始するまでより長く待機することがあり、より高い優先度のプランのタスクは通常より早く開始します。

2分未満の時間は秒(s)で、それより長い時間は分(min)で示されています。「非対応」は、そのモデルではAPIがそのオプションを提供していないことを意味します。

3D生成

画像から3Dおよびマルチ画像から3Dにおいて、「メッシュのみ」はshould_texture: falseを意味します。次のオプションおよび入力は所要時間に影響します。

• PBRマップ（enable_pbr）は30から60秒を追加します。
• 高解像度ジオメトリ（geometry_resolution: "2k"または"4k"）は最大1分を追加します。
• 同じ設定の場合、より複雑な入力画像ほど時間がかかります。

テクスチャリング

画像生成

リギングとアニメーション

後処理

3Dプリント

v2では、プリント可能性を修復とプリント可能性を分析は常に薄肉チェックを実行します。v1では、プリンタータイプまたはプリントサイズを送信した場合にのみこれを実行します。

待機時間の目安

コード側が待機を停止しても、タスクは実行を続けます。リクエストがtimeoutになったり、接続が切断されたり、ストリームが閉じたりしても、タスクが失敗したりキャンセルされたりすることはありません。

• タスクのcreated_atから数えて、少なくとも60分は待機してから待機を停止してください。それより早く停止すると、後で成功するタスクを見逃す可能性があります。これは主に混雑時に発生します。
• タスクIDを保持してください。タスクはいつでも再取得できます。60分経っても最終状態になっていない場合は、後でもう一度確認してください。その状態が続く場合は、サポートにお問い合わせください。
• タスクが失敗したことを意味するのはFAILEDのみです。Meshyは失敗したタスクを自動的に返金します。

コード内では、次の値を使用してください。

多数のタスクを同時に扱う場合は、それぞれをポーリングする代わりにWebhooksを使用してください。タスクの最終イベントが、その典型的な時間の約2倍を経過しても届かない場合は、GETエンドポイントからタスクを取得してください。