Creative Lab 键帽 API

要转换为键帽设计的照片，可以是公开可访问的 URL，或是一个 data URI（data:image/jpeg;base64,<your base64-encoded image data>）。

图片必须是 JPG、JPEG、PNG 或 WebP 文件，且不超过 20 MB（20,000,000 字节）。每条边至少为 32 像素，图片总像素数最多为 178,956,970。超出这些限制的图片会返回 400。

Meshy 会根据图像数据来检测格式，而不是依据 URL 中的文件扩展名。没有扩展名的 URL 也可以正常工作，并且 Meshy 会跟随 HTTP 重定向。Meshy 会应用 EXIF 方向信息，因此旋转过的手机照片会按照其实际显示的方向呈现。

data URI 必须使用 base64 编码，并带有图像类型，例如 data:image/png;base64,...，且解码后的图像必须是 JPEG、PNG 或 WebP 格式。20 MB 的限制适用于解码后的图像，因此 base64 文本本身可能会大约再大三分之一。

任务的名称，最多 100 个字符。该名称会在任务的 name 字段中返回。超出长度限制会返回 400。

是否从 prototype 图像中移除背景。设为 true 会返回一张透明的 RGBA PNG，这样你就可以将键帽放置在任意背景之上。如果 Meshy 无法移除背景，它会返回带有原背景的图像，任务仍然会成功。

无论如何，build 阶段用于生成 3D 效果的头部设计都会保留其背景。build 阶段会根据 image_urls 中的图像来绘制键帽底座，如果你发送了 true，则不带其背景。build 阶段会将该图像以 process_image_urls.composite 的形式返回。

请求无法执行。例如：

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

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

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

以下情况之一适用：

• 账户的积分不足。
• 该 API key、workspace 或成员已达到其积分上限。
• 该账户处于免费套餐。

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

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

已达到以下限制之一：

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

Meshy 遇到了服务器错误，例如由于内容审核（moderation）或知识产权检查未能运行，或 Meshy 无法存储该图像。Meshy 不会创建该任务，并会退还其已扣除的任何积分。请重试该请求。

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

如果 ID 不是你通过 API 创建的 Keycap prototype 任务之一，将返回 404，这也包括在 web app 中创建的 prototype。

要构建的候选项，来自 prototype 任务的 candidate_ids 数组。如果值不在该数组中，将返回 400。

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

用于构建的 keycap 底座。目前唯一可用的值是 cherry-mx-1x1-r1，即标准的 Cherry MX profile 1u keycap。不支持自定义尺寸，其他任何值都会返回 400。

头部沿其最长维度的尺寸，单位为毫米，范围为 10 到 40。Meshy 会缩放头部，使其最长维度与该值匹配。超出范围的值将返回 400。

当值大于约 32.9 时，Meshy 可能会缩小尺寸，以使头部符合底座的保护性占用面积限制。此时头部生成的结果可能会比你要求的更小。任务对象不会返回 Meshy 实际应用的尺寸。要检查该尺寸，请测量模型中 keycap-head mesh 的包围盒。

在 Meshy 将头部嵌入底座之前对其施加的垂直偏移量，单位为毫米，范围为 -5 到 5。超出范围的值将返回 400。

请求无法运行。例如：

• input_task_id 缺失或不是有效的任务 ID。
• prototype 任务的状态不是 SUCCEEDED。如果仍在运行，请等待后重试。如果已失败或被取消，请创建一个新的 prototype 任务。
• prototype 任务成功了，但没有候选项。请创建一个新的 prototype 任务。
• candidate_id 缺失，或不在 prototype 任务的 candidate_ids 中。请从该数组中发送一个值。
• options 中的某个字段超出范围，或 base_model 不是可用的值。

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

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

以下情况之一适用：

• 账户没有足够的积分。
• 该 API key、workspace 或成员已达到其积分限额。
• 账户处于免费计划。

请检查你的积分和计划，然后重试。

input_task_id 与你的账户通过 API 创建的任何 Keycap prototype 任务都不匹配。在 web app 中创建的 prototype 同样会返回 404。请发送来自 prototype 创建响应中的 result ID。

达到以下限制之一：

• 你发送的请求数超过了速率限制所允许的数量。请等待几秒后重试。参见速率限制。
• 你排队或正在运行的任务过多。请等待部分任务完成后重试。
• 在没有积分的无限制计划下，你达到了在没有积分时可运行的任务数量上限。请等待某个任务完成，或添加积分。

由于服务器错误，Meshy 无法创建任务。Meshy 会退还其已扣除的所有积分。请重试该请求。

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

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

你的团队已开启 IP Filtering，并且 Meshy 检测到该 prototype 任务的图片涉及第三方知识产权问题。Build 任务以及 Enterprise 套餐团队不会遇到此错误。请使用你拥有使用权的图片来创建 prototype 任务。

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

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

要取消的任务的 ID。

以下情况之一适用：

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

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

Meshy 在取消任务时遇到了服务器错误，因此该任务可能已取消，也可能未取消。请先获取任务以检查其 status，然后再重试。

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

要列出的阶段，prototype 或 build。

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

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

排序方式。

可用值：

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

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

任务类型，恒为 creative-lab-keycap-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 结果的 Enterprise 账户，该时间约为 100 年之后。另见资产保留期。

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

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

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

成品键帽图像的下载 URL。任务成功后，该数组包含一个 URL；在此之前为空数组。image_urls[i] 展示的是 candidate_ids[i] 所对应的候选结果。

这些 URL 仅用于展示。build endpoint 接收的是 candidate_ids 中的某个条目，而不是 URL。这些是签名 URL，获取时无需携带 Authorization 请求头。它们在 expires_at 之前始终有效，并且再次获取该任务会返回相同的 URL。

候选结果的 ID，顺序与 image_urls 相同。要构建某个候选结果，请在 build 请求中将其 ID 作为 candidate_id 发送。请勿依赖这些 ID 的具体格式。

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

任务类型，始终为 creative-lab-keycap-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。参见Errors。

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

3D 模型的下载 URL。Meshy 导出的 GLB 文件和 OBJ 包按真实世界比例（以毫米为单位）、Y 轴朝上，键帽正面朝向 +Z 方向。

该模型包含名为 keycap-head 和 keycap-base 的 mesh。当 Meshy 回退为底座使用图案填充时，模型还会包含一个用于轴芯凹腔的 keycap-base-interior mesh。请勿假设模型一定只有两个 mesh。

这些是签名 URL，因此获取时无需携带 Authorization 请求头。它们在 expires_at 之前保持有效，在此之前再次获取该任务会返回相同的 URL。过期的 URL 无法续期，因此请在到期前下载并保存文件。

构建过程各步骤生成图片的下载 URL，按类型进行键值索引。与 model_urls 一样，它们也是签名 URL，因此获取时无需携带 Authorization 请求头。它们在 expires_at 之前保持有效，再次获取该任务会返回相同的 URL。

它可能包含以下键：

• head_design：所选候选项的设计图像，构建任务据此生成 3D 内容。始终存在。
• composite：所选候选项完成后的键帽图像，底座正是根据它绘制而成。可能缺失。
• base_canvas：绘制完成的键帽底座。可能缺失。

Meshy 可能会新增键，因此遇到不认识的键请直接忽略。