Errors

在本指南中，我们将介绍在使用 Meshy API 时出现问题会发生什么情况。

请求错误（Request Errors）

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

model_insufficient_uv

此 Errors 发生于模型具有 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 部件上都有 UV 坐标，并且只能有一个基础颜色 texture。
• cartoon 会按面拍平颜色，接受任意部件上的基础颜色 texture，或者每个顶点的颜色（COLOR_0）。

对于这两种 style，既没有基础颜色 texture 也没有顶点颜色的模型都会被拒绝；否则在 cartoon 下它会“成功”生成为单色打印。

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

解决方法：

• 先为模型添加 texture。 对其运行 Retexture 任务，或在生成时启用 texture 处理（例如 Text to 3D 的 refine 任务，或设置了 should_texture: true 的 Image to 3D 任务），然后将该任务作为 input_task_id 传入。
• 顶点着色的模型（如摄影测量扫描、手绘 mesh）：请求 style: "cartoon"，它会读取 COLOR_0。
• 在 realistic 下部分添加了 texture 或存在多个 texture 的模型：每个 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. 验证输入。 在提交之前，请确保您的输入图像和模型符合格式要求。