Creative Lab — 方塊小人 API

分兩個階段將一張來源照片轉換為方塊風格的可收藏 3D 小人 Q 版手辦： 原型（prototype） 階段會根據你的輸入照片產生一張風格化的概念圖，然後 構建（build） 階段會將該概念圖轉換為帶貼圖的 3D 模型。這兩個階段透過 input_task_id 關聯在一起。

POST /openapi/creative-lab/brick-figure/v1/prototype
POST /openapi/creative-lab/brick-figure/v1/build

POST/openapi/creative-lab/brick-figure/v1/prototype

Create a Brick Figure Prototype Task

根據來源照片生成單張方塊風格的概念圖。回傳的任務 ID 即為傳遞給構建 endpoint 的 input_task_id。回應結構請參閱方塊小人原型任務物件。

參數

Name
image_url
Type
string
必選
Description
Meshy 用於風格化為方塊小人的來源照片。目前支援 .jpg、.jpeg、.png 和 .webp 格式。
提供圖片的方式有兩種：
- 可公開存取的 URL：一個可從公共網際網路存取的 URL。
- Data URI：圖片的 base64 編碼 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 形式回傳，方便你將主體合成到任意背景中。

回傳值

回應中的 result 屬性包含新建立的方塊小人原型任務的 id。輪詢取得任務 endpoint 或訂閱 stream，直到任務狀態變為 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
403 - Forbidden
Description
輸入圖片因涉嫌智慧財產權侵權被標記。
Name
429 - Too Many Requests
Description
你已超出速率限制。

Request

POST

/openapi/creative-lab/brick-figure/v1/prototype

# Stage 1: generate a brick-style concept image
curl https://api.meshy.ai/openapi/creative-lab/brick-figure/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": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

POST/openapi/creative-lab/brick-figure/v1/build

建立方塊小人建置任務

從一個已成功的原型任務生成最終的帶紋理 3D 方塊小人。建置過程執行與 Image to 3D 相同的影象生成 3D 流水線，因此回應物件格式和輸出 URL 清單完全一致。回應結構請參考方塊小人建置任務物件。

參數

Name
input_task_id
Type
string
必選
Description
透過同一個 OpenAPI endpoint 建立的原型任務的任務 ID。該原型任務必須使用相同的 API 金鑰建立，必須已達到 SUCCEEDED 狀態，並且必須恰好生成了一張候選圖片。
透過 webapp 建立的原型任務不被接受——建置 endpoint 僅接受由 POST /openapi/creative-lab/brick-figure/v1/prototype 生成的原型任務，其他任何來源都會回傳 404。
Name
name
Type
string
Description
可選的任務名稱，用於顯示目的。最多 100 個字元。

回傳值

回應中的 result 屬性包含新建立的方塊小人建置任務的 id。輪詢取得任務 endpoint 或訂閱資料流，直到任務達到 SUCCEEDED 狀態，然後從 model_urls.glb 下載帶紋理的 GLB（如果你的下游流水線更適合 OBJ，也可以從 model_urls.obj 和 model_urls.mtl 下載 OBJ + MTL 檔案對）。

失敗模式

Name
400 - Bad Request
Description
請求不可接受。常見原因：
- 缺少參數：input_task_id 是必需的。
- 無效的 UUID：input_task_id 不是有效的 UUID。
- 父任務未成功：所參照的原型任務尚未達到 SUCCEEDED 狀態。
- 無候選圖片：原型任務已成功，但未生成任何候選圖片。
Name
401 - Unauthorized
Description
身份驗證失敗。請檢查你的 API 金鑰。
Name
402 - Payment Required
Description
執行此任務所需的積分不足。
Name
404 - Not Found
Description
所參照的原型任務不存在、屬於其他使用者，或是透過 webapp 建立的（只有 API 模式下建立的原型任務才能連結到建置任務）。
Name
429 - Too Many Requests
Description
你已超出速率限制。

Request

POST

/openapi/creative-lab/brick-figure/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

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

獲取方塊小人任務

透過有效的任務 id 獲取原型或構建任務。URL 路徑必須與任務所處的階段匹配 —— 若透過 /prototype/:id 獲取構建任務，將返回 404，反之亦然。

有關回應結構，請參閱方塊小人原型任務物件和方塊小人構建任務物件。

參數

Name
id
Type
path
Description
要獲取的方塊小人任務的唯一識別碼。

回傳值

回應包含方塊小人任務物件。其結構取決於請求的是哪個階段。

Request

GET

/openapi/creative-lab/brick-figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-brick-figure-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-brick-figure-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": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ]
}

DELETE/openapi/creative-lab/brick-figure/v1/(prototype|build)/:id

刪除方塊小人任務

取消一個方塊小人任務。如果任務仍處於 PENDING 狀態，建立時消耗的積分將被退還。已處於 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/brick-figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/brick-figure/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

