Creative Lab — Keychain API

将一张源照片转换为可 3D 打印的 Keychain 挂饰——一种徽章造型的彩色浮雕——分为两个阶段完成：prototype（原型） 阶段根据你的输入照片生成一张彩色概念图，随后 build（构建） 阶段将该概念图转换为浮雕 3D 模型。这两个阶段通过 input_task_id 关联起来。

POST /openapi/creative-lab/keychain/v1/prototype
POST /openapi/creative-lab/keychain/v1/build

POST/openapi/creative-lab/keychain/v1/prototype

创建 Keychain 原型任务

根据源照片生成单张彩色概念图像。返回的任务 ID 即是你在调用构建 endpoint 时需要传入的 input_task_id。响应结构请参见 Keychain 原型任务对象。

参数

Name
image_url
Type
string
必选
Description
供 Meshy 上色以生成可用于钥匙扣的概念图像的源照片。目前支持 .jpg、.jpeg、.png 和 .webp 格式。
提供图像的方式有两种：
- 公开可访问的 URL：可从公共互联网访问的 URL。
- Data URI：图像的 base64 编码 data URI。data URI 示例：data:image/jpeg;base64,<your base64-encoded image data>。
Name
name
Type
string
Description
可选的任务名称，用于展示。最多 100 个字符。
该名称用于在你的控制台和任务列表中标记该任务，不会被刻印到钥匙扣上——如需刻印文字，请使用 name_text。
Name
name_text
Type
string
Description
要刻印在钥匙扣上的文字，例如宠物或人的名字。最多 10 个字符，按 Unicode 字符而非字节计数，因此可以接受一个 10 个字符的中文、日文或韩文名字。若省略该字段，则生成的钥匙扣不带任何刻印。
使用前会去除首尾空白字符，并移除不可见的格式字符。处理后的值会作为 name_text 返回在原型任务对象中，因此你可以在为构建阶段付费之前，确认最终将被刻印的确切内容。
刻印是在此原型阶段完成的。构建阶段会自动继承该刻印，且不接受自己的 name_text。
当文字不是纯 ASCII 字符时，请以 UTF-8 编码发送请求体，并设置 Content-Type: application/json; charset=utf-8。部分 HTTP 客户端——包括 Windows PowerShell 的 Invoke-RestMethod——默认会以 ISO-8859-1 编码请求体，这会在数据到达 Meshy 之前，将所有非拉丁字符悄悄替换为 ?。API 无法区分这种情况与你确实想要的刻印内容。
Name
remove_background
Type
boolean
默认值 false
Description
设为 true 时，返回的原型图像将是去除背景的透明 RGBA PNG，方便你将主体合成到任意背景上。
此选项仅控制该 endpoint 返回的图像，与同名的构建选项（默认值为 true，用于控制在浮雕处理前是否去除背景）相互独立。

返回值

响应中的 result 属性包含新创建的 keychain 原型任务的 id。请轮询获取任务 endpoint，或订阅流式接口，直到任务状态变为 SUCCEEDED，然后将该 ID 作为 input_task_id 传递给构建 endpoint。

失败模式

Name
400 - Bad Request
Description
请求无法被接受。常见原因包括：
- 缺少参数：image_url 为必填项。
- 图像格式无效：提供的 image_url 不是受支持的格式（.jpg、.jpeg、.png、.webp）。
- 图像尺寸超出范围：图像过小、超过最大文件大小限制，或超过最大像素数限制。
- URL 不可访问：无法下载 image_url（404 或 timeout）。
- Data URI 无效：base64 字符串格式有误。
- 刻印文字过长：name_text 超过 10 个字符。此类请求会被直接拒绝而非截断处理，因此你不会因刻印了被截短名字的钥匙扣而被扣费。
- 内容被标记：输入图像被 NSFW 或知识产权 moderation 标记，或 name_text 刻印内容被 NSFW moderation 标记。刻印文字仅会进行 NSFW 内容审查——知识产权审查仅适用于图像。
Name
401 - Unauthorized
Description
Authentication 失败。请检查你的 API key。
Name
402 - Payment Required
Description
credits 不足，无法执行此任务。
Name
429 - Too Many Requests
Description
你已超出速率限制。

Request

POST

/openapi/creative-lab/keychain/v1/prototype

# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "name_text": "Luna"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Prototype example

Start with a source photo, then generate the prototype image used by the keychain build stage.

Source photo used as the Creative Lab Keychain input — Prototype input

