エラー

リクエストやタスクが失敗した理由と、次に何をすべきかを確認できます。リクエストはHTTPエラーによってすぐに失敗することがあり、タスクは後からtask_errorによって失敗することがあります。

リクエストエラー

Meshyはリクエストを拒否する際、これらのエラーを即座に返します。何が問題だったかを調べるには、HTTPステータスコードとmessageフィールドを確認してください。

{
  "message": "Invalid model file extension: .3dm"
}

タスクエラー

Meshy が作成したタスクでも、実行中に失敗することがあります。その場合、status は FAILED になり、Meshy はクレジットを返金し、task_error にその理由が示されます。

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "invalid_input",
    "code": "image_too_complex",
    "message": "The uploaded image is too complex for 3D generation.",
    "doc_url": "https://docs.meshy.ai/en/api/errors#image-too-complex"
  }
}

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

エラータイプ

type は失敗の大まかなカテゴリです。次に何をすべきかを判断するために使用してください。

エラーコード

code が存在する場合、それは以下の問題のいずれかを示しています。

image_too_complex

入力画像または prompt が、3D生成には幾何学的に複雑すぎる被写体を表しています。

例えば：

• 果物でいっぱいの木箱や本の山のような、小さな物体が密集した集合
• 格子構造、足場、ワイヤーメッシュのような、複雑な繰り返しパターン
• 窓やバルコニーが多数ある高層ビルのような、複雑な建築物
• 1つの被写体ではなく、1枚の画像に複数の異なる物体が含まれている場合

以下のような入力はおそらく複雑すぎます：

これを解決するには、以下のいずれか、または複数の対策を試してください：

• 画像1枚につき1つの物体を使用してください。Meshy は明確な被写体が1つであるときに最も効果を発揮するため、複数の独立した物体を同じ画像や prompt に含めないでください。
• 被写体をシンプルにしてください。例えば、何十本もの花で埋め尽くされた花瓶ではなく、シンプルな花瓶を使用してください。
• シーンを避けてください。建物全体、街区、家具付きの部屋、風景などはおそらく複雑すぎます。単一の物体に焦点を当ててください。
• 密集した繰り返し構造を避けてください。足場、ワイヤーメッシュ、格子、小さな物体の山などは、よくある原因です。

model_missing_uv

enable_original_uvをtrueに設定してテクスチャリング用のモデルを送信しましたが、モデルにUV座標がありません。UV座標は、2Dテクスチャが3Dサーフェスにどのようにラップされるかを定義します。

これを修正するには、以下のいずれかを行ってください。

• モデル独自のUVレイアウトを維持したい場合（例えばカスタムのシーム配置のため）、3DソフトウェアでモデルにUVを追加してください。そのUVエディターで確認してから、モデルを再度アップロードしてください。STLファイルはUVを保存できないため、GLB、FBX、またはOBJを使用してください。
• 独自のレイアウトが不要な場合、またはよくわからない場合は、enable_original_uvを省略するかfalseに設定してください。すると、MeshyがモデルのUVレイアウトを作成します。新しいUVはモデルをうまくカバーしますが、テクスチャのシームがどこに配置されるかは制御できません。

model_insufficient_uv

モデルにはUV座標がありますが、UV空間に占める割合が小さすぎるため、適切にテクスチャを適用できません。これは、エクスポーターが適切なアンラップを行わずにプレースホルダーや潰れたUVを書き出したモデルでよく発生します。

これを修正するには、次のいずれかを行ってください。

• 独自のUVレイアウトを維持したい場合は、3Dソフトウェアでモデルのアンラップを再度行ってください。UV空間の小さな一角にまとめるのではなく、アイランドをUV空間全体に広げてください。
• 独自のレイアウトが不要な場合は、enable_original_uv を指定しないか、false に設定してください。すると、Meshyが新しいUVレイアウトを作成します。この場合、シームの配置は失われますが、新しいUVはテクスチャを適用するのに十分な領域をカバーします。

model_missing_texture

Multi-Color Print タスクの入力モデルに、Meshy がプリントカラーに分割できる色がありません。Meshy はモデルの色から多色 3MF を構築するため、無地の白いメッシュでは処理のしようがありません。例えば、一度もテクスチャ生成されていない Text to 3D や Image to 3D のプレビューには色がありません。プリント可能性を修復の出力や、テクスチャを保持しなかった Auto Split タスクも同様です。

何が色として扱われるかは、リクエストした style によって異なります。

• realistic はベースカラーテクスチャをモデルの UV 経由でサンプリングします。単一のベースカラーテクスチャと、すべてのメッシュパーツに UV が必要です。
• cartoon はフェースごとに色を平坦化します。任意のパーツのベースカラーテクスチャ、または頂点ごとの色（COLOR_0）を受け付けます。

Meshy は、ベースカラーテクスチャも頂点カラーも持たないモデルを、両方のスタイルで拒否します。cartoon によって単色プリントに変換させることはしません。

