Creative Lab — 冰箱贴 API

将您的照片转换为定制冰箱贴——一个带有平坦磁性背面、尺寸适合冰箱的圆角矩形彩色浮雕——分为两个 阶段：原型（prototype） 阶段根据您输入的照片生成彩色概念图，然后 构建（build） 阶段 将该概念图转换为浮雕 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 作为 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/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"
}
Prototype example
Start with a source photo, then generate the prototype image used by the fridge magnet build stage.
Source landscape photo used as the Creative Lab Fridge Magnet input
Prototype input
Creative Lab Fridge Magnet prototype output generated from the source photo
Prototype output
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

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

  • 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_urls.glb 下返回单个 model.glb 文件。
    • obj ——将 model.obj + model.mtl + texture.png 打包为 zip，并在 model_urls.obj 下返回该压缩包。
    • zip ——将生成器输出的所有产物打包为 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

    身份验证失败。请检查你的 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/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"
}
Build example
The build task turns the selected prototype image into a 3D-printable fridge magnet model.
Creative Lab Fridge Magnet build model preview
Build model preview
GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id

获取冰箱贴任务

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

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

参数

  • Name
    id
    Type
    path
    Description

    要获取的冰箱贴任务的唯一标识符。

返回值

响应包含冰箱贴任务对象。其结构取决于所请求的阶段。

Request

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

Prototype Response

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

Build Response

{
  "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 状态的任务将被取消，但不予退款（此时 worker 可能已经在消耗资源）。已经到达终止状态 （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

流式获取冰箱贴任务

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

参数

  • Name
    id
    Type
    path
    Description

    要流式获取的冰箱贴任务的唯一标识符。

返回

以 Server-Sent Events 的形式返回一个由 冰箱贴原型 或 冰箱贴构建任务对象组成的流。 每一帧都携带该阶段的完整任务对象 —— 与 Get endpoint 返回的结构相同 —— 因此当任务处于 PENDING 或 IN_PROGRESS 状态时，输出字段只是尚未被填充（为 null、[] 或 {}）， 且 finished_at 为 null。

Request

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

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

    分页大小限制。最大允许值为 100 项。

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

Fridge Magnet 原型任务对象

Fridge Magnet 原型任务对象是 Meshy 跟踪的一个工作单元，用于从源照片生成一张彩色概念图（concept image）。此阶段的输出会通过 input_task_id 链接到构建阶段。

属性

  • Name
    id
    Type
    string
    Description

    任务的唯一标识符。虽然我们在实现细节上使用 k-可排序的 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

    任务创建时的 timestamp，单位为毫秒。

    timestamp 表示自 1970 年 1 月 1 日 UTC 起经过的毫秒数，遵循 RFC 3339 标准。 例如，2023 年 9 月 1 日星期五 GMT 时间 12:00:00 PM 表示为 1693569600000。这适用于 Meshy API 中的所有 timestamp。

  • Name
    started_at
    Type
    timestamp
    Description

    任务开始时的 timestamp，单位为毫秒。如果任务尚未开始，该属性值为 0。

  • Name
    finished_at
    Type
    timestamp
    Description

    任务完成时的 timestamp，单位为毫秒。如果任务尚未完成，该属性值为 0。

  • Name
    expires_at
    Type
    timestamp
    Description

    任务结果过期时的 timestamp，单位为毫秒。

  • 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 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

    任务创建时间的 timestamp（毫秒）。

  • Name
    started_at
    Type
    timestamp
    Description

    任务开始时间的 timestamp（毫秒）。

  • Name
    finished_at
    Type
    timestamp
    Description

    任务完成时间的 timestamp（毫秒）。

  • Name
    expires_at
    Type
    timestamp
    Description

    任务结果过期时间的 timestamp（毫秒）。

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