エラー

このガイドでは、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

このエラーは、入力画像またはプロンプトが、3D生成モデルで処理するには幾何学的に複雑すぎる被写体を記述している場合に発生します。

一般的な例は次のとおりです。

• 小さな物体が密集した山（例: 果物でいっぱいの木箱、本の山）
• 複雑な反復パターン（例: 格子構造、足場、ワイヤーメッシュ）
• 複雑な建築構造（例: 多数の窓やバルコニーがある複数階の建物）
• 単一の被写体ではなく、1枚の画像内に複数の異なる物体がある場合

複雑すぎる可能性が高い入力の例:

解決方法:

1. 画像ごとに単一のオブジェクトを使用してください。 モデルは、明確な被写体が1つだけある場合に最もよく機能します。同じ画像またはプロンプトに複数の別々のオブジェクトを含めないでください。
2. 被写体を単純化してください。 詳細度を下げます。たとえば、何十本もの花が入った花瓶ではなく、シンプルな花瓶にします。
3. シーンレベルのプロンプトは避けてください。 建物全体、街区、家具で埋め尽くされた室内、または風景は、モデルの容量を超える可能性があります。代わりに単一のオブジェクトに焦点を当ててください。
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 フィールドを確認してください。入力ファイルとパラメータが endpoint の要件に一致していることを確認してください。

moderation_blocked

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

解決方法:

• 示唆的またはセンシティブな説明を取り除くように、テキストプロンプトを言い換えてください。
• 安全性フィルターを作動させる可能性のあるコンテンツが含まれている場合は、参照画像を調整してください。

timeout

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

解決方法:

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

format_conversion_failed

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

解決方法:

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

ベストプラクティス

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