エラー
リクエストやタスクが失敗した理由と、その対処方法について説明します。リクエストはHTTPエラーによってすぐに失敗することもあれば、タスクは後になって task_error によって失敗することもあります。
リクエストエラー
Meshyはリクエストを拒否する際、これらのエラーを即座に返します。何が問題だったかを確認するには、HTTPステータスコードとmessageフィールドをチェックしてください。
レスポンス形式
エラーレスポンスには、何が問題だったかを説明するmessageフィールドがあります:
- Name
- message
- Type
- string
- Description
エラーの簡単な説明。
ステータスコード
- Name
2xx- Description
成功。
- Name
200 - OK- Description
リクエストは正常に処理されました。
- Name
202 - Accepted- Description
Meshyはリクエストを受け付けましたが、処理はまだ完了していません。例えば、タスクを作成する リクエストは
202を返します。
- Name
4xx- Description
リクエストまたはアカウントに問題があります。各ステータスには対処方法が記載されています。
- Name
400 - Bad Request- Description
リクエストが無効です。多くの場合、必須のパラメータが欠けているか、パラメータの形式が 不正です。
- Name
401 - Unauthorized- Description
APIキーが見つからないか、無効であるか、このエンドポイントにアクセスできません。認証を参照してください。
- Name
402 - Payment Required- Description
APIキーのアカウントには、リクエストに必要なクレジットが不足しています。無料プランでは、 タスクを作成するほとんどのリクエストも
402を返します。
- Name
403 - Forbidden- Description
このリクエストを行う権限がありません。例えば、以下のいずれかの理由が考えられます:
- リクエストがAPIキーのIP許可リスト外のアドレスから送信された。
- タスクを読み取る際に、組織のIPフィルタリングによってタスクのファイルがブロックされた。
- エンドポイントがご利用のプランでは利用できない。
- コンテンツmoderationが入力をブロックした。一部のエンドポイントではこの場合
400を返すため、各エンドポイントのページでそのコードを確認してください。 - APIキーが、チームで既にアクティブでなくなったメンバーに属している。
- アカウントが禁止されている。
- Name
404 - Not Found- Description
リソースが存在しません。例えば、存在しないIDでタスクを取得しようとすると
404が返されます。
- Name
409 - Conflict- Description
リソースは存在しますが、その状態では操作が許可されていません。例えば、
IN_PROGRESSの タスクを削除しようとすると409が返されます。これは、ワーカーが開始したタスクをMeshyが 払い戻しできないためです。タスクは実行され続けます。最終的なステータス(SUCCEEDED、FAILED、 またはCANCELED)になるまで待ってから、タスクを削除してください。
- Name
422 - Unprocessable Entity- Description
リクエストは有効ですが、Meshyはその入力を処理できません。例えば、Riggingは モデル内にヒューマノイドの身体を見つけられない場合に
422を返します。
- Name
429 - Too Many Requests- Description
リクエストを送信しすぎたか、キューに入っている、または実行中のタスクが多すぎます。 レスポンスに
Retry-Afterヘッダーがある場合は、その秒数だけ待ってから再試行してください。 レート制限を参照してください。
Example: 400 Bad Request
{
"message": "Invalid model file extension: .3dm"
}
タスクエラー
Meshy が作成したタスクは、実行中に失敗することがあります。その場合、status は FAILED になり、Meshy はクレジットを払い戻し、task_error にその理由が示されます。
失敗したタスクの task_error には、次のフィールドがあります。
- Name
- type
- Type
- string
- Description
エラーのカテゴリです。失敗したタスクには必ず存在します。これに応じて再試行するかどうかを判断してください。エラータイプ を参照してください。
- Name
- message
- Type
- string
- Description
エラーの内容を人間が読める形で説明したものです。失敗したタスクには必ず存在します。
- Name
- code
- Type
- string
- 任意
- Description
対処可能な、具体的かつドキュメント化された問題です。Meshy がより詳しい情報を持っている場合に存在します。エラーコード を参照してください。Meshy は今後コードを追加する可能性があるため、認識できないコードについてはその
typeに基づいて処理してください。
- Name
- doc_url
- Type
- string
- 任意
- Description
このページ内の該当コードの項目へのリンクで、対処方法が記載されています。
codeが存在する場合に存在します。
Error with details
{
"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"
}
}
Error without details
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "FAILED",
"task_error": {
"type": "server_error",
"message": "An internal error occurred. Please retry."
}
}
エラータイプ
type は失敗の大まかなカテゴリーです。これを使って次に何をすべきかを判断してください。
- Name
invalid_input- Description
送信した入力に問題があります。
codeとmessageを確認して入力を修正し、新しいタスクを作成してください。
- Name
timeout- Description
タスクが処理またはキュー待機に関するサーバー側の時間制限を超えて失敗しました。Meshy はクレジットを払い戻します。これは一時的なものであることが多いです。タスクを再作成し、それでも失敗し続ける場合は、よりシンプルな入力を試してください。
- Name
service_unavailable- Description
サービスが一時的に利用できませんでした。しばらく待ってから、タスクを再作成してください。
- Name
server_error- Description
タスクの実行中に Meshy 側で問題が発生しました。タスクを再作成してください。それでも失敗し続ける場合は、タスク ID を添えてサポートにお問い合わせください。
エラーコード
code が存在する場合、それは以下の問題のいずれかを示します。
image_too_complex
入力画像または prompt が、3D 生成には幾何学的に複雑すぎる被写体を表しています。
例えば:
- 果物でいっぱいの木箱や積み重なった本のような、小さな物体が密集した山
- 格子構造、足場、ワイヤーメッシュなど、複雑な繰り返しパターン
- 窓やバルコニーが多数ある高層建築など、複雑な建物
- 単一の被写体ではなく、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
多色プリントタスクの入力モデルに、Meshyがプリントカラーに分割できる色が存在しません。Meshyはモデルの色から多色3MFを生成するため、単色の白いメッシュには処理対象となる素材がありません。例えば、一度もテクスチャ付けされていないテキストから3Dや画像から3Dのプレビューには色がありません。プリント可能性を修復の出力や、テクスチャを保持しなかったAuto Splitタスクも同様です。
何を色とみなすかは、リクエストしたstyleによって異なります。
realisticはモデルのUVを通じてベースカラーテクスチャをサンプリングします。単一のベースカラーテクスチャと、すべてのメッシュパーツにUVが必要です。cartoonは面ごとに色をフラット化します。任意のパーツのベースカラーテクスチャ、または頂点ごとの色(COLOR_0)を受け付けます。
Meshyは、ベースカラーテクスチャも頂点カラーも持たないモデルを、両方のスタイルで拒否します。cartoonがそれを単色プリントに変換してしまうことは許されません。
Meshyはこれらのリクエストのほとんどを、タスクを作成する前に400と同じ説明文で拒否します。このコードが返されるのは通常、Meshyが事前に入力を確認できない場合のみです。例えば、Meshyは.fbxアップロードを、タスクがそれを変換した後にのみチェックします。
修正するには、モデルに合ったオプションを使用してください。
- まずモデルにテクスチャを付けます。リテクスチャを実行するか、テキストから3Dのrefineタスク、または
should_texture: trueを指定した画像から3Dタスクで生成してください。そのうえで、そのタスクをinput_task_idとして送信します。 - フォトグラメトリスキャンや手作業で色付けされたメッシュなど、頂点カラー付きモデルの場合は、
COLOR_0を読み取るstyle: "cartoon"を使用してください。 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 はチェックをスキップする代わりにタスクを失敗させました。あなたのコンテンツ自体には問題はありません。
修正するには、タスクを再度作成してください。
timeout
タスクがサーバー側の時間制限(処理待ちまたはキュー待ちの時間制限)を超えて実行されたため、Meshyはそのタスクを失敗とし、クレジットを返金しました。高負荷や、時間内に処理しきれないほど複雑な入力が原因となることがあります。
これは、お客様自身のコード側で発生するtimeoutとは異なります。クライアントが待機を停止した場合でも、タスクは引き続き実行されています。どのくらい待てばよいかを参照してください。
これを解決するには、以下の手順に従ってください。
- タスクを再作成してください。timeoutは一時的な場合が多く、新しいタスクであれば成功する可能性があります。
- それでも失敗が続く場合は、画像やpromptの詳細を減らすなどして、入力を簡略化してください。処理がより困難な入力については、
image_too_complexを参照してください。
queue_timeout
タイプ: timeout。タスクがキューで待機している時間が長すぎて開始できなかったため、Meshy はこれを失敗として処理し、タスクに対して請求されたクレジットを返却しました。このエラーはお客様の入力が原因で発生したものではありません。
これを解決するには、タスクを再作成してください。
format_conversion_failed
Meshy はモデルを生成しましたが、リクエストされた形式への変換に失敗しました。
これを解決するには、以下の手順に従ってください。
- タスクを再作成します。
- 特定の形式が繰り返し失敗する場合は、ニーズに合った別の形式をリクエストしてください。
ベストプラクティス
- 失敗したタスクはリトライしてください。
timeout、service_unavailable、server_errorで失敗したタスクについては、指数バックオフを用いて新しいタスクを作成してください。 - 自分自身のリクエストがタイムアウトしても、新しいタスクを作成しないでください。最初のタスクがまだ実行中である可能性があるため、別のタスクを作成する前に存在するかどうかを確認してください。どのくらい待つべきかを参照してください。
- タスクIDを記録してください。サポートに問い合わせる際はこのIDを含めてください。
- 送信前に入力内容を確認してください。画像やモデルがエンドポイントの形式要件を満たしていることを確認してください。
- APIはサーバーから呼び出してください。ブラウザで実行されるコードは、ページを開いた人なら誰でもAPIキーを閲覧できる状態にしてしまいます。