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头,请等待相应的秒数后重试。请参阅速率限制。
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 表面上。

要解决此问题,请执行以下操作之一:
- 若要保留模型自身的 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
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 不同。如果你的客户端停止等待,任务实际上仍在运行。请参阅需要等待多久。
要解决此问题,请按以下步骤操作:
- 重新创建任务。timeout 往往是暂时性的,新建的任务可能会成功。
- 如果仍然持续失败,请简化你的输入,例如降低图像或 prompt 中的细节程度。对于更难处理的输入,请参阅
image_too_complex。
queue_timeout
类型:timeout。任务在队列中等待时间过长而未能开始,因此 Meshy 判定该任务失败,并退还了为其扣除的所有积分。此错误并非由你的输入引起。
要解决此问题,请重新创建任务。
format_conversion_failed
Meshy 已生成模型,但将其转换为你所请求的格式时失败。
要解决此问题,请按以下步骤操作:
- 重新创建任务。
- 如果某个格式始终转换失败,请改为请求符合你需求的其他格式。
最佳实践
- 重试失败的任务。对于状态为
timeout、service_unavailable或server_error的失败任务,使用指数退避策略创建新任务。 - 当自己的请求超时时不要创建新任务。第一个任务可能仍在运行,因此在创建另一个任务之前,请先检查它是否存在。请参阅应等待多长时间。
- 记录任务 ID。联系支持团队时请附上该 ID。
- 发送输入前先进行检查。确保图像和模型符合该 endpoint 的格式要求。
- 从服务器调用 API。在浏览器中运行的代码会将你的 API key 暴露给任何打开该页面的人。