lowpoly retires Oct 30, 2026. Please switch models before these dates to avoid request errors. See all deprecations

Creative Lab Collapsible Fidget API

Turn a photo into a print-in-place collapsible fidget toy in one task. The subject's silhouette becomes nested concentric rings that collapse flat and stretch out again. The toy prints in one piece, with no assembly.

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

Unlike the other Creative Lab endpoints, this one has no separate prototype and build stages. There are no candidate images to choose between, so one task turns the photo into a 3D model.

The request has no geometry settings either. The web app lets you set the size, layer count, gap width, wall thickness, extrusion depth, and bulge. Every API task uses the same default values for them.

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

Create a Collapsible Fidget task

Generates a collapsible fidget model from a photo. For the task's fields, see The Collapsible Fidget task object.

Each task costs 6 credits and needs a paid plan.

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

Parameters

  • Name
    image_url
    Type
    string
    Required
    Description

    The photo to turn into a collapsible fidget, as a public URL or a data URI (data:image/jpeg;base64,<your base64-encoded image data>).

    The image must be a JPG, JPEG, PNG, or WebP file of at most 20 MB.

    The subject's silhouette becomes the rings, so a subject with one clear, closed outline works best. A busy background, several separate subjects, or very thin shapes can leave too little area for the nested walls. In that case, the task fails.

  • Name
    name
    Type
    string
    Description

    A name for the task, up to 100 characters. It comes back in the task's name field, and Meshy doesn't engrave it on the model. A longer name returns 400.

Returns

The result field holds the ID of the new task. Get the task or stream it until status is SUCCEEDED. Then download the printable STL file from model_urls.stl. To preview the model first, download the GLB file from model_urls.glb when it's present.

Failure modes

  • Name
    400 - Bad Request
    Description

    The request can't run. For example:

    • image_url is missing.
    • The image isn't a JPG, JPEG, PNG, or WebP file.
    • The image is too small, over 20 MB, or over the maximum pixel count.
    • Meshy can't download the image, for example because the URL returns 404 or times out.
    • The data URI isn't valid base64.
    • The image was flagged as NSFW.

    The error message says which problem it found. Fix the request, then send it again.

  • Name
    401 - Unauthorized
    Description

    The API key is missing or invalid. Check the Authorization header.

  • Name
    402 - Payment Required
    Description

    One of these applies:

    • The account doesn't have enough credits.
    • The API key, workspace, or member reached its credit limit.
    • The account is on the free plan.

    Check your credits and plan, then retry.

  • Name
    403 - Forbidden
    Description

    Your team has IP Filtering turned on, and Meshy flagged the image for third-party intellectual property. Send an image you have the rights to use.

  • Name
    429 - Too Many Requests
    Description

    One of these limits was reached:

    • You sent more requests than your rate limit allows. Wait a few seconds, then retry. See Rate limits.
    • Too many of your tasks are queued or running. Wait for some to finish, then retry.
    • On an unlimited plan with no credits left, you reached the number of tasks that can run without credits. Wait for a task to finish, or add credits.
  • Name
    500 - Internal Server Error
    Description

    Meshy hit a server error, for example because it couldn't run the intellectual property check on the image. Meshy doesn't create the task, and refunds any credits it charged. Retry the request.

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

Get a Collapsible Fidget task

Returns a Collapsible Fidget task. Only tasks created with this endpoint are returned. A task from another Creative Lab endpoint, or one created in the web app, returns 404.

For the fields, see The Collapsible Fidget task object.

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

Parameters

  • Name
    id
    Type
    path
    Description

    The task ID from the create response.

Returns

The Collapsible Fidget task object.

Failure modes

  • Name
    400 - Bad Request
    Description

    id isn't a valid task ID. Send the result ID from the create response.

  • Name
    403 - Forbidden
    Description

    Your team has IP Filtering turned on, and Meshy flagged the task's image for third-party intellectual property. Teams on the Enterprise plan don't get this error. Create a task from an image you have the rights to use.

  • Name
    404 - Not Found
    Description

    No Collapsible Fidget task with this ID belongs to your account, or the task wasn't created with this endpoint. Check the ID.

  • Name
    500 - Internal Server Error
    Description

    Meshy couldn't run the intellectual property check. Retry the request.

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

Delete a Collapsible Fidget task

Cancels a Collapsible Fidget task. Canceling a PENDING task refunds its credits. An IN_PROGRESS task is canceled without a refund, because a worker has already started it. A task with a final status (SUCCEEDED, FAILED, or CANCELED) can't be 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).

Path parameters

  • Name
    id
    Type
    path
    Description

    The ID of the task to cancel.

Returns

