Creative Lab — Keychain API

将源照片转换为可3D打印的钥匙扣徽章——一种徽章形状的彩色深度浮雕——分为两个阶段：原型阶段从您的输入照片生成彩色概念图像，然后构建阶段将该概念图像转换为浮雕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 传递给构建 endpoint 作为 input_task_id。

失败模式

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
积分不足，无法执行此任务。
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"
}

原型示例

从源照片开始，然后生成 keychain 构建阶段使用的原型图像。

从源照片生成的 Creative Lab Keychain 原型输出 — 原型输出

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

创建钥匙链构建任务

从成功的原型任务生成最终的3D可打印钥匙链奖章。构建在原型的彩色概念图像上运行深度图浮雕管道，并以您要求的格式提供一个mesh工件。请参阅钥匙链构建任务对象以获取响应结构。

参数

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.glb，位于model_urls.glb下。
- obj — 压缩model.obj + model.mtl + texture.png并返回包，位于model_urls.obj下。
- zip — 压缩生成器发出的每个工件并返回包，位于model_urls.bundle_zip下。

响应的result属性包含新创建的钥匙链构建任务的任务id。轮询获取任务endpoint或订阅流直到任务达到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
积分不足以执行此任务。
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"
}

构建示例

构建任务将选定的原型图像转换为3D可打印的钥匙链模型。

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

检索 Keychain 任务

根据有效的任务 id 检索原型或构建任务。URL 路径必须与任务的阶段匹配——通过 /prototype/:id 获取的构建任务会返回 404，反之亦然。

请参阅 Keychain 原型任务对象和 Keychain 构建任务对象以了解响应结构。

参数

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

响应包含 keychain 任务对象。形状取决于请求的阶段。

请求

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}"

原型响应

{
  "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=***"
  ]
}

构建响应

{
  "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 状态，创建时消耗的积分将被退还。已经 IN_PROGRESS 的任务会被取消但不退款（工作者可能已经在消耗 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 任务

通过服务器发送事件 (SSE) 流式传输 Keychain 任务的实时更新。URL 路径必须与任务的阶段匹配——在 /prototype/:buildId/stream 打开流会发出一个 event: error 负载，状态码为 404，并关闭流。

参数

Name
id
Type
path
Description
要流式传输的 Keychain 任务的唯一标识符。

返回值

返回 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 返回原型任务；/build 返回构建任务。来自其他阶段的任务不包含在任何响应中。

路径参数

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

查询参数

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 构建任务对象。

请求

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}"

响应（列出原型任务）

[
  {
    "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 日星期五下午 12:00:00 GMT 表示为 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 对象参考见 Errors。
Name
consumed_credits
Type
integer
Description
此任务消耗的积分数量。当任务状态为 PENDING、IN_PROGRESS 或 SUCCEEDED 时存在。对于 FAILED 任务返回 0（失败时积分会被退还）。
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
此任务消耗的积分数量。对于 FAILED 任务返回 0（失败时积分会被退还）。
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=***"
  }
}