Creative Lab 灯具 API

用于制作灯罩的照片，可以是公开可访问的 URL 或 Data URI（data:image/jpeg;base64,<your base64-encoded image data>）。

图片必须为 JPG、JPEG、PNG 或 WebP 文件，且大小不超过 20 MB。

照片中主体的类型，用于决定 Meshy 如何对其进行风格化处理。

可用取值：

• character：单个角色或物体，例如手办、动物或吉祥物
• landscape：户外场景或全景，例如山脉、城市景观或森林

任务的名称，最多 100 个字符。它会在任务的 name 字段中返回。名称过长会返回 400。

是否从 prototype 图片中移除背景。设为 true 会返回带透明背景的 RGBA PNG 图片，方便你将主体放置在任意背景上。Meshy 也会基于去除背景后的图片构建 3D 模型。如果 Meshy 无法移除背景，则会使用带背景的原始图片，任务依然会成功。

请求无法运行。例如：

• 缺少 image_url。
• 图片不是 JPG、JPEG、PNG 或 WebP 文件。
• 图片过小、超过 20 MB，或超过最大像素数。
• Meshy 无法下载该图片，例如 URL 返回 404 或超时。
• Data URI 不是有效的 base64 编码。
• 图片被标记为 NSFW（不适宜工作场所）内容。
• image_subject 既不是 character 也不是 landscape。

错误信息会说明发现的具体问题。修复请求后重新发送。

API key 缺失或无效。请检查 Authorization 请求头。

以下情形之一适用：

• 账户 credits 不足。
• API key、workspace 或成员已达到其 credit 限额。
• 账户处于免费套餐。

请检查你的 credits 和套餐，然后重试。

你的团队已开启 IP Filtering（知识产权过滤），且 Meshy 将该图片标记为涉及第三方知识产权。请发送你拥有使用权利的图片。

达到了以下限制之一：

• 你发送的请求超过了速率限制所允许的数量。请等待几秒钟后重试。参见速率限制。
• 你排队或正在运行的任务过多。请等待部分任务完成后重试。
• 在没有剩余 credits 的无限套餐下，你达到了无需 credits 即可运行的任务数量上限。请等待某个任务完成，或增加 credits。

Meshy 遇到了服务器错误，例如无法对图片执行知识产权检查。Meshy 不会创建该任务，并会退还已扣除的任何 credits。请重试该请求。

要构建的原型任务的 ID。它必须是您的账户通过 POST /openapi/creative-lab/lamp/v1/prototype 创建的任务，且状态为 SUCCEEDED。

如果该 ID 不是来自 API 的 Lamp 原型任务（包括在 Web App 中创建的原型），将返回 404。

任务的名称，最多 100 个字符。它会在任务的 name 字段中返回。名称过长会返回 400。

灯罩最大尺寸的大小，单位为毫米，范围为 50 到 400。Meshy 会按比例均匀缩放模型以适配。0 表示使用默认值，超出该范围的其他值会返回 400。

灯罩的壁厚，单位为毫米，最大为 10。0 表示使用默认值，负值或超过 10 的值会返回 400。

在底部切平的高度所占模型高度的百分比，范围为 1 到 100。平整的底部可让灯罩放置在打印平台上，并为固定装置留出空间。超出范围的值会返回 400。

灯光固定装置预设，用于设置 Meshy 如何构建底部。

可用值：

• bambu_mh001_60mm：底部开口的灯罩，带有一个具有 60 mm 固定孔的底板（均位于 model_urls.lamp_stl 中），以及位于 model_urls.base_stl 中的固定装置安装件
• none：单个密封灯罩，位于 model_urls.lamp_stl 中，没有 model_urls.base_stl

固定孔相对灯罩中心沿 X 轴移动的距离，单位为毫米，范围为 -80 到 80。仅在 light_source_preset 不是 none 时适用。

固定孔相对灯罩中心沿 Z 轴（深度方向）移动的距离，单位为毫米，范围为 -80 到 80。仅在 light_source_preset 不是 none 时适用。

在 Meshy 处理模型之前，围绕 X 轴施加的旋转角度，单位为度，范围为 -360 到 360。Meshy 会以模型中心为基准，按 XYZ 欧拉角的方式依次施加这三个旋转。

在 Meshy 处理模型之前，围绕 Y 轴施加的旋转角度，单位为度，范围为 -360 到 360。

在 Meshy 处理模型之前，围绕 Z 轴施加的旋转角度，单位为度，范围为 -360 到 360。

是否在 zip 压缩包中添加一个 result.json 文件，其中包含所运行流水线的名称、警告信息和文件路径。需要将 output.format 设置为 zip。若与 stl 一起设为 true 会返回 400。

构建返回的文件。

可用值：

• stl：model_urls.lamp_stl，即带底板的灯罩（当存在固定装置预设时），以及当 light_source_preset 不是 none 时的 model_urls.base_stl
• zip：model_urls.bundle_zip 中的一个 zip 文件，包含 lamp.stl，以及在适用时的 base.stl 和 result.json

请求无法运行。例如：

• input_task_id 缺失或不是有效的任务 ID。
• 原型任务的状态不是 SUCCEEDED。如果仍在运行，请等待后重试。如果已失败或被取消，请创建新的原型任务。
• 原型任务已成功，但没有 3D 模型。请创建新的原型任务。
• 某个 options 字段超出范围或不是可用值。
• output.format 不是 stl 或 zip，或者未设置 zip 却将 include_result_json 设为 true。

错误消息会说明发现的具体问题。

API key 缺失或无效。请检查 Authorization 请求头。

以下情况之一适用：

• 账户没有足够的 credits。
• 该 API key、workspace 或成员已达到其 credit 限额。
• 账户使用的是免费套餐。