GET/openapi/creative-lab/brick-figure/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 的形式回傳一個由 Brick Figure Prototype 或 Brick Figure Build 任務物件組成的串流。每一帧都帶有該階段完整的任務物件——與 Get endpoint 回傳的結構相同—— 因此當任務處於 PENDING 或 IN_PROGRESS 狀態時，輸出欄位只是尚未被填入資料（為 null、[] 或 {}），且 finished_at 為 null。

Request

GET

/openapi/creative-lab/brick-figure/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/brick-figure/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-brick-figure-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ]
}

GET/openapi/creative-lab/brick-figure/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/brick-figure/v1/prototype

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

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

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-brick-figure-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=***"
    ]
  }
]

Brick Figure 原型任務物件

Brick Figure 原型任務物件是 Meshy 用來追蹤的一個工作單元，用於從來源照片產生方塊風格的概念圖。此階段的輸出會透過 input_task_id 連結到建構階段。

屬性

Name
id
Type
string
Description
任務的唯一識別碼。雖然我們在實作細節上使用 k-可排序 UUID 作為任務 id，但你不應對 id 的格式做任何假設。
Name
type
Type
string
Description
任務的類型。該值為 creative-lab-brick-figure-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
任務建立時間的時間戳，以毫秒為單位。
時間戳表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數，遵循 RFC 3339 標準。例如，2023 年 9 月 1 日星期五 GMT 時間下午 12:00:00 表示為 1693569600000。這適用於 Meshy API 中的所有時間戳。
Name
started_at
Type
timestamp
Description
任務開始時間的時間戳，以毫秒為單位。如果任務尚未開始，此屬性將為 null。
Name
finished_at
Type
timestamp
Description
任務完成時間的時間戳，以毫秒為單位。如果任務尚未完成，此屬性將為 null。
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
此任務消耗的積分數量。當任務狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時會顯示該值。對於 FAILED 任務，返回 0（失敗時積分會退還）。
Name
image_urls
Type
array of strings
Description
此原型任務產生的概念圖候選項的可下載 URL。目前 API 始終只返回一個候選項；該欄位是陣列的原因是為了讓未來版本能夠在不產生破壞性變更的情況下呈現多個候選項。

Example Brick Figure Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-brick-figure-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=***"
  ]
}

Brick Figure Build 任務物件

Brick Figure Build 任務物件是 Meshy 用來追蹤工作進度的一個工作單元，用於從已成功的原型任務生成帶貼圖的3D 方塊小人。它執行的是 Image to 3D 所使用的相同影象生成 3D 流程，因此輸出欄位與該 endpoint 的任務物件一致。

屬性

Name
id
Type
string
Description
任務的唯一識別碼。
Name
type
Type
string
Description
任務的類型。數值為 creative-lab-brick-figure-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
該任務消耗的 credits 數量。對於 FAILED 的任務會回傳 0（失敗時會退還 credits）。
Name
prompt
Type
string
Description
對於 brick figure build 始終為空。此欄位的存在是為了與 Image to 3D 所使用的共享 V2ImageTo3DTaskResponse 結構保持跨 endpoint 相容。
Name
negative_prompt
Type
string
Description
對於 brick figure build 始終為空。此欄位的存在是為了跨 endpoint 相容。
Name
texture_prompt
Type
string
Description
對於 brick figure build 始終為空。此欄位的存在是為了跨 endpoint 相容。
Name
texture_image_url
Type
string
Description
對於 brick figure build 始終為空。此欄位的存在是為了跨 endpoint 相容。
Name
model_urls
Type
object
Description
生成的 3D 模型的可下載 URL。brick figure build 會輸出一個帶貼圖的 GLB，以及適用於更偏好 Wavefront OBJ 的流程的 OBJ + MTL 組合。該欄位的結構與 Image to 3D 的 model_urls 物件一致，因此未來新增格式時不會造成破壞性變更。
- Name
  glb
  Type
  string
  Description
  指向帶貼圖的 GLB 檔案的可下載 URL。
- Name
  obj
  Type
  string
  Description
  指向 Wavefront OBJ 檔案（geometry + UV）的可下載 URL。
- Name
  mtl
  Type
  string
  Description
  指向 OBJ 配套的 MTL material 檔案的可下載 URL。請將其與 obj 以及 texture_urls[0].base_color 中的條目配合使用。
Name
thumbnail_url
Type
string
Description
指向模型檔案縮圖（thumbnail）影像的可下載 URL。
Name
texture_urls
Type
array
Description
該任務生成的 texture URL 物件陣列。目前僅包含一個帶有基礎顏色貼圖的物件。
- Name
  base_color
  Type
  string
  Description
  指向基礎顏色貼圖影像的可下載 URL。

Example Brick Figure Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-brick-figure-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": 30,
  "prompt": "",
  "negative_prompt": "",
  "texture_prompt": "",
  "texture_image_url": "",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.mtl?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/preview.png?Expires=***",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/texture_0.png?Expires=***"
    }
  ]
}