lowpoly 将于 2026年10月30日 下线。 meshy-7 作为 3D 生成模型将于 2026年12月31日 下线;作为贴图模型仍可使用。 请在这些日期前切换模型,以免请求报错。 查看所有弃用信息

Errors

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


请求错误

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

响应格式

错误响应中有一个 message 字段,用于描述出错的原因:

  • Name
    message
    Type
    string
    Description

    对错误的简短描述。

状态码

  • Name
    2xx
    Description

    成功。

    • Name
      200 - OK
      Description

      请求成功。

    • Name
      202 - Accepted
      Description

      Meshy 已接受该请求,处理尚未完成。例如,创建任务的请求会返回 202。

  • Name
    4xx
    Description

    请求或你的账户存在问题。每个状态码都说明了应如何处理。

    • Name
      400 - Bad Request
      Description

      请求无效,通常是因为缺少必需的参数,或某个参数格式有误。

    • Name
      401 - Unauthorized
      Description

      API key 缺失、无效,或无法访问该 endpoint。请参阅身份验证。

    • Name
      402 - Payment Required
      Description

      该 API key 所属账户的积分不足以完成该请求。在免费套餐中,大多数创建任务的请求也会返回 402。

    • Name
      403 - Forbidden
      Description

      你无权发出此请求,可能的原因包括:

      • 请求来自不在该 API key 的 IP 允许列表中的地址。
      • 你的组织的 IP 过滤策略在你读取任务文件时阻止了访问。
      • 该 endpoint 在你的套餐中不可用。
      • 内容 moderation 拦截了输入内容。部分 endpoint 会为此返回 400;每个 endpoint 页面都会列出其对应的状态码。
      • 该 API key 所属的团队成员已不再是团队的活跃成员。
      • 该账户已被封禁。
    • Name
      404 - Not Found
      Description

      资源不存在。例如,使用不存在的 ID 获取任务会返回 404。

    • Name
      409 - Conflict
      Description

      资源存在,但其状态不允许执行该操作。例如,删除处于 IN_PROGRESS 状态的任务会返回 409,因为 Meshy 无法为已开始处理的任务退还积分。该任务会继续运行。请等待其进入最终状态(SUCCEEDED、FAILED 或 CANCELED)后再删除该任务。

    • Name
      422 - Unprocessable Entity
      Description

      请求有效,但 Meshy 无法处理其输入内容。例如,当骨骼绑定在模型中找不到类人体型时,会返回 422。

    • Name
      429 - Too Many Requests
      Description

      你发送的请求过多,或你有过多任务处于排队或运行状态。如果响应中带有 Retry-After 头,请等待相应的秒数后重试。请参阅速率限制。

  • Name
    5xx
    Description

    Meshy 一侧出现了问题。请采用退避策略重试。如果错误持续出现,请查看状态页面,并通过 Discord 联系我们。

Example: 400 Bad Request

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

任务错误

Meshy 创建的任务在运行过程中仍可能失败。此时其 status 会变为 FAILED,Meshy 会退还相应的积分,并且 task_error 会说明失败的原因。

失败任务的 task_error 包含以下字段:

  • Name
    type
    Type
    string
    Description

    错误类别。失败任务中始终会包含此字段。根据它来判断是否应该重试。请参阅错误类型。

  • Name
    message
    Type
    string
    Description

    对错误的易读描述。失败任务中始终会包含此字段。

  • Name
    code
    Type
    string
    可选
    Description

    一个可供你据此采取行动的、有文档记录的具体问题。当 Meshy 提供更多详情时会出现此字段。请参阅错误代码。Meshy 可能会新增代码,因此对于你不认识的代码,应根据其 type 进行处理。

  • Name
    doc_url
    Type
    string
    可选
    Description

    指向本页面中该代码对应条目的链接,其中说明了应采取的操作。当存在 code 时会出现此字段。

Error with details

{
  "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"
  }
}

Error without details

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "FAILED",
  "task_error": {
    "type": "server_error",
    "message": "An internal error occurred. Please retry."
  }
}

错误类型

type 是失败的大致分类。可以用它来决定接下来该怎么做。

  • Name
    invalid_input
    Description

    你发送的输入存在问题。请查看 code 和 message,修正输入内容,然后重新创建任务。

  • Name
    timeout
    Description

    任务超出了服务器端的时间限制(处理耗时或排队等待耗时),因而失败。Meshy 会退还相应的积分。这种情况通常是暂时性的。请重新创建任务;如果依然持续失败,可以尝试使用更简单的输入。

  • Name
    service_unavailable
    Description

    服务暂时不可用。请稍等片刻,然后重新创建任务。

  • Name
    server_error
    Description

    任务运行期间 Meshy 这边出现了问题。请重新创建任务。如果依然持续失败,请携带任务 ID 联系支持团队。


错误代码

当存在 code 字段时,它指明了以下问题之一。

image_too_complex

输入图像或 prompt 描述的主体在几何结构上过于复杂,无法用于 3D 生成。

例如:

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

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

一箱混合浆果一座复杂的大教堂天花板一座带有脚手架的在建建筑一个蜂巢格栅球体

要解决这个问题,请尝试以下一种或多种方法:

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

model_missing_uv

您发送了一个用于 texture 生成的模型,并将 enable_original_uv 设置为 true,但该模型没有 UV 坐标。UV 坐标定义了 2D texture 如何包裹到 3D 表面上。

No UVs vs Good UVs

要解决此问题,请执行以下操作之一:

  • 若要保留模型自身的 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 时,经常会发生这种情况。

Insufficient UVs vs Good UVs

要解决此问题,请执行以下操作之一:

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

model_missing_texture

Multi-Color Print 任务的输入模型没有任何 Meshy 可以拆分为打印颜色的颜色。Meshy 会根据模型的颜色构建多色 3MF,因此纯白色的 mesh 没有可用的素材。例如,从未进行过 texture 处理的 Text to 3D 或 Image to 3D 预览没有颜色。Repair Printability 的输出,或未保留 texture 的 Auto Split 任务也同样没有颜色。

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

  • realistic 通过模型的 UV 对基础颜色 texture 进行采样。它需要一个单一的基础颜色 texture,以及每个 mesh 部件上的 UV。
  • cartoon 按面将颜色扁平化。它接受任意部件上的基础颜色 texture,或逐顶点颜色(COLOR_0)。

如果模型既没有基础颜色 texture 也没有顶点颜色,Meshy 会拒绝该模型用于这两种 style,而不是让 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 或多 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 暴露给任何打开该页面的人。