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

    身份驗證失敗。請檢查你的 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 負載,並隨後關閉該串流。

參數

  • 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

    任務建立時的時間戳,單位為毫秒。

  • 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

    前置任務的數量。

  • Name
    task_error
    Type
    object
    Description

    失敗任務的錯誤詳情。完整的 task_error 物件參考請參見錯誤。

  • 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 冰箱貼網格的工作單元。該構建會在原型的概念圖上運行深度圖浮雕流水線,並按呼叫者請求的格式發布單個網格生成物。

屬性

  • 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 物件的完整參考,請參閱錯誤。

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