Errors

了解请求或任务失败的原因，以及接下来该怎么做。请求可能会立即因 HTTP 错误而失败，任务也可能稍后因 task_error 而失败。

请求错误

Meshy 在拒绝请求时会立即返回这些错误。要找出问题所在，请检查 HTTP 状态码和 message 字段。

{
  "message": "Invalid model file extension: .3dm"
}

任务错误

Meshy 创建的任务在运行过程中仍可能失败。此时它的 status 会变为 FAILED，Meshy 会退还其积分，并通过 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 生成。

例如：

• 密集堆放的小物体，例如装满水果的箱子或一摞书
• 复杂的重复图案，例如格栅结构、脚手架或金属网
• 复杂的建筑物，例如拥有许多窗户和阳台的多层建筑
• 一张图片中包含多个不同的物体，而不是单一的主体

以下输入很可能过于复杂：

要解决此问题，可以尝试以下一种或多种方法：

• 每张图片只使用一个物体。Meshy 在处理单一、清晰的主体时效果最好，因此不要在同一张图片或 prompt 中放入多个独立的物体。
• 简化你的主体。例如，使用一个简单的花瓶，而不是插满几十朵花的花瓶。
• 避免使用场景。整栋建筑、街区、布置好的房间和风景通常都过于复杂。请专注于单一物体。
• 避免密集的重复结构。脚手架、金属网、格栅以及成堆的小物件都是常见的触发因素。

model_missing_uv

你发送模型进行 texture 处理时将 enable_original_uv 设置为 true，但该模型没有 UV 坐标。UV 坐标定义了 2D texture 如何包裹到 3D 表面上。

要解决此问题，请执行以下操作之一：

• 若要保留模型自身的 UV 布局（例如用于自定义接缝位置），请在你的 3D 软件中为模型添加 UV，在其 UV editor 中检查无误后，再重新上传模型。STL 文件无法存储 UV，因此请使用 GLB、FBX 或 OBJ。
• 如果你不需要自己的布局，或者不确定，请省略 enable_original_uv 或将其设置为 false。此时 Meshy 会为模型创建 UV 布局。新的 UV 能很好地覆盖模型，但你无法控制 texture 接缝的位置。

model_insufficient_uv

该模型具有 UV 坐标，但它们覆盖的 UV 空间过小，无法很好地生成 texture。这种情况常见于导出器写入了占位符或塌陷的 UV、而没有进行正确展开的模型。

要解决此问题，请执行以下操作之一：

• 若要保留你自己的 UV 布局，请在你的 3D 软件中重新展开模型的 UV。将 UV 岛分布到整个 UV 空间，而不是集中在其中一小块角落。
• 如果你不需要自己的布局，请省略 enable_original_uv 或将其设置为 false。这样 Meshy 会创建一个新的 UV 布局。你会失去自己设置的接缝位置，但新的 UV 会覆盖足够的空间以便生成 texture。

model_missing_texture

多色打印 任务的输入模型没有 Meshy 可以拆分为打印颜色的颜色。Meshy 会根据模型的颜色构建多色 3MF，因此一个纯白色的 mesh 没有可用的信息。例如，从未经过贴图的 Text to 3D 或 Image to 3D 预览没有颜色。Repair Printability 的输出，或未保留 texture 的 Auto Split 任务，同样也没有颜色。

什么算作颜色取决于你请求的 style：

• realistic 会通过模型的 UV 对基础颜色 texture 进行采样。它需要一个单一的基础颜色 texture，并且每个 mesh 部件都要有 UV。
• cartoon 会按面将颜色进行扁平化处理。它接受任意部件上的基础颜色 texture，或逐顶点颜色（COLOR_0）。

对于这两种 style，如果模型既没有基础颜色 texture 也没有顶点颜色，Meshy 会拒绝该模型，而不会让 cartoon 将其转换为单色打印。

对于大多数此类请求，Meshy 会在创建任务之前就予以拒绝，返回 400 并附带相同的说明。通常只有在 Meshy 无法提前检查输入内容时，你才会收到这个代码。例如，Meshy 只会在任务完成转换后才检查 .fbx 上传文件。

要解决这个问题，请使用适合你模型的方案：

• 先为模型制作 texture。对它运行 Retexture，或者通过 Text to 3D 的 refine 任务生成，或使用 should_texture: true 的 Image to 3D 任务生成。然后将该任务作为 input_task_id 发送。
• 对于顶点着色的模型，例如摄影测量扫描或手绘 mesh，使用 style: "cartoon"，它会读取 COLOR_0。
• 对于使用 realistic 的部分贴图或多 texture 模型，为每个 mesh 部件提供 UV，并使用同一个基础颜色 texture。为此，可以为剩余部件制作 texture，或将多个 texture 合并为一张图集。你也可以改用 style: "cartoon"。

textured_split_refused

Auto Split 任务在设置 keep_texture: true 时，无法在拆分出的部件上保留输入模型的 texture。例如，模型没有 UV，或者其 texture 没有足够的空间容纳切割产生的新面。Meshy 会退还积分。

要解决此问题，请在不带 keep_texture 参数或将其设为 keep_texture: false 的情况下重新发送请求。这样返回的各个部件将各自呈现单一的纯色。

invalid_input

输入未通过检查，且没有更具体的错误代码适用。message 给出了具体原因。

例如：

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

要解决此问题，请查看 message 以了解具体问题。请检查你的输入文件和参数是否满足该 endpoint 的要求。

moderation_blocked

安全过滤器拒绝了您的 prompt 或参考图片。过滤器会同时检查文本和图片。

要解决此问题，请执行以下一项或两项操作：

• 修改 prompt，删除具有暗示性或敏感性的描述。
• 更换可能被过滤器拦截的参考图片。

moderation_unavailable

类型：server_error。内容 moderation 暂时不可用，因此 Meshy 没有跳过检查，而是将任务判定为失败。您的内容本身没有问题。

要解决此问题，请重新创建任务。

timeout

任务运行超过了服务器端的时间限制（处理耗时或排队等待耗时），因此 Meshy 判定该任务失败并退还了积分。高负载，或输入过于复杂而无法在规定时间内完成，都可能导致这种情况。

这与你自己代码中的 timeout 不同。如果你的客户端停止了等待，任务其实仍在运行。请参阅需要等待多久。

要解决此问题，请按以下步骤操作：

1. 重新创建任务。timeout 通常是暂时性的，新建的任务可能会成功。
2. 如果仍然持续失败，请简化你的输入，例如减少图片或 prompt 中的细节。对于处理难度较大的输入，请参阅 image_too_complex。

queue_timeout

类型：timeout。任务在队列中等待时间过长而未能开始，因此 Meshy 判定该任务失败，并退还了为此扣除的所有积分。此错误并非由你的输入导致。

要解决此问题，请重新创建任务。

format_conversion_failed

Meshy 已生成模型，但将其转换为你所请求的格式时失败。

要解决此问题，请按照以下步骤操作：

1. 重新创建任务。
2. 如果某种格式持续失败，请改为请求一种适合你需求的其他格式。

最佳实践

• 重试失败的任务。对于出现 timeout、service_unavailable 或 server_error 的失败任务，使用指数退避策略创建新任务。
• 不要在自己的请求超时时创建新任务。第一个任务可能仍在运行，因此在创建另一个任务之前，请先检查它是否存在。参见需要等待多久。
• 记录任务 ID。联系支持团队时请附上该 ID。
• 在发送输入之前先检查它们。确保图像和模型符合 endpoint 的格式要求。
• 从你的服务器调用 API。在浏览器中运行的代码会将你的 API key 暴露给任何打开该页面的人。