エラー

このガイドでは、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. scene レベルの 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のカバー率が低すぎて高品質なテクスチャリングができない場合に発生します。これは、適切な展開(unwrap)を行わずにプレースホルダー的なUVや潰れたUVを生成する3Dツールからエクスポートされたモデルでよく見られます。

解決方法:

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

model_missing_texture

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

何が色の情報源として認められるかは、リクエストした style によって異なります。

• realistic はモデルのUVを通じてベースカラーテクスチャをサンプリングするため、すべてのメッシュパーツにUV座標が設定された単一のベースカラーテクスチャが必要です。
• cartoon は面ごとに色をフラット化し、任意のパーツ上のベースカラーテクスチャまたは頂点ごとの色（COLOR_0）を受け付けます。

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

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

解決方法：

• 先にモデルにテクスチャを付与してください。 モデルに対してRetextureタスクを実行するか、テクスチャ生成を有効にして生成してください（Text to 3Dのrefineタスク、または should_texture: true を指定したImage to 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、または server_error エラーで失敗した場合は、指数バックオフを用いて再度作成してください。自分のリクエスト自体がタイムアウトした場合は、新しいタスクを作成するのではなく、まず既存のタスクを確認してください（タスクのライフサイクルを参照）。
2. タスクIDを記録してください。 デバッグ目的のため、常にタスクIDを記録してください。サポートに問い合わせる際は必ず含めてください。
3. 入力を検証してください。 送信前に、入力画像やモデルがフォーマット要件を満たしていることを確認してください。