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 原型任务对象。

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

参数

Name
image_url
Type
string
必选
Description
供 Meshy 着色为 keychain 可用概念图的源照片。目前支持 .jpg、.jpeg、.png 和 .webp 格式。
最大文件大小：20 MB。
提供图像有两种方式：
- 公开可访问的 URL：可从公共互联网访问的 URL。
- Data URI：图像的 base64 编码 data URI。data URI 示例：data:image/jpeg;base64,<your base64-encoded image data>。
Name
name
Type
string
Description
用于显示的可选任务名称。最多 100 个字符。
该名称用于在你的仪表盘和任务列表中标注此任务，不会被刻印在 keychain 上——如需刻印请使用 name_text。
Name
name_text
Type
string
Description
要刻印在 keychain 上的文字，例如宠物或人的名字。最多 10 个字符，按 Unicode 字符而非字节计数，因此 10 个字符的中文、日文或韩文名字也可以接受。省略此参数将生成不带刻印的 keychain。
文本在使用前会去除首尾空白并移除不可见的格式字符。处理后的值会作为原型任务对象上的 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 个字符。请求会被拒绝而非被截断，因此你绝不会为刻印了被截短名字的 keychain 付费。
- 内容被标记：输入图像被 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
你已超出速率限制。

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

创建 Keychain 构建任务

根据一个已成功完成的 prototype 任务，生成最终可供 3D 打印的 keychain 挂件。构建过程会在 prototype 任务生成的彩色概念图上运行深度图浮雕管线，并以你指定的格式输出单个 mesh 产物。响应结构请参考 The Keychain Build Task Object。

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

该构建任务会将所选 prototype 图像转换为一个可供 3D 打印的 keychain 模型。

Creative Lab Keychain build model preview — Build model preview

参数

Name
input_task_id
Type
string
必选
Description
通过同一个 OpenAPI endpoint 创建的 prototype 任务的任务 ID。该 prototype 任务必须使用相同的 API key 创建，必须已经达到 SUCCEEDED 状态，并且必须恰好生成了一张候选图像。
通过 webapp 创建的 prototype 任务不被接受——构建 endpoint 只接受由 POST /openapi/creative-lab/keychain/v1/prototype 产生的 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
在生成浮雕之前，自动移除 prototype 概念图的背景。
这与 prototype 中同名参数（默认值为 false）是独立的，后者控制的是 prototype 图像本身是否以透明背景返回。
Name
export_resolution
Type
integer
默认值 512
Description
导出时使用的 mesh 分辨率。范围：[64, 512]。geometry 是基于 512px 的深度图构建的，因此更精细的网格只会增加面数，而不会增加细节。

`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。请轮询 Get a Task endpoint 或订阅 stream，直到任务达到 SUCCEEDED 状态，然后从 model_urls 中唯一的条目下载产物。

失败模式

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

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

获取 Keychain 任务

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

有关响应结构，请参阅 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=***"
  }
}

参数

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

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

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。

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).

路径参数

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

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

失败模式

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

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 并关闭该流。

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

参数

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

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

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

列出 Keychain 任务

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

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

路径参数

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

Keychain Prototype 任务对象

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

属性

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

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 始终只返回一个候选项；该字段设计为数组，是为了让未来版本能够在不产生破坏性变更的情况下提供多个候选项。

钥匙扣构建任务对象

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

属性

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

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 时存在。