Meshy はこれらのリクエストのほとんどを、タスクを作成する前に 400 と同じ説明で拒否します。このコードが返ってくるのは通常、Meshy が事前に入力をチェックできない場合に限られます。例えば、Meshy は .fbx のアップロードを、タスクがそれを変換した後にのみチェックします。

修正するには、モデルに合ったオプションを使用してください。

• まずモデルにテクスチャを生成します。Retexture を実行するか、Text to 3D の refine タスク、または should_texture: true を指定した Image to 3D タスクで生成します。その上で、そのタスクを input_task_id として送信してください。
• フォトグラメトリスキャンや手描きのメッシュなど、頂点カラー付きのモデルには style: "cartoon" を使用します。これは COLOR_0 を読み取ります。
• realistic で部分的にテクスチャ生成されたモデルや、複数テクスチャを持つモデルの場合は、すべてのメッシュパーツに UV を付与し、同一の単一ベースカラーテクスチャを与えてください。そのためには、残りのパーツにテクスチャを生成するか、テクスチャを1つのアトラスに統合します。style: "cartoon" に切り替えることもできます。

textured_split_refused

keep_texture: true を指定したAuto Splitタスクが、入力モデルのテクスチャをパーツに維持できません。たとえば、モデルにUVが存在しない場合や、カットによって新しく生成される面を収めるためのテクスチャの余白がない場合です。Meshyはクレジットを返金します。

これを解決するには、keep_texture を指定せずにリクエストを再送信するか、keep_texture: false を指定して再送信してください。その場合、各パーツは単色で返されます。

invalid_input

入力がチェックに失敗し、他に該当する特定のコードがない場合です。理由は message に示されます。

例：

• 空のモデルファイル、または破損したモデルファイル
• ファイル形式のサポート対象外のバリアント（ASCII形式のFBXファイルや、meshopt圧縮されたGLBファイルなど）
• 有効な3Dオブジェクトを含まないアップロードモデル（アーマチュア、カメラ、ライトのみを含むファイルなど）
• 安全フィルターを通過しないコンテンツ

これを解決するには、具体的な問題については message を確認してください。入力ファイルとパラメータが、そのエンドポイントの要件を満たしているか確認してください。

moderation_blocked

安全フィルターがprompt、または参照画像を拒否しました。フィルターはテキストと画像をまとめてチェックします。

修正するには、以下のいずれか、または両方を行ってください。

• 示唆的または不適切な表現をprompt から削除するよう書き直してください。
• フィルターがブロックする可能性のある内容が映っている参照画像を変更してください。

moderation_unavailable

種類: server_error。コンテンツのmoderation が一時的に利用できなかったため、Meshy はチェックをスキップせずタスクを失敗（FAILED）させました。あなたのコンテンツには問題ありません。

修正するには、タスクを再度作成してください。

timeout

タスクがサーバー側の時間制限（処理中またはキュー待機中）を超過したため、Meshy はタスクを失敗とし、クレジットを返金しました。高負荷、または時間内に処理しきれないほど複雑な入力が原因となることがあります。

これは、お客様自身のコード側で発生する timeout とは異なります。クライアント側が待機を停止した場合でも、タスク自体は実行され続けています。How long to wait を参照してください。

解決するには、以下の手順に従ってください。

1. タスクを再度作成してください。timeout は一時的な場合が多く、新しいタスクでは成功することがあります。
2. それでも失敗し続ける場合は、入力を簡略化してください。例えば、画像や prompt の詳細さを減らしてみてください。処理が難しい入力については、image_too_complex を参照してください。

queue_timeout

タイプ：timeout。タスクがキュー内で待機しすぎて開始されなかったため、Meshy はタスクを失敗として処理し、課金されたクレジットを返却しました。この問題はお客様の入力が原因ではありません。

解決するには、タスクを再作成してください。

format_conversion_failed

Meshy はモデルの生成には成功しましたが、リクエストされた形式への変換に失敗しました。

解決するには、以下の手順に従ってください。

1. タスクを再作成する。
2. 特定の形式で失敗が繰り返される場合は、ご要望に合った別の形式をリクエストしてください。

ベストプラクティス

• 失敗したタスクはリトライしてください。timeout、service_unavailable、server_errorのいずれかで失敗したタスクについては、指数バックオフを用いて新しいタスクを作成してください。
• 自分のリクエストがタイムアウトした場合でも、新しいタスクを作成しないでください。最初のタスクがまだ実行中である可能性があるため、別のタスクを作成する前に、それが存在するかどうかを確認してください。どのくらい待つべきかを参照してください。
• タスクIDを記録してください。サポートに連絡する際はIDを含めてください。
• 送信前に入力内容を確認してください。画像やモデルがエンドポイントの形式要件を満たしていることを確認してください。
• APIはご自身のサーバーから呼び出してください。ブラウザで実行されるコードは、ページを開いた誰にでもAPIキーを公開してしまいます。