Creative Lab Keychain prototype output generated from the source photo — Prototype output

POST/openapi/creative-lab/keychain/v1/build

创建 Keychain 构建任务

从一个已成功的原型任务生成最终可用于 3D 打印的 keychain 徽章。构建过程会对原型的彩色概念图运行深度图浮雕（depth-map relief）流水线，并按你所要求的格式输出单个 mesh 产物。响应结构请参见 Keychain 构建任务对象。

参数

Name
input_task_id
Type
string
必选
Description
通过同一个 OpenAPI endpoint 创建的原型任务的任务 ID。该原型必须使用相同的 API key 创建，必须已达到 SUCCEEDED 状态，并且必须恰好生成了一张候选图片。
通过 webapp 创建的原型任务不被接受——构建 endpoint 只接受由 POST /openapi/creative-lab/keychain/v1/prototype 生成的原型任务，其他来源一律返回 404 拒绝。
Name
name
Type
string
Description
可选的任务名称，用于展示。最多 100 个字符。

`options`

浮雕 geometry 的可选调节参数。每个字段都有合理的默认值——只需发送你想要覆盖的字段。

Name
badge_shape
Type
string
默认值 circle
Description
keychain 徽章的外轮廓形状。可选值：
- circle（默认）
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
默认值 40
Description
keychain 的外接正方形边长，单位为毫米。范围：(0, 400]。
Name
relief_height_mm
Type
number
默认值 2.2
Description
浮雕相对底面的最大高度，单位为毫米。范围：[0, 20]。
Name
relief_offset_mm
Type
number
默认值 0
Description
在挤出之前应用于浮雕的垂直偏移量，单位为毫米。范围：[0, 20]。
Name
base_thickness_mm
Type
number
默认值 0.1
Description
浮雕背面平整底板的厚度，单位为毫米。范围：[0, 20]。
Name
has_closed_back
Type
boolean
默认值 true
Description
徽章背面是否封闭为一个密闭表面。设为 false 则为开放式外壳。
Name
relief_curve
Type
string
默认值 linear
Description
将深度图数值映射到浮雕高度的转换曲线。可选值：
- linear（默认）
- gamma
- s-curve
Name
curve_param
Type
number
默认值 1.0
Description
转换曲线的形状参数（仅当 relief_curve 为 gamma 时有意义）。范围：(0, 10]。
Name
invert_depth
Type
boolean
默认值 false
Description
反转深度图的解读方式，使较暗区域产生更高的浮雕。
Name
smoothing
Type
number
默认值 0.24
Description
在提取浮雕之前应用于深度图的平滑强度。范围：[0, 10]。
Name
relief_scale
Type
number
默认值 1.0
Description
在 relief_height_mm 基础上叠加的垂直缩放倍数。范围：(0, 10]。
Name
depth_threshold
Type
number
默认值 0.1
Description
深度图数值的低通阈值；低于该值的部分将被截断为零。范围：[0, 1]。
Name
remove_background
Type
boolean
默认值 true
Description
在生成浮雕之前，自动移除原型概念图的背景。
这与原型任务中同名参数（默认 false）是分开的，后者控制的是原型图片本身是否以透明背景形式返回。
Name
export_resolution
Type
integer
默认值 512
Description
导出时使用的 mesh 分辨率。范围：[64, 2048]。

`output`

可选的输出格式选择器。默认值为 glb。

Name
format
Type
string
默认值 glb
Description
构建返回的产物包。可选值：
- glb（默认）——在 model_urls.glb 下返回单个 model.glb。
- obj ——将 model.obj + model.mtl + texture.png 打包为 zip，并在 model_urls.obj 下返回该包。
- zip ——将生成器产出的所有产物打包为 zip，并在 model_urls.bundle_zip 下返回该包。

返回值

响应中的 result 属性包含新创建的 keychain 构建任务的任务 id。轮询获取任务 endpoint 或订阅流式接口，直到任务达到 SUCCEEDED 状态，然后从 model_urls 中唯一的条目下载产物。

失败模式

Name
400 - Bad Request
Description
请求不可接受。常见原因：
- 缺少参数：input_task_id 是必需的。
- UUID 无效：input_task_id 不是有效的 UUID。
- 父任务未成功：所引用的原型任务尚未达到 SUCCEEDED 状态。
- 无候选图：原型任务成功了，但未生成候选图片。
- 选项超出范围：options 中的某个字段超出了其允许的范围或枚举集合。
Name
401 - Unauthorized
Description
身份验证失败。请检查你的 API key。
Name
402 - Payment Required
Description
credits 不足，无法执行此任务。
Name
404 - Not Found
Description
所引用的原型任务不存在、属于其他用户，或是通过 webapp 创建的（只有 API 模式下创建的原型任务才能链接到构建任务）。
Name
429 - Too Many Requests
Description
你已超出速率限制。

