Creative Lab — 可折疊指尖玩具 API

將一張來源照片轉變為可原地列印的可折疊指尖玩具：主體的輪廓變成一組巢狀的同心環， 可以折疊平整也可以再次拉伸展開，一體成型列印，無需組裝。

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

與其他 Creative Lab 端點不同，此端點沒有原型／建構階段這一對流程—— 不存在需要從中選擇的中間候選項，因此一個任務會將圖像一路處理到 3D 模型。web 應用程式中 所暴露的 geometry 控制選項（尺寸、層數、間隙寬度、壁厚、擠出深度、凸起程度）也不 屬於請求的一部分：每個任務都會使用相同的伺服器端預設值來建構。

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

建立可摺疊指尖玩具任務

根據來源照片產生一個可摺疊指尖玩具模型。回應的具體結構請參閱 可摺疊指尖玩具任務物件。

每個任務花費 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。輪詢 取得任務 endpoint，或訂閱 串流介面，直到任務達到 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

獲取一個可折疊玩具（Collapsible Fidget）任務

根據有效的任務 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 狀態的任務會被取消但不予退款 （工作進程可能已經在消耗資源）。已經達到終止狀態 （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

流式取得可折疊玩具任務

透過伺服器發送事件（SSE）流式取得可折疊玩具任務的即時更新。如果任務不存在，或不是透過此 endpoint 建立的，將發出單個 event: error payload，其中包含 status_code: 404，隨後關閉串流。

參數

  • Name
    id
    Type
    path
    Description

    要進行流式傳輸的可折疊玩具任務的唯一識別碼。

回傳值

以 Server-Sent Events 的形式回傳一個 可折疊玩具 任務物件流。每一幀都攜帶該階段的完整任務物件——與 Get endpoint 回傳的結構相同——因此當任務處於 PENDING 或 IN_PROGRESS 狀態時， 輸出欄位只是尚未填入（為 null、[] 或 {}），且 finished_at 為 null。

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 PENDING frame below is abbreviated 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=***"
  }
}
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 用來追蹤的工作單元，用於將一張來源照片轉換為可原地列印的可折疊指尖玩具模型。這是一個單階段任務：沒有可供鏈式呼叫的原型，中間輪廓也不屬於回應內容的一部分。

屬性

  • Name
    id
    Type
    string
    Description

    任務的唯一識別碼。雖然我們在實作細節中使用 k-可排序的 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

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

    時間戳表示自 1970 年 1 月 1 日 UTC 起經過的毫秒數，遵循 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 物件參考請參見錯誤。

  • 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。這是可列印的交付物——可直接傳送給 slicer。

    • Name
      glb
      Type
      string
      Description

      指向 GLB 檔案的可下載 URL，用於在 3D 檢視器中預覽模型。其顏色僅用於預覽：STL 不攜帶顏色資訊，列印出的指尖玩具的顏色取決於所用的耗材。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=***"
  }
}