Creative Lab — 冰箱贴 API

将您的照片转换为定制的冰箱贴——一种带有平坦磁性背面的圆角矩形彩色深度浮雕，适合冰箱大小——分为两个阶段：原型从您的输入照片生成彩色概念图像，然后构建将该概念图像转换为浮雕3D模型。这两个阶段通过 input_task_id 连接。

POST /openapi/creative-lab/fridge-magnet/v1/prototype
POST /openapi/creative-lab/fridge-magnet/v1/build

POST/openapi/creative-lab/fridge-magnet/v1/prototype

创建冰箱贴原型任务

从源照片生成单个彩色概念图像。返回的任务 ID 是您传递给构建 endpoint 的 input_task_id。请参阅冰箱贴原型任务对象以获取响应结构。

参数

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
remove_background
Type
boolean
默认值 false
Description
当设置为 true 时，原型图像将作为背景移除的透明 RGBA PNG 返回，因此您可以将主体合成到任何背景上。
这仅控制此 endpoint 返回的图像。它与同名的构建选项（默认 true）分开，后者控制在浮雕之前的背景移除。

响应的 result 属性包含新创建的冰箱贴原型任务的任务 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/fridge-magnet/v1/prototype

# Stage 1: generate a colorized fridge magnet concept image
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/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": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9"
}

原型示例

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

POST/openapi/creative-lab/fridge-magnet/v1/build

创建冰箱贴构建任务

从成功的原型任务生成最终的3D可打印冰箱贴。构建在原型的彩色概念图像上运行深度图浮雕管道，并以您请求的格式提供单个mesh工件。请参阅冰箱贴构建任务对象以了解响应结构。

参数

Name
input_task_id
Type
string
必选
Description
通过此相同OpenAPI endpoint创建的原型任务的任务ID。原型必须使用相同的API key创建，必须达到SUCCEEDED，并且必须生成一个候选图像。
通过webapp创建的原型任务不被接受——构建endpoint仅接受由POST /openapi/creative-lab/fridge-magnet/v1/prototype生成的原型任务，并拒绝任何其他来源，返回404。
Name
name
Type
string
Description
用于显示的可选任务名称。最多100个字符。

`options`

用于浮雕几何的可选调优参数。每个字段都有一个合理的默认值——仅发送您想要覆盖的字段。

Name
badge_shape
Type
string
默认值 rounded-rect
Description
冰箱贴的轮廓剪影。可用值：
- circle
- rounded-rect (默认)
- hexagon
- shield
- star
Name
size_mm
Type
number
默认值 60
Description
冰箱贴的边界正方形边长，单位为毫米。范围：(0, 400]。
Name
relief_height_mm
Type
number
默认值 3.3
Description
基础上方的最大浮雕高度，单位为毫米。范围：[0, 20]。
Name
relief_offset_mm
Type
number
默认值 0
Description
在挤出之前应用于浮雕的垂直偏移，单位为毫米。范围：[0, 20]。
Name
base_thickness_mm
Type
number
默认值 2.0
Description
浮雕后面的平板底座厚度，单位为毫米。冰箱贴的默认值是较厚的2毫米底座——使磁铁有足够的厚度以抓住冰箱，而不会让浮雕感觉脆弱。范围：[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/fridge-magnet/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
    "options": {
      "badge_shape": "rounded-rect",
      "size_mm": 60,
      "relief_height_mm": 3.3
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0"
}

构建示例

构建任务将选定的原型图像转换为3D可打印的冰箱贴模型。

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

检索冰箱贴任务

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

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

参数

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

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

请求

GET

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

原型响应

{
  "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
  "type": "creative-lab-fridge-magnet-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543210000,
  "started_at": 1729543215000,
  "finished_at": 1729543242000,
  "expires_at": 1729802442000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

构建响应

{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

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

删除冰箱贴任务

取消一个冰箱贴任务。如果任务仍然是PENDING状态，创建时消耗的credits将被退还。已经处于IN_PROGRESS状态的任务将被取消且不退款（工作者可能已经在消耗Resources）。已经达到终止状态（SUCCEEDED、FAILED、CANCELED）的任务无法取消。

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

路径参数

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

成功时返回204 No Content，且主体为空。

失败模式

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

Request

DELETE

/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/prototype/01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

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

通过流式传输冰箱贴任务

通过服务器发送事件 (SSE) 流式传输冰箱贴任务的实时更新。 URL 路径必须与任务的阶段匹配——在 /prototype/:buildId/stream 打开流会发出一个 event: error payload，带有 status_code: 404 并关闭流。

参数

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

返回冰箱贴原型或冰箱贴构建任务对象的流作为服务器发送事件。对于 PENDING 或 IN_PROGRESS 任务，响应流将仅包含必要的 progress 和 status 字段。

请求

GET

/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fridge-magnet/v1/build/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

响应流

// 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": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}

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

列出冰箱贴任务

检索单个阶段的冰箱贴任务的分页列表。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 时为冰箱贴原型任务对象，列出 /build 时为冰箱贴构建任务对象。

Request

GET

/openapi/creative-lab/fridge-magnet/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
    "type": "creative-lab-fridge-magnet-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729543210000,
    "started_at": 1729543215000,
    "finished_at": 1729543242000,
    "expires_at": 1729802442000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

冰箱贴原型任务对象

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

属性

Name
id
Type
string
Description
任务的唯一标识符。虽然我们使用k-sortable UUID作为任务ID的实现细节，但您不应对ID的格式做任何假设。
Name
type
Type
string
Description
任务的类型。值为creative-lab-fridge-magnet-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 PM 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 Fridge Magnet Prototype Task Object

{
  "id": "01a3d8f1-8c2e-7d04-b223-3f3776a1c8c9",
  "type": "creative-lab-fridge-magnet-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543210000,
  "started_at": 1729543215000,
  "finished_at": 1729543242000,
  "expires_at": 1729802442000,
  "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-fridge-magnet-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 Fridge Magnet Build Task Object

{
  "id": "01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0",
  "type": "creative-lab-fridge-magnet-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729543250000,
  "started_at": 1729543258000,
  "finished_at": 1729543285000,
  "expires_at": 1729802485000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/01b4e9a2-9d3f-8e15-c334-4f4887b2d9d0/output/model.glb?Expires=***"
  }
}