Creative Lab 冰箱贴 API

要转换为冰箱贴概念图的照片，可以是公开可访问的 URL 或 Data URI（data:image/jpeg;base64,<your base64-encoded image data>）。

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

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

是否移除 prototype 图像的背景。true 会返回一张保留整个磁贴的透明 RGBA PNG，方便你将其放置在任意背景上。构建阶段也会从去除背景后的图像开始处理。如果 Meshy 无法移除背景，则会返回带有背景的图像，任务仍然算作成功。

构建阶段的 remove_background 选项是独立的。

请求无法执行。例如：

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

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

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

以下情形之一适用：

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

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

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

达到以下其中一个限制：

• 你发送的请求超出了速率限制允许的数量。请等待几秒后重试。参见速率限制。
• 你有过多任务正在排队或运行。请等待部分任务完成后再重试。
• 在无限量套餐下且 credits 已用尽时，你已达到可在无 credits 情况下运行的任务数量上限。请等待某个任务完成，或增加 credits。

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

要构建的 prototype 任务的 ID。它必须是你的账号使用 POST /openapi/creative-lab/fridge-magnet/v1/prototype 创建的任务，且状态为 SUCCEEDED。

如果该 ID 不是你通过 API 创建的冰箱贴 prototype 任务（包括在 Web App 中创建的 prototype），将返回 404。

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

当 Meshy 未从主体中描摹轮廓时，磁贴的外轮廓。当 remove_background 为 false，或者 Meshy 找不到主体的轮廓时，会使用此设置。

可用取值：

• circle
• rounded-rect
• hexagon
• shield
• star

磁贴外接正方形的边长，单位为毫米，最大为 400。0 表示使用默认值。

浮雕高出底座的最大高度，单位为毫米，范围从 0 到 20。

浮雕整体下压的程度，单位为毫米，范围从 0 到 20。Meshy 会在浮雕各处的高度上减去该值，直至底座。

浮雕背后平整底板的厚度，单位为毫米，范围从 0 到 20。默认的 2 毫米底板能让磁贴有足够的厚度贴附在冰箱上，使浮雕不会显得脆弱。

是否封闭磁贴的背面，即粘贴磁铁的那一面。设为 false 会使背面保持中空，呈壳状。

将深度图数值映射为浮雕高度所用的曲线。

可用取值：

• linear
• gamma
• s-curve

曲线强度，最大为 10。gamma 和 s-curve 曲线会用到该值，linear 会忽略它。0 表示使用默认值。

是否反转深度图，使较暗的区域浮雕更高。

在 Meshy 构建浮雕之前对深度图进行平滑处理的程度，范围从 0 到 10。

在轮廓内以中心为基准缩放浮雕及其 texture 的程度，最大为 10。大于 1 的值会放大主体，小于 1 的值会缩小主体。它不会改变浮雕的高度。0 表示使用默认值。

低于此深度图数值时，Meshy 会将深度设为零，范围从 0 到 1。

是否从主体中描摹磁贴的轮廓，使磁贴形状贴合主体。设为 false 则改用 badge_shape 轮廓。当 Meshy 找不到主体的轮廓时，也会使用 badge_shape。

这与 prototype 的 remove_background 参数是分开的，后者用于设置 prototype 图像是否具有透明背景。

导出模型的 mesh 分辨率，范围从 64 到 512。Meshy 基于 512 像素的深度图构建 geometry，因此更精细的 mesh 只会增加面数而不会增加细节。0 表示使用默认值。

构建返回的文件格式。

可用取值：

• glb：一个 model.glb 文件，位于 model_urls.glb
• obj：一个包含 model.obj、model.mtl 和 texture.png 的 zip 文件，位于 model_urls.obj
• zip：一个包含 Meshy 生成的所有文件的 zip 文件，位于 model_urls.bundle_zip

请求无法运行。例如：

• input_task_id 缺失或不是有效的任务 ID。
• prototype 任务的状态不是 SUCCEEDED。如果仍在运行，请等待后重试。如果已失败或被取消，请创建一个新的 prototype 任务。
• prototype 任务已成功，但没有图像。请创建一个新的 prototype 任务。
• 某个 options 字段超出其取值范围，或不是可用取值。

错误信息会说明发现了哪个问题。

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

以下情况之一适用：

• 账号没有足够的 credits。
• API key、workspace 或成员达到了其 credit 限额。
• 账号处于免费方案。

请检查你的 credits 和方案，然后重试。

input_task_id 不匹配你的账号通过 API 创建的任何冰箱贴 prototype 任务。在 Web App 中创建的 prototype 也会返回 404。请发送 prototype 创建响应中的 result ID。

达到以下限制之一：

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

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

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

你的团队开启了 IP Filtering，且 Meshy 将该 prototype 任务的图片标记为涉及第三方知识产权。Build 任务以及 Enterprise 方案下的团队不会出现此错误。请使用你拥有使用权的图片创建 prototype 任务。

你的账户下没有与该 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-fridge-magnet-prototype。

创建任务时发送的 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。请参阅 Errors。

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

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

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

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

您在创建任务时发送的 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。在这种情况下，请重试该请求。

模型文件的下载链接，针对您所请求的 output.format 提供一个条目。在任务成功之前为 {}。