Creative Lab — 可折疊指尖玩具 API

將一張原始照片轉換為可直接列印成型的可折疊指尖玩具：主體的輪廓會變成一組嵌套的同心環， 可以壓縮攤平，也可以重新展開拉伸，整體一次性列印完成，無需組裝。

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

與其他 Creative Lab endpoint 不同，此 endpoint 沒有原型／建構階段配對——不存在需要在 中間挑選的候選方案，因此單一任務會將圖片一路處理到最終的 3D 模型。Web 應用程式所公開的 geometry 控制項（尺寸、層數、間隙寬度、壁厚、擠出深度、凸起程度）同樣不屬於請求的一 部分：每個任務都使用相同的伺服器端預設值進行建構。

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

Create a Collapsible Fidget Task

根據來源照片產生一個可折疊的指尖玩具（fidget）模型。回應結構請參閱 The Collapsible Fidget Task Object。

每個任務花費 6 credits，且需要付費方案。

參數

  • 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 個字元。這只是一個任務標籤，不會刻印在模型上。

回傳

回應中的 result 屬性包含新建立的可折疊指尖玩具任務的 id。輪詢 Get a Task endpoint 或訂閱 stream，直到任務狀態變為 SUCCEEDED，然後從 model_urls.stl 下載可列印的 STL 檔案（如果存在，還可以先從 model_urls.glb 下載 GLB 檔案進行預覽）。

失敗模式

  • 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

    您的帳戶為免費方案——該 endpoint 的任務建立需要付費方案——或者您的 credits 不足。

  • Name
    403 - Forbidden
    Description

    輸入圖片因涉嫌智慧財產權侵權而被標記。

  • Name
    429 - Too Many Requests
    Description

    您已超出速率限制。

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"
}
GET/openapi/creative-lab/fidget-collapsible/v1/:id

取得可摺疊玩具任務

根據有效的任務 id 取得可摺疊玩具任務。此處僅可存取透過該 endpoint 建立的任務——來自其他 Creative Lab endpoint 的任務，或在網頁應用程式中建立的任務，將回傳 404。

有關回應結構，請參閱可摺疊玩具任務物件。

參數

  • Name
    id
    Type
    path
    Description

    要取得的可摺疊玩具任務的唯一識別碼。

回傳值

回應包含可摺疊玩具任務物件。

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=***"
  }
}
DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

刪除可摺疊指尖玩具任務

取消一個可摺疊指尖玩具任務。如果任務仍處於 PENDING 狀態，建立任務時消耗的 credits 將被退還。已處於 IN_PROGRESS 狀態的任務將被取消，但不會退款（因為 worker 可能已經在消耗資源）。已經達到終止狀態（SUCCEEDED、FAILED、 CANCELED）的任務無法取消。

路徑參數

  • Name
    id
    Type
    path
    Description

    要取消的可摺疊指尖玩具任務的唯一識別碼。

回傳值

成功時回傳 204 No Content，回應內容為空。

失敗模式

  • Name
    400 - Bad Request
    Description

    任務已處於終止狀態，無法取消。

  • Name
    404 - Not Found
    Description

    該任務不存在、屬於其他使用者，或不是透過此 endpoint 建立的。

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).
GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

流式取得可折疊指尖玩具任務

透過 Server-Sent Events（SSE）流式取得可折疊指尖玩具任務的即時更新。 如果任務不存在，或者不是透過該 endpoint 建立的，將發出一個 event: error 負載，其中 status_code: 404，隨後關閉串流。

參數

  • Name
    id
    Type
    path
    Description

    要流式取得的可折疊指尖玩具任務的唯一識別碼。

回傳值

以 Server-Sent Events 的形式回傳一系列 可折疊指尖玩具 任務物件的串流。對於 PENDING 或 IN_PROGRESS 狀態的任務， 回應串流中只會包含必要的 progress 和 status 欄位。

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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=***"
  }
}
GET/openapi/creative-lab/fidget-collapsible/v1

列出可折疊指尖玩具任務

取得分頁列出的可折疊指尖玩具任務清單。僅包含透過此 endpoint 建立的任務。

查詢參數

  • 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：按建立時間降序排序。

回傳值

回傳分頁列出的 可折疊指尖玩具任務物件。

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

可折疊指尖玩具任務物件

可折疊指尖玩具任務物件是 Meshy 用於追蹤的一項工作單元，用於將一張來源照片轉換為可原地列印（print-in-place）的可折疊指尖玩具模型。它是一個單階段任務：沒有可供連結的原型，且中間輪廓也不屬於回應內容的一部分。

屬性

  • Name
    id
    Type
    string
    Description

    任務的唯一識別碼。雖然我們在實作細節中使用 k-sortable UUID 作為任務 id，但你不應對 id 的格式做任何假設。

  • Name
    type
    Type
    string
    Description

    任務的類型。該值為 creative-lab-fidget-collapsible。

  • 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

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

    時間戳表示自 UTC 時間 1970 年 1 月 1 日以來經過的毫秒數，遵循 RFC 3339 標準。 例如，格林威治標準時間 2023 年 9 月 1 日星期五中午 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 物件參考請參閱 Errors。

  • Name
    consumed_credits
    Type
    integer
    Description

    此任務消耗的 積分 數量。當任務狀態為 PENDING、IN_PROGRESS 或 SUCCEEDED 時會出現該欄位。對於 FAILED 任務，回傳 0（失敗時會退還積分）。

  • Name
    model_urls
    Type
    object
    Description

    產生的 3D 模型的可下載 URL。一旦任務 SUCCEEDED 便會填入：stl 始終存在，glb 僅在預覽渲染成功時才存在。

    • Name
      stl
      Type
      string
      Description

      STL 檔案的可下載 URL。這是可列印的最終成品——可直接送往切片軟體。

    • Name
      glb
      Type
      string
      Description

      GLB 檔案的可下載 URL，用於在 3D 檢視器中預覽模型。其顏色僅供預覽使用：STL 不攜帶顏色資訊，列印出來的指尖玩具的顏色取決於所使用的線材（filament）。GLB 是盡力提供的：當預覽渲染不可用時，model_urls 中會完全省略該鍵，因此在讀取時應做好防禦性處理——stl 才是最終成品，且在任務 SUCCEEDED 時始終存在。

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