Creative Lab — Keychain API

将一张源照片转换为可 3D 打印的钥匙扣挂饰——一个徽章造型的彩色浮雕深度图——共分两个阶段：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 彩色化为 keychain 就绪概念图的源照片。目前支持 .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
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 字符串格式不正确。
- 内容被标记：输入图像被 NSFW 或知识产权 moderation 标记。
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' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

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 打印的钥匙链徽章。构建过程会对原型的彩色概念图运行深度图浮雕流水线，并按照你指定的格式输出单个 mesh 制品。响应结构请参见 The Keychain Build Task Object。

参数

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
钥匙链徽章的外轮廓形状。可选值：
- circle（默认）
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
默认值 40
Description
钥匙链外接正方形的边长，单位为毫米。取值范围：(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 属性包含新创建的钥匙链构建任务的任务 id。请轮询 Get a Task endpoint，或订阅 stream，直到任务达到 SUCCEEDED 状态，然后从 model_urls 中唯一的条目下载制品。

失败情形

Name
400 - Bad Request
Description
请求不可接受。常见原因包括：
- 缺少参数：input_task_id 为必填项。
- UUID 无效：input_task_id 不是有效的 UUID。
- 父任务未成功：所引用的原型任务尚未达到 SUCCEEDED 状态。
- 无候选图：原型任务已成功，但未生成任何候选图片。
- 选项超出范围：options 中的某个字段超出了允许的范围或枚举集合。
Name
401 - Unauthorized
Description
Authentication 失败。请检查你的 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

The build task converts the selected prototype image into a 3D-printable keychain model.

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 获取 build 任务会返回 404，反之亦然。

响应结构请参阅 The Keychain Prototype Task Object 和 The Keychain Build Task Object。

参数

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 可能已经在消耗资源）。已经达到终止状态（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 打开流，将只返回一条 event: error payload，其中 status_code: 404，随后连接会关闭。

参数

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

以 Server-Sent Events 的形式返回一系列 Keychain Prototype 或 Keychain Build 任务对象。对于处于 PENDING 或 IN_PROGRESS 状态的任务，响应流中只会包含必要的 progress 和 status 字段。

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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
每页数量限制。最大允许值为 50 项。
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 原型任务对象

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

属性

Name
id
Type
string
Description
任务的唯一标识符。虽然我们在实现细节上使用 k-sortable UUID 作为任务 id，但你不应对 id 的格式做任何假设。
Name
type
Type
string
Description
任务的类型。该值为 creative-lab-keychain-prototype。
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
任务创建时的时间戳，以毫秒为单位。
时间戳表示自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。例如，2023 年 9 月 1 日星期五 GMT 时间 12:00:00 PM 表示为 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": "",
  "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 构建任务对象

Keychain 构建任务对象是 Meshy 用来跟踪从成功完成的原型任务生成最终 3D keychain 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=***"
  }
}