エラー

このガイドでは、Meshy API を使用している際に問題が発生した場合に何が起こるかについて説明します。

リクエストエラー

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

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

タスクエラー

これらのエラーは、タスクが作成されて処理が行われた後に発生します。エラーの詳細については、タスクレスポンスの 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つの物体を使用してください。 モデルは、明確な被写体が1つある場合に最も良く機能します。同じ画像や prompt に複数の別々の物体を含めないでください。
2. 被写体をシンプルにしてください。 詳細のレベルを減らしてください。例えば、何十本もの花で満たされた花瓶ではなく、シンプルな花瓶にします。
3. シーンレベルの prompt は避けてください。 建物全体、街区、家具でいっぱいの室内、風景などは、モデルの処理能力を超える可能性が高いです。代わりに単一の物体に焦点を当ててください。
4. 密集した繰り返し構造は避けてください。 足場、ワイヤーメッシュ、格子パターン、多数の小さな物のまとまりなどの被写体は、よくある原因となります。

model_missing_uv

このエラーは、enable_original_uv を true に設定してテクスチャリング用にモデルをアップロードしたにもかかわらず、そのモデルにUV座標が存在しない場合に発生します。UV座標は、2Dテクスチャがモデルの3Dサーフェスにどのようにラップされるかを定義します。

解決方法:

正しい対処法は、なぜ enable_original_uv を true に設定したかによって異なります。

• モデル本来のUVレイアウトを維持する必要がある場合（例：精密なテクスチャマッピングのためのカスタムシーム配置など）：モデルには有効なUV座標が必要です。アップロードする前に、お使いの3DソフトウェアのUVエディターでUVが存在することを確認してください。なお、STLファイルはUVデータを保存できないため、代わりにGLB、FBX、またはOBJを使用してください。
• 特定のUV制御が不要な場合（またはよく分からない場合）：enable_original_uv を省略するか、false に設定してください。システムがモデル用のUVレイアウトを自動生成します。自動生成されたUVはカバレッジ重視で最適化されますが、テクスチャのシームがどこに配置されるかを制御することはできません。

model_insufficient_uv

このエラーは、モデルにUV座標は存在するものの、UVカバレッジが小さすぎて高品質なテクスチャリングができない場合に発生します。これは、適切な展開を行わずにプレースホルダー用または潰れたUVを生成する3Dツールからエクスポートされたモデルでよく見られます。

解決方法:

• 元のUVレイアウトを維持する必要がある場合: ご使用の3DソフトウェアでモデルのUVを再展開してください。UVアイランドが小さな領域に潰れるのではなく、UV空間全体に適切に広がるようにしてください。
• 特定のUV制御が不要な場合: enable_original_uv を省略するか、false に設定してください。システムが自動的に新しいUVレイアウトを生成します。トレードオフとして元のシーム配置は失われますが、自動生成されるUVはテクスチャリングに適した十分なカバレッジを持ちます。

model_missing_texture

このエラーは、Multi-Color Print タスクの入力モデルに、コンバータがプリントカラーへ分離できる色情報が存在しない場合に発生します。多色3MFはモデルの色情報から構築されるため、テクスチャが一切設定されていない真っ白なメッシュ——たとえばテクスチャ生成前のText to 3Dやテキストから3Dのプレビュー、あるいは修復済み／自動分割された出力——には元にできる情報がありません。

何が色情報として認められるかは、指定した style によって異なります。

• realistic はモデルのUV座標を通じてベースカラーテクスチャをサンプリングするため、すべてのメッシュパーツに対してUV座標を持つ単一のベースカラーテクスチャが必要です。
• cartoon は面ごとに色を平坦化するため、いずれかのパーツにベースカラーテクスチャがあるか、頂点ごとの色（COLOR_0）があれば受け付けます。

ベースカラーテクスチャも頂点カラーも持たないモデルは、どちらのスタイルでも拒否されます。そうしないと cartoon の場合、単色プリントとして「成功」してしまうためです。

ほとんどのリクエストはタスク作成前に拒否されます（同じ説明とともに 400 Bad Request が返されます）。そのため、このコードが表示されるのは通常、入力を事前に検査できなかった場合——たとえば .fbx のアップロードは、タスクが正規化された後にチェックされる場合——に限られます。

解決方法：

• 先にモデルにテクスチャを適用してください。 そのモデルに対してリテクスチャタスクを実行するか、テクスチャ生成を有効にして生成してください（テキストから3Dのrefineタスク、または should_texture: true を指定した画像から3Dタスク）。そのタスクを input_task_id として渡してください。
• 頂点カラーが設定されたモデル（フォトグラメトリスキャン、手作業で彩色されたメッシュ）の場合：style: "cartoon" を指定してください。この場合 COLOR_0 が読み取られます。
• realistic において部分的にしかテクスチャが適用されていない、または複数テクスチャを持つモデルの場合：すべてのメッシュパーツにUV座標が必要であり、同一の単一ベースカラーテクスチャを使用する必要があります。残りのパーツにテクスチャを適用するか、テクスチャを1枚のアトラスに統合するか、style: "cartoon" に切り替えてください。

invalid_input

これは、入力が検証に失敗したものの、より具体的なコードが該当しない場合のフォールバックエラーコードです。messageフィールドには、失敗の具体的な理由が含まれます。

一般的な原因は以下の通りです：

• 空または破損したモデルファイル
• サポートされていないファイル形式のバリエーション（例：ASCII FBXファイル、meshopt圧縮されたGLB）
• アップロードされたモデル内に有効な3Dオブジェクトが見つからない（例：ファイルにアーマチュア、カメラ、ライトのみが含まれている）
• 安全フィルターを通過しないコンテンツ

解決方法： messageフィールドで、何が問題だったのか詳細を確認してください。入力ファイルとパラメータがエンドポイントの要件を満たしているか確認してください。

moderation_blocked

このエラーは、prompt または参照画像がAI安全フィルターによって拒否された場合に発生します。フィルターはテキストの prompt と参照画像の両方を合わせて評価します。

解決方法:

• 示唆的または機微な表現を取り除くよう、テキストの prompt を修正してください。
• 安全フィルターを誘発する可能性のある内容が写っている場合は、参照画像を調整してください。

timeout

このエラーは、タスクの処理時間が許容制限を超えたことを意味します。これはシステムの負荷が高い場合や、入力が複雑すぎて制限時間内に処理できない場合に発生することがあります。

解決方法:

1. リクエストを再試行する。 timeout は一時的なものであることが多く、再試行によって成功する場合があります。
2. 入力を簡略化する。 再試行を繰り返しても失敗し続ける場合、入力が複雑すぎる可能性があります。画像や prompt の詳細度を下げてみてください。どのような種類の入力が処理しづらいかについては、image_too_complex を参照してください。

format_conversion_failed

このエラーは、生成された3Dモデルをリクエストされた出力フォーマットに変換できなかった場合に発生します。モデル自体の生成は成功していますが、変換ステップで失敗しています。

解決方法:

1. リクエストを再試行してください。
2. 別の出力フォーマットを試してください。 特定のフォーマットで失敗が続く場合は、要件に合った別のフォーマットに切り替えてください。

ベストプラクティス

1. リトライロジックを実装する。 timeout および service_unavailable エラーについては、指数バックオフによるリトライロジックを実装してください。
2. タスクIDを記録する。 デバッグのために、常にタスクIDをログに記録してください。サポートに問い合わせる際にはこのIDを含めてください。
3. 入力を検証する。 送信前に、入力画像やモデルがフォーマット要件を満たしていることを確認してください。