错误处理

在本指南中，我们将讨论当您使用 Meshy API 时出现问题时会发生什么。

请求错误

这些错误在 API 请求被拒绝时立即返回。请检查 HTTP 状态码和 message 字段以了解错误原因。

{
  "message": "无效的模型文件扩展名: .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. 每张图像使用单个物体。 模型对单一清晰的主体效果最佳。不要在同一张图像或提示中包含多个独立物体。
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 覆盖率不足以进行高质量贴图时，会出现此错误。这通常发生在 3D 工具导出时生成了占位符或折叠的 UV 而没有进行适当展开的情况下。

解决方案：

• 如果您需要保留原始 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 以便调试。联系支持团队时请提供任务 ID。
3. 验证输入。 在提交前确保您的输入图像和模型符合格式要求。