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

创建冰箱贴 Build 任务

根据已成功的 prototype 任务生成最终的可 3D 打印冰箱贴。build 会对该 prototype 的彩色概念图运行深度图浮雕（relief）流水线，并按你所要求的格式输出单个 mesh 产物。响应结构请参阅 冰箱贴 Build 任务对象。

参数

  • Name
    input_task_id
    Type
    string
    必选
    Description

    通过同一 OpenAPI endpoint 创建的 prototype 任务的任务 ID。该 prototype 必须使用相同的 API key 创建，必须已达到 SUCCEEDED 状态，并且必须仅生成了一张候选图片。

    通过 webapp 创建的 prototype 任务不被接受——build endpoint 只接受由 POST /openapi/creative-lab/fridge-magnet/v1/prototype 生成的 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

    在生成浮雕之前，自动移除 prototype 概念图的背景。

    这与同名的 prototype 参数（默认 false）是独立的，后者控制 prototype 图片本身是否以透明形式返回。

  • Name
    export_resolution
    Type
    integer
    默认值 512
    Description

    导出时使用的 mesh 分辨率。范围：[64, 2048]。

output

可选的线格式（wire-format）选择器。默认值为 glb。

  • Name
    format
    Type
    string
    默认值 glb
    Description

    build 返回的产物包。可用取值：

    • glb（默认）——在 model_urls.glb 下返回单个 model.glb。
    • obj —— 将 model.obj + model.mtl + texture.png 打包为 zip，并在 model_urls.obj 下返回该包。
    • zip —— 将生成器输出的所有产物打包为 zip，并在 model_urls.bundle_zip 下返回该包。

返回值

响应中的 result 属性包含新创建的冰箱贴 build 任务的任务 id。轮询 获取任务 endpoint，或订阅流式接口，直到任务达到 SUCCEEDED 状态，然后从 model_urls 中的单个条目下载产物。

失败模式

  • Name
    400 - Bad Request
    Description

    请求不可接受。常见原因：

    • 缺少参数：input_task_id 为必填项。
    • UUID 无效：input_task_id 不是有效的 UUID。
    • 父任务未成功：所引用的 prototype 任务尚未达到 SUCCEEDED 状态。
    • 无候选图：prototype 任务成功但未生成候选图片。
    • 选项超出范围：options 中的某个字段超出了允许的范围或枚举集合。
  • Name
    401 - Unauthorized
    Description

    身份验证失败。请检查你的 API key。

  • Name
    402 - Payment Required
    Description

    credits 不足以执行此任务。

  • Name
    404 - Not Found
    Description

    所引用的 prototype 任务不存在、属于其他用户，或是通过 webapp 创建的（只有 API 模式下的 prototype 任务才能串联进入 build）。

  • 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 示例
build 任务会将所选的 prototype 图片转换为可 3D 打印的冰箱贴模型。
Creative Lab Fridge Magnet build model preview
Build 模型预览
GET/openapi/creative-lab/fridge-magnet/v1/(prototype|build)/:id

获取冰箱贴任务

根据有效的任务 id 获取原型（prototype）或构建（build）任务。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 状态的任务会被取消，但不会退还 credits（因为工作进程可能已经在消耗资源）。已经到达终止状态 （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 打开流会发出单个 event: error payload，其中包含 status_code: 404，随后关闭该流。

参数

  • Name
    id
    Type
    path
    Description

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

返回值

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

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.
// 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-可排序的 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

    任务的 progress。如果任务尚未开始，此属性值为 0。一旦任务成功，此值将变为 100。

  • Name
    created_at
    Type
    timestamp
    Description

    任务创建时的时间戳，以毫秒为单位。

    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

    任务开始时的时间戳，以毫秒为单位。如果任务尚未开始，此属性值为 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

    此任务消耗的 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。该构建任务会在原型的概念图上运行深度图浮雕（relief）流水线，并按照调用方请求的格式发布单个 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

    此任务消耗的 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=***"
  }
}