タスクのライフサイクル
タスクがリクエストから結果に至るまでどのように進行するか、通常どのくらい時間がかかるか、そしてコードがどのくらい待機すべきかについて説明します。
タスクの実行の流れ
作成リクエストは、タスクの実行を待たずにタスクIDを返します。その後タスクはバックグラウンドで実行され、GETエンドポイントをポーリングする、ストリームエンドポイントを開く、またはwebhookを受け取るという3つの方法のいずれかで進行状況を追跡できます。
PENDING状態でタスクを開始します。ワーカーがタスクを取得するとIN_PROGRESSに移行し、タスクはほとんどの時間をこの状態で過ごします。最終的にSUCCEEDEDまたはFAILEDで終了し、最終ステータスはその後変化しません。PENDINGIN_PROGRESSSUCCEEDEDFAILEDタスクは各ステップをcreated_at、started_at、finished_atの各フィールドに記録します。
次の表は、各ステータスにおいてコードが行うべき動作を示しています。
| ステータス | コードが行うべきこと |
|---|---|
PENDING | 待機を続けます。 |
IN_PROGRESS | progressを追跡します。これは作業がどのくらい完了したかを示す0から100のパーセンテージです。 |
SUCCEEDED | 結果をダウンロードします。Meshyはファイルを一定期間のみ保持します。アセット保持期間を参照してください。 |
FAILED | task_errorを読み取り、入力を修正するか新しいタスクを作成してください。エラーを参照してください。 |
CANCELED | 待機を中止してください。タスクは結果を生成しません。このステータスはCreative Labのタスクでのみ使用されます。 |
SUCCEEDED、FAILED、CANCELEDは最終状態です。タスクがこれらのいずれかに達すると、そのステータスはそれ以降変化しません。
コードの視点から見ると、次のようになります。
リクエスト: POST/image-to-3d
レスポンス: 202{ "result": "<task_id>" }タスク作成完了
- 数秒ごとに繰り返し
リクエスト: GET/image-to-3d/<task_id>
レスポンス: 200{ "status": "IN_PROGRESS","progress": 45 }Retry-After: 5
リクエスト: GET/image-to-3d/<task_id>
レスポンス: 200{ "status": "SUCCEEDED","model_urls": { "glb": "…" } }
GETしてください。処理時間
次の表は、2026年9月の本番API トラフィックにおける中央値の処理時間を示しています。
処理時間はタスク作成から最終ステータスに至るまでの時間です。タスクは通常数秒間しかPENDINGのままにならないため、そのほとんどは処理時間です。キューが混雑している場合、タスクが開始するまでにより長く待機することがあり、より高い優先度のプランのタスクは通常より早く開始されます。
2分未満の時間は秒(s)で、それより長い時間は分(min)で表記されています。「非対応」は、そのモデルでAPIがそのオプションを提供していないことを意味します。
3D生成
| API | 設定 | meshy-7.1(latest) | meshy-6 | meshy-6-lite | meshy-t2 |
|---|---|---|---|---|---|
| テキストから3D (Preview) | メッシュのみ | 75秒 | 90秒 | 45秒 | 10秒 |
| 画像から3D | メッシュのみ | 75秒 | 90秒 | 40秒 | 4秒 |
| 2Kテクスチャ付きメッシュ | 2分 | 3分 | 75秒 | 60秒 | |
| 4Kテクスチャ付きメッシュ | 2.5分 | 3.5分 | 非対応 | 80秒 | |
| 8Kテクスチャ付きメッシュ | 3.5分 | 4分 | 非対応 | 2.5分 | |
| マルチ画像から3D | メッシュのみ | 65秒 | 2分 | 30秒 | 非対応 |
| 2Kテクスチャ付きメッシュ | 2.5分 | 3.5分 | 85秒 | 非対応 | |
| 4Kテクスチャ付きメッシュ | 3分 | 4分 | 非対応 | 非対応 | |
| 8Kテクスチャ付きメッシュ | 3.5分 | 4.5分 | 非対応 | 非対応 |
画像から3Dおよびマルチ画像から3Dにおいて、「メッシュのみ」はshould_texture: falseを意味します。以下のオプションと入力は処理時間に影響します。
- PBRマップ(
enable_pbr)は30~60秒を追加します。 - Ultraジオメトリ(
geometry_resolution: "2k"または"4k")は最大1分を追加します。 - 同じ設定でも、より複雑な入力画像は処理に時間がかかります。
テクスチャ生成
| API | テクスチャ解像度 | 典型的な処理時間 |
|---|---|---|
| テキストから3D (Refine) | 2Kまたは4K | 80秒 |
| 8K | 3.5分 | |
| リテクスチャ | 2K | 55秒 |
| 4K | 90秒 | |
| 8K | 2.5分 |
画像生成
リギングとアニメーション
| API | 設定 | 典型的な処理時間 |
|---|---|---|
| 自動リギング | 自動リギング | 40秒 |
| アニメーション | リクエストごと | 15秒 |
| テキストからモーション | prime mode | 15秒 |
swift mode | 10秒 |
後処理
3Dプリント
| API | 設定 | 典型的な処理時間 |
|---|---|---|
| プリント可能性を分析 | メッシュチェックのみ | 1秒 |
| メッシュと薄肉チェック | 10秒 | |
| マルチカラー | リクエストごと | 30秒 |
| プリント可能性を修復 | メッシュ修復のみ | 10秒 |
| 薄肉チェック、壁を維持 | 20秒 | |
| 薄肉チェック、壁を厚肉化 | 100秒 | |
| Auto Split | 単色パーツ | 70秒 |
テクスチャ付きパーツ(keep_texture: true) | 170秒 |
v2では、プリント可能性を修復とプリント可能性を分析は常に薄肉チェックを実行します。v1では、プリンタータイプまたはプリントサイズを送信した場合にのみ実行されます。
待機すべき時間
あなたのコードが待機を中止しても、タスクは実行を続けます。リクエストがtimeoutになったり、接続が切れたり、ストリームが閉じたりしても、タスクは失敗したりキャンセルされたりしません。
- タスクの
created_atから数えて、少なくとも60分間は待機を続けてから待機を中止してください。早く中止すると、後で成功するタスクを見逃す可能性があります。これは主に混雑時に発生します。 - タスクIDを保持してください。いつでもタスクを再度取得できます。60分経過しても最終状態になっていない場合は、後でもう一度確認してください。それでも状態が変わらない場合は、サポートにお問い合わせください。
- タスクが失敗したことを意味するのは
FAILEDのみです。Meshyは失敗したタスクを自動的に返還します。
コードでは以下の値を使用してください。
| 設定 | 推奨値 |
|---|---|
作成リクエスト(POST)のtimeout | 60秒 |
100MBを超えるmodel_urlファイルを伴う作成リクエスト(POST)のtimeout | 120秒。Meshyはレスポンスを返す前にファイルをダウンロードします。 |
ステータスリクエスト(GET)のtimeout | 30秒 |
| ポーリング間隔 | Retry-Afterヘッダーの値、なければ5秒。ポーリングはレート制限にカウントされます。 |
失敗したステータスリクエスト(timeout、429、または5xx) | 次のポーリングで再試行してください。タスクが失敗したことを意味するわけではありません。 |
| タスクごとの合計待機時間 | created_atから少なくとも60分。ストリームを再接続してもこのカウントをリセットしないでください。 |
| ストリーム | ストリームはタスクが完了する前に閉じることがあります。最終ステータスを受け取らずに閉じた場合は、再接続するかポーリングに切り替えてください。 |
多数のタスクを同時に扱う場合は、個々にポーリングする代わりにwebhooksを使用してください。タスクの最終イベントが、その典型的な処理時間の約2倍を経過しても届かない場合は、GETエンドポイントからタスクを取得してください。