错误

在本指南中，我们将讨论在使用 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. 每张图片使用单一物体。 该模型在处理单一明确主体时效果最佳。不要在同一张图片或 prompt 中包含多个独立的物体。
2. 简化你的主体。 降低细节层级。例如，使用一个简单的花瓶，而不是插满几十朵花的花瓶。
3. 避免 scene 级别的 prompt。 整栋建筑、城市街区、摆满家具的室内空间或风景，很可能超出模型的处理能力。请将重点放在单一物体上。
4. 避免密集的重复结构。 脚手架、金属网、格栅图案或大量小物件的堆叠等主体，是常见的触发因素。

model_missing_uv

当您上传模型进行 texture 处理时，如果将 enable_original_uv 设置为 true，但该模型没有 UV 坐标，就会出现此错误。UV 坐标定义了 2D texture 如何包裹到模型的 3D 表面上。

解决方法：

正确的修复方法取决于您为什么将 enable_original_uv 设置为 true：

• 如果您需要保留模型原始的 UV 布局（例如，为精确的 texture 映射自定义接缝位置）：您的模型必须具有有效的 UV 坐标。上传前请在您的 3D 软件的 UV editor 中确认 UV 是否存在。请注意，STL 文件无法存储 UV 数据，因此请改用 GLB、FBX 或 OBJ。
• 如果您不需要特定的 UV 控制（或者不确定）：省略 enable_original_uv 或将其设置为 false。系统会自动为您的模型生成 UV 布局。自动生成的 UV 会针对覆盖率进行优化，但您将无法控制 texture 接缝的放置位置。

model_insufficient_uv

此错误发生在模型具有 UV 坐标，但 UV 覆盖范围过小，无法满足质量贴图要求时。这种情况通常发生在从 3D 工具导出的模型中，这些工具生成了占位符或折叠的 UV，而没有进行正确的展开。

解决方法：

• 如果你需要保留原始的 UV 布局： 在你的 3D 软件中重新展开模型的 UV。确保 UV 岛正确地分布在 UV 空间中，而不是折叠成一小块区域。
• 如果你不需要特定的 UV 控制： 省略 enable_original_uv 或将其设置为 false。系统将自动生成新的 UV 布局。这样做的代价是你会失去原始的接缝位置，但自动生成的 UV 会有适合贴图的正确覆盖范围。

invalid_input

这是当输入未通过验证但没有更具体的代码适用时的回退错误代码。message 字段包含失败的具体原因。

常见原因包括：

• 模型文件为空或已损坏
• 不受支持的文件格式变体（例如 ASCII 格式的 FBX 文件、经过 meshopt 压缩的 GLB）
• 上传的模型中未找到有效的 3D 对象（例如文件仅包含骨架、相机或灯光）
• 未通过安全过滤器的内容

解决方法： 查看 message 字段以了解具体出错原因。请检查你的输入文件和参数是否符合该 endpoint 的要求。

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. 验证输入内容。 提交前请确保您的输入图像和模型符合格式要求。