Creative Lab 可摺疊指尖玩具 API

透過一次任務將照片轉換為可直接列印、無需組裝的可摺疊指尖玩具。主體的輪廓會變成層層嵌套的同心圓環，可以壓扁收起，也可以拉伸展開。該玩具一次列印成型，無需組裝。

POST /openapi/creative-lab/fidget-collapsible/v1

與其他 Creative Lab 端點不同，此端點沒有單獨的原型階段和建構階段。沒有可供選擇的候選圖像，因此一次任務就能將照片轉換為 3D 模型。

該請求也沒有幾何體設定。網頁應用程式允許你設定尺寸、層數、間隙寬度、壁厚、擠出深度和凸起程度。每個 API 任務都對這些參數使用相同的預設值。

POST/openapi/creative-lab/fidget-collapsible/v1

建立一個 Collapsible Fidget 任務

根據一張照片生成一個可折疊（collapsible）的減壓玩具（fidget）模型。關於該任務的欄位，參見 The Collapsible Fidget task object。

每個任務消耗 6 個積分，且需要付費套餐。

Request

POST

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1 \
  -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"
}

參數

Name
image_url
Type
string
必選
Description
要轉換為可折疊減壓玩具的照片，可以是公開可存取的 URL，也可以是 data URI（data:image/jpeg;base64,<your base64-encoded image data>）。
圖片必須是 JPG、JPEG、PNG 或 WebP 檔案，大小不超過 20 MB。
主體的輪廓會變成一圈圈的環，因此一個具有清晰、閉合輪廓的主體效果最好。背景過於雜亂、存在多個獨立主體，或者形狀過細，都可能導致沒有足夠的區域來生成嵌套的壁結構。在這種情況下，任務會失敗。
Name
name
Type
string
Description
該任務的名稱，最多 100 個字元。它會在任務的 name 欄位中返回，Meshy 不會將其雕刻到模型上。名稱過長會返回 400。

返回值

result 欄位保存新任務的 ID。取得該任務或對其進行串流取得，直到 status 變為 SUCCEEDED。然後從 model_urls.stl 下載可列印的 STL 檔案。若想先預覽模型，可在 model_urls.glb 存在時從中下載 GLB 檔案。

失敗情形

Name
400 - Bad Request
Description
請求無法執行。例如：
- 缺少 image_url。
- 圖片不是 JPG、JPEG、PNG 或 WebP 檔案。
- 圖片過小、超過 20 MB，或超過最大像素數。
- Meshy 無法下載該圖片，例如因為該 URL 返回 404 或逾時。
- data URI 不是有效的 base64。
- 該圖片被標記為 NSFW（不適宜內容）。
錯誤訊息會說明具體問題。修復請求後重新發送。
Name
401 - Unauthorized
Description
API 金鑰缺失或無效。請檢查 Authorization 請求標頭。
Name
402 - Payment Required
Description
以下情況之一適用：
- 帳戶沒有足夠的積分。
- 該 API 金鑰、工作區或成員已達到其積分限額。
- 該帳戶處於免費套餐。
請檢查你的積分和套餐，然後重試。
Name
403 - Forbidden
Description
你的團隊開啟了 IP Filtering（IP 過濾） 功能，Meshy 將該圖片標記為涉及第三方智慧財產權。請發送你擁有使用權的圖片。
Name
429 - Too Many Requests
Description
達到了以下限制之一：
- 你發送的請求數超過了速率限制所允許的數量。請等待幾秒後重試。參見速率限制。
- 你排隊或正在執行的任務過多。請等待部分任務完成後重試。
- 在沒有積分的無限套餐下，你達到了無需積分即可執行的任務數量上限。請等待某個任務完成，或新增積分。
Name
500 - Internal Server Error
Description
Meshy 發生了伺服器錯誤，例如無法對圖片執行智慧財產權檢查。Meshy 不會建立該任務，並會退還已扣除的任何積分。請重試該請求。

GET/openapi/creative-lab/fidget-collapsible/v1/:id

取得 Collapsible Fidget 任務

返回一個 Collapsible Fidget 任務。僅返回透過此 endpoint 建立的任務。來自其他 Creative Lab endpoint 或在網頁應用程式中建立的任務會返回 404。

有關欄位說明，請參閱Collapsible Fidget 任務物件。

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

參數

Name
id
Type
path
Description
建立回應中的任務 ID。

返回值

Collapsible Fidget 任務物件。

失敗模式

Name
400 - Bad Request
Description
id 不是有效的任務 ID。請傳送建立回應中的 result ID。
Name
403 - Forbidden
Description
您的團隊已開啟 IP Filtering，且 Meshy 將該任務的圖片標記為涉及第三方智慧財產權。企業版（Enterprise）方案的團隊不會遇到此錯誤。請使用您擁有使用權的圖片建立任務。
Name
404 - Not Found
Description
您的帳戶下沒有此 ID 對應的 Collapsible Fidget 任務，或該任務並非透過此 endpoint 建立。請檢查該 ID。
Name
500 - Internal Server Error
Description
Meshy 無法執行智慧財產權檢查。請重試該請求。

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

刪除 Collapsible Fidget 任務

取消一個 Collapsible Fidget 任務。取消處於 PENDING 狀態的任務會退還其積分。處於 IN_PROGRESS 狀態的任務被取消時不會退款，因為已有工作行程開始處理該任務。處於最終狀態（SUCCEEDED、FAILED 或 CANCELED）的任務無法取消。

Request

DELETE

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

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

路徑參數

Name
id
Type
path
Description
要取消的任務的 ID。

回傳值

204 No Content，回應內容為空。

失敗情況

