エラー

このガイドでは、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つの明確な主題で最も効果的に動作します。同じ画像や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はテクスチャリングに適したカバレッジを持つことになります。

invalid_input

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

一般的な原因には以下が含まれます：

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

解決策: 何が問題だったのかの詳細については、message フィールドを確認してください。入力ファイルとパラメータがエンドポイントの要件に一致していることを確認してください。

moderation_blocked

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

解決策:

• 示唆的またはセンシティブな記述を削除するために、テキストプロンプトを言い換えてください。
• 安全フィルターを引き起こす可能性のある内容を描写している場合は、参照画像を調整してください。

timeout

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

解決策:

1. リクエストを再試行してください。 タイムアウトは一時的なことが多く、再試行で成功することがあります。
2. 入力を簡素化してください。 再試行が失敗し続ける場合、入力が複雑すぎる可能性があります。画像やプロンプトの詳細レベルを減らしてみてください。処理が難しい入力の種類については、image_too_complexを参照してください。

format_conversion_failed

このエラーは、生成された3Dモデルが要求された出力形式に変換できなかった場合に発生します。モデルは正常に生成されましたが、変換ステップで失敗しました。

解決策:

1. リクエストを再試行してください。
2. 別の出力形式を試してください。 特定の形式が繰り返し失敗する場合は、ニーズに合った別の形式に切り替えてください。

ベストプラクティス

1. リトライロジックを実装する。 timeout および service_unavailable エラーに対して、指数バックオフリトライロジックを実装してください。
2. タスクIDを記録する。 デバッグ目的で常にタスクIDを記録してください。サポートに連絡する際にはそれを含めてください。
3. 入力を検証する。 提出前に、入力画像とモデルが形式要件を満たしていることを確認してください。