请检查您的 credits 和套餐，然后重试。

input_task_id 与您的账户通过 API 创建的任何 Lamp 原型任务都不匹配。在 Web App 中创建的原型也会返回 404。请发送原型创建响应中的 result ID。

达到以下限制之一：

• 您发送的请求数超过了速率限制允许的数量。请等待几秒钟后重试。请参阅速率限制。
• 您排队或正在运行的任务过多。请等待部分任务完成后再重试。
• 在无限制套餐下且没有剩余 credits 时，您已达到无需 credits 即可运行的任务数量上限。请等待某个任务完成，或添加 credits。

创建响应中返回的任务 ID。

id 不是有效的任务 ID。请发送创建响应中的 result ID。

你的团队已开启 IP Filtering（知识产权过滤）功能，且 Meshy 将该原型任务的图像标记为涉及第三方知识产权。构建任务以及 Enterprise 套餐团队不会出现此错误。请使用你拥有使用权的图像来创建原型任务。

你的账户下不存在此 ID 对应的灯具任务，或者该任务所处的阶段与路径不匹配。请检查 ID，并使用 /prototype 或 /build 来匹配对应任务。

Meshy 无法执行知识产权检查。请重试该请求。

要取消的任务的 ID。

以下情况之一：

• id 不是有效的任务 ID。请发送创建响应中的 result ID。
• 任务已处于最终状态（SUCCEEDED、FAILED 或 CANCELED），因此无法取消。

你的账户下没有该 ID 对应的灯具任务，或任务所处的阶段与路径不匹配。请检查 ID，并使用 /prototype 或 /build 以匹配对应任务。

创建响应中返回的任务 ID。

要列出的阶段，prototype 或 build。

要返回的页码，范围从 1 到 255。0 返回第一页。超出 0 到 255 范围的值将返回 400。

每页任务数，最多 100。101 到 255 之间的值将返回 100 个任务，0 使用默认值。超出 0 到 255 范围的值将返回 400。

排序顺序。

可用值：

• -created_at：最新的排在最前
• +created_at：最旧的排在最前

任务 ID。请勿依赖其格式。

任务类型，始终为 creative-lab-lamp-prototype。

你在创建任务时发送的 name，如果未发送，则为 ""。

任务的状态。

可用值：

• PENDING：在队列中等待
• IN_PROGRESS：正在生成结果
• SUCCEEDED：最终状态，已获得结果
• FAILED：最终状态，原因见 task_error
• CANCELED：最终状态，没有结果

已完成工作的百分比，从 0 到 100。任务开始前为 0，成功后为 100。

任务创建的时间，以 Unix 毫秒表示。

worker 开始执行任务的时间，以 Unix 毫秒表示。在此之前为 null。

任务达到最终状态的时间，以 Unix 毫秒表示。在此之前为 null。

任务结果过期的时间，以 Unix 毫秒表示。该时间为 finished_at 之后 3 天；在任务完成之前，则为 created_at 之后 3 天。对于会无限期保留 API 结果的企业版账户，该时间大约是 100 年后。参见资产保留期。

任务处于 PENDING 状态时在队列中的位置。1 表示下一个就轮到它开始。任务离开队列后为 0，在列表结果中始终为 0。

任务失败的原因。除非 status 为 FAILED，否则为 null。参见 Errors。

该任务扣除的 credits 数量（已扣除任何退款）。返回错误的请求不会被扣费。失败的任务为 0，因为 Meshy 会退还该费用。取消任务仅在其处于 PENDING 状态时才会退款。如果 Meshy 无法读取扣费信息，get 或 stream 响应会省略该字段，而 list 请求会返回 500。在这种情况下，请重试该请求。

从概念图生成的 3D 模型的下载 URL。在任务成功之前为 {}。

3D 模型预览图的下载 URL。在任务成功之前为 ""。

概念图的下载 URL。任务成功后，数组中包含一个 URL；在此之前为空数组。

任务 ID。不要依赖其格式。

任务类型，始终为 creative-lab-lamp-build。

创建任务时你发送的 name，如果没有发送则为 ""。

任务的状态。

可用取值：

• PENDING：在队列中等待
• IN_PROGRESS：正在生成结果
• SUCCEEDED：最终状态，附带结果
• FAILED：最终状态，原因见 task_error
• CANCELED：最终状态，没有结果

已完成工作的百分比，范围从 0 到 100。在任务开始之前为 0，成功后为 100。

任务创建的时间，采用 Unix 毫秒时间戳。

工作进程开始处理任务的时间，采用 Unix 毫秒时间戳。在此之前为 null。

任务达到最终状态的时间，采用 Unix 毫秒时间戳。在此之前为 null。

任务结果过期的时间，采用 Unix 毫秒时间戳。该时间为 finished_at 之后的 3 天；在任务完成之前，则为 created_at 之后的 3 天。对于会无限期保留 API 结果的企业版账户，该时间大约在 100 年之后。请参阅资产保留期。

任务处于 PENDING 状态时在队列中的位置。1 表示下一个就会开始处理该任务。任务离开队列后为 0，在列表结果中始终为 0。

任务失败的原因。除非 status 为 FAILED，否则为 null。请参阅错误。

任务扣除的 credits 数量（已扣除任何退款）。返回错误的请求不会被扣费。失败的任务为 0，因为 Meshy 会退还费用。只有在任务处于 PENDING 状态时取消才会退款。如果 Meshy 无法读取扣费信息，获取或流式响应会省略该字段，而列表请求会返回 500。这种情况下，请重试该请求。

可打印文件的下载链接。出现哪些键取决于 output.format 和 options.light_source_preset。