Errors

在本指南中，我们将讨论在使用 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 坐标，就会出现此 Errors。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 将具有适合贴图的合理覆盖率。

model_missing_texture

当 Multi-Color Print 任务的输入模型没有可供转换器分离为打印颜色的颜色信息时，会出现此错误。多色 3MF 是根据模型的颜色构建的，因此一个纯白色的 mesh——例如从未经过 texture 处理的 Text to 3D 或 Image to 3D 预览，或是经过修复/自动拆分的输出——没有任何可供处理的内容。

哪些内容可以算作颜色来源取决于你请求的 style：

• realistic 会通过模型的 UV 对基础颜色 texture 进行采样，因此它要求每一个 mesh 部件上都有单一的基础颜色 texture 及 UV 坐标。
• cartoon 会按面平铺颜色，可以接受任意部件上的基础颜色 texture，或者每顶点颜色（COLOR_0）。

既没有基础颜色 texture 也没有顶点颜色的模型，在这两种 style 下都会被拒绝；对于 cartoon 而言，如果不这样限制，它本可以“成功”生成一个单色打印结果。

大多数请求会在任务创建之前就被拒绝（返回 400 Bad Request 并附带相同的说明），因此通常只有在无法提前检查输入内容的情况下才会看到此错误代码——例如，上传 .fbx 文件时，是在任务将其标准化之后才进行检查的。

解决方法：

• 先对模型进行 texture 处理。 对其运行 Retexture 任务，或在生成时启用贴图（例如 Text to 3D 的 refine 任务，或设置了 should_texture: true 的 Image to 3D 任务），然后将该任务作为 input_task_id 传入。
• 顶点着色模型（摄影测量扫描、手绘 mesh）：请求 style: "cartoon"，它会读取 COLOR_0。
• 在 realistic 下部分贴图或多贴图的模型：每个 mesh 部件都需要 UV 坐标，并使用同一个单一的基础颜色 texture。请对剩余部件进行 texture 处理，或将多个 texture 合并为一个图集，或改用 style: "cartoon"。

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. 验证输入。 确保您的输入图像和模型在提交前满足格式要求。