Request

POST

/openapi/creative-lab/keychain/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

该构建任务将选定的原型图片转换为可用于 3D 打印的 keychain 模型。

Creative Lab Keychain build model preview — Build model preview

GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

获取 Keychain 任务

根据有效的任务 id 获取原型（prototype）或构建（build）任务。URL 路径必须与任务所处的阶段一致——通过 /prototype/:id 获取构建任务将返回 404，反之亦然。

有关响应结构，请参阅 Keychain 原型任务对象和 Keychain 构建任务对象。

参数

Name
id
Type
path
Description
要获取的 keychain 任务的唯一标识符。

响应包含 keychain 任务对象。其具体结构取决于所请求的阶段。

Request

GET

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

DELETE/openapi/creative-lab/keychain/v1/(prototype|build)/:id

删除 Keychain 任务

取消一个 keychain 任务。如果任务仍处于 PENDING 状态，创建时消耗的 credits 将被退还。已经处于 IN_PROGRESS 状态的任务会被取消但不会退款（worker 可能已经在消耗 resources）。已经达到终止状态（SUCCEEDED、FAILED、CANCELED）的任务无法被取消。

URL 路径必须与任务所处的阶段相匹配 —— 对 /prototype/:buildId 执行 DELETE 将返回 404。

路径参数

Name
id
Type
path
Description
要取消的 keychain 任务的唯一标识符。

成功时返回 204 No Content，响应体为空。

失败模式

Name
400 - Bad Request
Description
该任务已处于终止状态，无法被取消。
Name
404 - Not Found
Description
该任务不存在、属于其他用户，或其所处阶段与 URL 路径不匹配。

Request

DELETE

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id/stream

流式获取 Keychain 任务

通过 Server-Sent Events（SSE）流式获取 keychain 任务的实时更新。 URL 路径必须与任务所处的阶段相匹配 —— 若在 /prototype/:buildId/stream 上打开流，会发出一条 status_code: 404 的 event: error payload 并关闭该流。

参数

Name
id
Type
path
Description
要进行流式获取的 keychain 任务的唯一标识符。

以 Server-Sent Events 的形式返回一系列 Keychain Prototype 或 Keychain Build 任务对象。每一帧都携带该阶段的完整任务对象 —— 与 Get endpoint 返回的形状相同 —— 因此当任务处于 PENDING 或 IN_PROGRESS 状态时，输出字段只是尚未被填充（为 null、[] 或 {}），且 finished_at 为 null。

Request

GET

/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

GET/openapi/creative-lab/keychain/v1/(prototype|build)

列出 Keychain 任务

获取单个阶段的 keychain 任务的分页列表。URL 路径决定阶段——/prototype 返回原型（prototype）任务； /build 返回构建（build）任务。另一个阶段的任务不会包含在任一响应中。

路径参数

Name
stage
Type
path
必选
Description
prototype 或 build 二选一。该集合仅返回阶段与 URL 匹配的任务—— 请求 /prototype 永远不会返回 build 任务，反之亦然。

查询参数

Name
page_num
Type
integer
默认值 1
Description
用于分页的页码。
Name
page_size
Type
integer
默认值 10
Description
每页条目数限制。允许的最大值为 100 条。
Name
sort_by
Type
string
默认值 -created_at
Description
用于排序的字段。可用值：
- +created_at：按创建时间升序排序。
- -created_at：按创建时间降序排序。

返回值

返回该阶段对应任务对象的分页列表——列出 /prototype 时返回 keychain 原型任务对象，列出 /build 时返回 keychain 构建任务对象。

Request

GET

/openapi/creative-lab/keychain/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

Keychain Prototype 任务对象

Keychain Prototype 任务对象是 Meshy 用于跟踪的一个工作单元，用于从源照片生成彩色的概念图像。该阶段的输出会通过 input_task_id 链接到构建阶段。

属性