Name
400 - Bad Request
Description
以下情況之一：
- id 不是有效的任務 ID。請傳送建立回應中的 result ID。
- 該任務已處於最終狀態（SUCCEEDED、FAILED 或 CANCELED），因此無法取消。
Name
404 - Not Found
Description
你的帳戶下沒有此 ID 對應的 Collapsible Fidget 任務，或者該任務並非透過此 endpoint 建立。請檢查該 ID。

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

流式取得可折疊玩具任務

以伺服器發送事件（SSE）的形式流式取得可折疊玩具任務的更新。如果任務不存在，或者不是透過此 endpoint 建立的，流會發送一個 status_code: 404 的 error 事件，然後關閉。

Request

GET

/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (task not found, or not created through this endpoint)
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 following PENDING frame is shortened to the fields that change.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

參數

Name
id
Type
path
Description
建立回應中回傳的任務 ID。

回傳值

一個可折疊玩具任務物件的流。每個事件都包含完整的任務物件，與取得可折疊玩具任務回傳的內容一致。當任務處於 PENDING 或 IN_PROGRESS 狀態時，其輸出欄位仍為空（null、[] 或 {}），且 finished_at 為 null。

如果 IP 過濾阻止了任務結果的回傳，流會在該位置發送一個 error 事件，其中的 status_code 與透過 get 請求會回傳的狀態碼相同。

GET/openapi/creative-lab/fidget-collapsible/v1

取得 Collapsible Fidget 任務列表

分頁回傳你的 Collapsible Fidget 任務。僅包含透過此 endpoint 建立的任務。

Request

GET

/openapi/creative-lab/fidget-collapsible/v1

curl https://api.meshy.ai/openapi/creative-lab/fidget-collapsible/v1?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-fidget-collapsible",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123512000,
    "expires_at": 1729382712000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

查詢參數

Name
page_num
Type
integer
預設值 1
Description
要回傳的頁碼，範圍從 1 到 255。0 會回傳第一頁。超出 0 到 255 的值將回傳 400。
Name
page_size
Type
integer
預設值 10
Description
每頁任務數量，最多 100。101 到 255 之間的值會回傳 100 個任務，0 則使用預設值。超出 0 到 255 的值將回傳 400。
Name
sort_by
Type
string
預設值 -created_at
Description
排序方式。
可選值：
- -created_at：最新的排在最前
- +created_at：最舊的排在最前

回傳值

一個 Collapsible Fidget 任務物件陣列。

可折疊指尖陀螺（Collapsible Fidget）任務物件

Collapsible Fidget 任務會將一張照片轉換為可直接列印、無需組裝的可折疊指尖玩具模型。這是一個單階段任務，因此沒有可銜接的原型（prototype）任務。回應中不包含 Meshy 在生成過程中製作的輪廓（silhouette）。

屬性

Example Collapsible Fidget Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-fidget-collapsible",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123512000,
  "expires_at": 1729382712000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}

Name
id
Type
string
Description
任務 ID。請不要依賴其格式。
Name
type
Type
string
Description
任務類型，始終為 creative-lab-fidget-collapsible。
Name
name
Type
string
Description
你建立任務時傳送的 name，如果未傳送則為 ""。
Name
status
Type
string
Description
任務的狀態。
可用值：
- PENDING：在佇列中等待
- IN_PROGRESS：正在生成結果
- SUCCEEDED：最終狀態，附帶結果
- FAILED：最終狀態，原因見 task_error
- CANCELED：最終狀態，沒有結果
Name
progress
Type
integer
Description
已完成工作的百分比，範圍從 0 到 100。任務開始前為 0，成功時為 100。
Name
created_at
Type
timestamp
Description
任務建立的時間，採用 Unix 毫秒時間戳。
Name
started_at
Type
timestamp
Description
某個工作程序開始處理任務的時間，採用 Unix 毫秒時間戳。在此之前為 null。
Name
finished_at
Type
timestamp
Description
任務達到最終狀態的時間，採用 Unix 毫秒時間戳。在此之前為 null。
Name
expires_at
Type
timestamp
Description
任務結果過期的時間，採用 Unix 毫秒時間戳。該時間為 finished_at 之後 3 天；在任務完成之前，則為 created_at 之後 3 天。對於可無限期保留 API 結果的 Enterprise 帳戶，該時間約為之後 100 年。參見資產保留期。
Name
preceding_tasks
Type
integer
Description
任務處於 PENDING 狀態時在佇列中的位置。1 表示它將是下一個開始的任務。任務離開佇列後為 0，在清單結果中始終為 0。
Name
task_error
Type
object
Description
任務失敗的原因。除非 status 為 FAILED，否則為 null。參見 Errors。
Name
consumed_credits
Type
integer
Description
任務扣除的積分數量（扣除任何退款後）。回傳錯誤的請求不會被扣費。失敗的任務為 0，因為 Meshy 會退還費用。取消操作僅在任務處於 PENDING 狀態時才會退款。如果 Meshy 無法讀取扣費資訊，get 或 stream 回應會省略該欄位，而 list 請求會回傳 500。遇到這種情況，請重試該請求。
Name
model_urls
Type
object
Description
3D 模型的下載連結，在任務成功之前為空。成功的任務始終包含 stl，僅當 Meshy 渲染了預覽時才包含 glb。
- Name
  stl
  Type
  string
  Description
  STL 檔案的下載連結，即用於列印的檔案。你可以直接在切片軟體中開啟它。
- Name
  glb
  Type
  string
  Description
  用於在 3D 檢視器中預覽模型的 GLB 檔案下載連結。其顏色僅用於預覽。STL 檔案沒有顏色，因此列印出的指尖玩具的顏色由耗材決定。
  如果 Meshy 無法渲染預覽，model_urls 中就不會有 glb 鍵，因此在讀取之前請先檢查該鍵是否存在。SUCCEEDED 狀態的任務始終包含 stl。