204 No Content with an empty body.

Failure modes

  • Name
    400 - Bad Request
    Description

    One of these applies:

    • id isn't a valid task ID. Send the result ID from the create response.
    • The task already has a final status (SUCCEEDED, FAILED, or CANCELED), so it can't be canceled.
  • Name
    404 - Not Found
    Description

    No Collapsible Fidget task with this ID belongs to your account, or the task wasn't created with this endpoint. Check the ID.

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

Stream a Collapsible Fidget task

Streams a Collapsible Fidget task's updates as Server-Sent Events (SSE). If the task doesn't exist or wasn't created with this endpoint, the stream sends one error event with status_code: 404 and closes.

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

Parameters

  • Name
    id
    Type
    path
    Description

    The task ID from the create response.

Returns

A stream of Collapsible Fidget task objects. Each event has the full task object, as Get a Collapsible Fidget task returns it. While the task is PENDING or IN_PROGRESS, its output fields are still empty (null, [], or {}), and finished_at is null.

If IP Filtering blocks the task's result, the stream sends one error event in its place, with the status_code that a get request would return.

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

List Collapsible Fidget tasks

Returns your Collapsible Fidget tasks, one page at a time. Only tasks created with this endpoint are included.

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

Query parameters

  • Name
    page_num
    Type
    integer
    default 1
    Description

    The page to return, from 1 to 255. 0 returns the first page. A value outside 0 to 255 returns 400.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Number of tasks per page, up to 100. A value from 101 to 255 returns 100 tasks, and 0 uses the default. A value outside 0 to 255 returns 400.

  • Name
    sort_by
    Type
    string
    default -created_at
    Description

    The sort order.

    Available values:

    • -created_at: newest first
    • +created_at: oldest first

Returns

An array of Collapsible Fidget task objects.

The Collapsible Fidget task object

A Collapsible Fidget task turns a photo into a print-in-place collapsible fidget model. It's a single-stage task, so there's no prototype task to chain from. The response doesn't include the silhouette that Meshy makes along the way.

Properties

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

    The task ID. Don't rely on its format.

  • Name
    type
    Type
    string
    Description

    The task type, always creative-lab-fidget-collapsible.

  • Name
    name
    Type
    string
    Description

    The name you sent when you created the task, or "" if you didn't send one.

  • Name
    status
    Type
    string
    Description

    The task's status.

    Available values:

    • PENDING: waiting in the queue
    • IN_PROGRESS: generating the result
    • SUCCEEDED: final, with the result
    • FAILED: final, with the reason in task_error
    • CANCELED: final, with no result
  • Name
    progress
    Type
    integer
    Description

    Percentage of the work done, from 0 to 100. It's 0 until the task starts and 100 when it succeeds.

  • Name
    created_at
    Type
    timestamp
    Description

    Time the task was created, in Unix milliseconds.

  • Name
    started_at
    Type
    timestamp
    Description

    Time a worker started the task, in Unix milliseconds. null until then.

  • Name
    finished_at
    Type
    timestamp
    Description

    Time the task reached a final status, in Unix milliseconds. null until then.

  • Name
    expires_at
    Type
    timestamp
    Description

    Time the task's result expires, in Unix milliseconds. It's 3 days after finished_at, or 3 days after created_at until the task finishes. For Enterprise accounts, which keep API results indefinitely, it's about 100 years later. See Asset retention.

  • Name
    preceding_tasks
    Type
    integer
    Description

    The task's position in the queue while it's PENDING. 1 means it starts next. 0 after the task leaves the queue, and always 0 in list results.

  • Name
    task_error
    Type
    object
    Description

    Why the task failed. null unless status is FAILED. See Errors.

  • Name
    consumed_credits
    Type
    integer
    Description

    Number of credits charged for the task, after any refund. A request that returns an error isn't charged. A failed task is 0, because Meshy refunds it. Canceling refunds a task only while it's PENDING. If Meshy can't read the charge, a get or stream response leaves the field out, and a list request returns 500. In that case, retry the request.

  • Name
    model_urls
    Type
    object
    Description

    Download URLs for the 3D model, empty until the task succeeds. A succeeded task always has stl, and has glb only if Meshy rendered the preview.

    • Name
      stl
      Type
      string
      Description

      Download URL for the STL file, which is the file to print. You can open it directly in a slicer.

    • Name
      glb
      Type
      string
      Description

      Download URL for a GLB file to preview the model in a 3D viewer. Its colors are for the preview only. The STL file has no color, so the printed fidget takes its color from the filament.

      If Meshy can't render the preview, model_urls has no glb key, so check for the key before you read it. A SUCCEEDED task always has stl.