Name
id
Type
string
Description
任务的唯一标识符。虽然我们在实现细节上使用 k-可排序的 UUID 作为任务 id，但你不应该对 id 的格式做任何假设。
Name
type
Type
string
Description
任务的类型。此值为 creative-lab-keychain-prototype。
Name
name
Type
string
Description
创建任务时提供的任务名称。如果未提供名称，则为空字符串。
Name
name_text
Type
string
Description
应用于此钥匙扣的刻字内容，经过修剪和去除不可见格式字符后的结果。如果创建任务时未提供 name_text，则该字段不存在。你可以将其与你发送的内容进行比对，以确认文本在你的 HTTP 客户端编码过程中未被破坏。
Name
status
Type
string
Description
任务的状态。可能的值为 PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED 之一。
Name
progress
Type
integer
Description
任务的进度。如果任务尚未开始，此属性将为 0。一旦任务成功，此值将变为 100。
Name
created_at
Type
timestamp
Description
任务创建时的时间戳，单位为毫秒。
时间戳表示自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。例如，2023 年 9 月 1 日星期五格林尼治标准时间下午 12:00:00 表示为 1693569600000。这适用于 Meshy API 中的所有时间戳。
Name
started_at
Type
timestamp
Description
任务开始时的时间戳，单位为毫秒。如果任务尚未开始，此属性将为 0。
Name
finished_at
Type
timestamp
Description
任务完成时的时间戳，单位为毫秒。如果任务尚未完成，此属性将为 0。
Name
expires_at
Type
timestamp
Description
任务结果过期时的时间戳，单位为毫秒。
Name
preceding_tasks
Type
integer
Description
排在前面的任务数量。
仅当任务状态为 PENDING 时，此字段的值才有意义。
Name
task_error
Type
object
Description
失败任务的错误详情。有关完整的 task_error 对象参考，请参阅错误。
Name
consumed_credits
Type
integer
Description
此任务消耗的 credits 数量。当任务状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时会显示此值。对于 FAILED 的任务，此值返回 0（失败时 credits 会被退还）。
Name
image_urls
Type
array of strings
Description
此原型任务生成的概念图像候选项的可下载 URL。目前 API 始终只返回一个候选项；该字段设计为数组，是为了让未来版本能够在不产生破坏性变更的情况下提供多个候选项。

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "name_text": "Luna",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

钥匙扣构建任务对象

钥匙扣构建任务对象是 Meshy 跟踪的一个工作单元，用于从已成功的原型任务生成最终的 3D 钥匙扣 mesh。构建过程会对原型的概念图运行深度图浮雕流水线，并按调用方请求的格式发布单个 mesh 产物。

属性

Name
id
Type
string
Description
任务的唯一标识符。
Name
type
Type
string
Description
任务的类型。值为 creative-lab-keychain-build。
Name
name
Type
string
Description
创建任务时提供的任务名称。如果未提供名称，则为空字符串。
Name
status
Type
string
Description
任务的状态。可能的值为 PENDING、IN_PROGRESS、SUCCEEDED、FAILED、CANCELED 之一。
Name
progress
Type
integer
Description
任务的进度。如果任务尚未开始，此属性将为 0。任务成功后，此值将变为 100。
Name
created_at
Type
timestamp
Description
任务创建时的时间戳，单位为毫秒。
Name
started_at
Type
timestamp
Description
任务开始时的时间戳，单位为毫秒。
Name
finished_at
Type
timestamp
Description
任务完成时的时间戳，单位为毫秒。
Name
expires_at
Type
timestamp
Description
任务结果过期时的时间戳，单位为毫秒。
Name
preceding_tasks
Type
integer
Description
排在前面的任务数量。仅当状态为 PENDING 时才有意义。
Name
task_error
Type
object
Description
失败任务的错误详情。完整的 task_error 对象参考请见 Errors。
Name
consumed_credits
Type
integer
Description
此任务消耗的 credits 数量。对于 FAILED 任务，返回 0（失败时会退还 credits）。
Name
model_urls
Type
object
Description
生成产物的可下载 URL，以产物名称作为键。始终恰好包含一个条目——即通过构建请求的 output.format 所指定的格式。该键与所请求的格式相匹配：
- Name
  glb
  Type
  string
  Description
  GLB 文件的可下载 URL。当 output.format 为 glb（默认值）时存在。
- Name
  obj
  Type
  string
  Description
  指向包含 model.obj、model.mtl 和 texture.png 的 zip 压缩包的可下载 URL。当 output.format 为 obj 时存在。
- Name
  bundle_zip
  Type
  string
  Description
  指向生成器输出的所有产物的 zip 压缩包的可下载 URL。当 output.format 为 zip 时存在。

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}