Creative Lab — Collapsible Fidget API

Turn a source photo into a print-in-place collapsible fidget toy: the subject's silhouette becomes a set of nested concentric rings that collapse flat and stretch out again, printed in one piece with no assembly.

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

Unlike the other Creative Lab endpoints, this one has no prototype/build stage pair — there are no intermediate candidates to choose between, so a single task carries the image all the way to a 3D model. The geometry controls the web app exposes (size, layer count, gap width, wall thickness, extrusion depth, bulge) are not part of the request either: every task builds with the same server-side defaults.

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

Create a Collapsible Fidget Task

Generate a collapsible fidget model from a source photo. Refer to The Collapsible Fidget Task Object for the response shape.

Each task costs 6 credits and requires a paid plan.

Parameters

  • Name
    image_url
    Type
    string
    Required
    Description

    Source photo for Meshy to turn into a collapsible fidget. We currently support .jpg, .jpeg, .png, and .webp formats.

    There are two ways to provide the image:

    • Publicly accessible URL: A URL that is accessible from the public internet.
    • Data URI: A base64-encoded data URI of the image. Example of a data URI: data:image/jpeg;base64,<your base64-encoded image data>.

    A subject with one clear, closed outline works best — the silhouette is what becomes the rings. Busy backgrounds, several separate subjects, or very thin shapes can leave too little area for the nested walls, and the task fails with a task error.

  • Name
    name
    Type
    string
    Description

    Optional task name for display purposes. Maximum 100 characters. This is a task label only; nothing is engraved on the model.

Returns

The result property of the response contains the task id of the newly created collapsible fidget task. Poll the Get a Task endpoint or subscribe to the stream until the task reaches SUCCEEDED, then download the printable STL from model_urls.stl (and, when present, the GLB from model_urls.glb to preview it first).

Failure Modes

  • Name
    400 - Bad Request
    Description

    The request was unacceptable. Common causes:

    • Missing parameter: image_url is required.
    • Invalid image format: The provided image_url is not a supported format (.jpg, .jpeg, .png, .webp).
    • Image dimensions out of range: The image is too small, exceeds the maximum file size, or exceeds the maximum pixel count.
    • Unreachable URL: The image_url could not be downloaded (404 or timeout).
    • Invalid Data URI: The base64 string is malformed.
    • Content flagged: The input image was flagged by NSFW moderation.
  • Name
    401 - Unauthorized
    Description

    Authentication failed. Please check your API key.

  • Name
    402 - Payment Required
    Description

    Either your account is on the free plan — task creation on this endpoint requires a paid plan — or you have insufficient credits.

  • Name
    403 - Forbidden
    Description

    The input image was flagged for intellectual property violation.

  • Name
    429 - Too Many Requests
    Description

    You have exceeded your rate limit.

Request

POST
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.cn/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

Retrieve a Collapsible Fidget Task

Retrieve a collapsible fidget task given a valid task id. Only tasks created through this endpoint are addressable here — a task from another Creative Lab endpoint, or one created in the web app, returns 404.

Refer to The Collapsible Fidget Task Object for the response shape.

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the collapsible fidget task to retrieve.

Returns

The response contains the collapsible fidget task object.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}
DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Delete a Collapsible Fidget Task

Cancel a collapsible fidget task. If the task is still PENDING, the credits consumed at create-time are refunded. Tasks that are already IN_PROGRESS are cancelled without a refund (the worker may already be burning resources). Tasks that have already reached a terminal state (SUCCEEDED, FAILED, CANCELED) cannot be cancelled.

Path Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the collapsible fidget task to cancel.

Returns

Returns 204 No Content on success with an empty body.

Failure Modes

  • Name
    400 - Bad Request
    Description

    The task is already in a terminal state and cannot be cancelled.

  • Name
    404 - Not Found
    Description

    The task does not exist, belongs to a different user, or was not created through this endpoint.

Request

DELETE
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.cn/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

Stream a Collapsible Fidget Task

Stream real-time updates for a collapsible fidget task via Server-Sent Events (SSE). A task that does not exist, or was not created through this endpoint, emits a single event: error payload with status_code: 404 and closes the stream.

Parameters

  • Name
    id
    Type
    path
    Description

    Unique identifier for the collapsible fidget task to stream.

Returns

Returns a stream of Collapsible Fidget task objects as Server-Sent Events. For PENDING or IN_PROGRESS tasks, the response stream will only include the necessary progress and status fields.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}
GET/openapi/creative-lab/fidget-collapsible/v1

List Collapsible Fidget Tasks

Retrieve a paginated list of your collapsible fidget tasks. Only tasks created through this endpoint are included.

Query Parameters

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Page number for pagination.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Page size limit. Maximum allowed is 100 items.

  • Name
    sort_by
    Type
    string
    default -created_at
    Description

    Field to sort by. Available values:

    • +created_at: Sort by creation time in ascending order.
    • -created_at: Sort by creation time in descending order.

Returns

Returns a paginated list of the collapsible fidget task object.

Request

GET
/openapi/creative-lab/fidget-collapsible/v1
curl https://api.meshy.cn/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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
      "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
    }
  }
]

The Collapsible Fidget Task Object

The Collapsible Fidget Task object is a work unit that Meshy keeps track of to turn a source photo into a print-in-place collapsible fidget model. It is a single-stage task: there is no prototype to chain from, and the intermediate silhouette is not part of the response.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the task. While we use a k-sortable UUID for task ids as the implementation detail, you should not make any assumptions about the format of the id.

  • Name
    type
    Type
    string
    Description

    Type of the task. The value is creative-lab-fidget-collapsible.

  • Name
    name
    Type
    string
    Description

    The task name supplied when the task was created. Empty string if no name was provided.

  • Name
    status
    Type
    string
    Description

    Status of the task. Possible values are one of PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress of the task. If the task is not started yet, this property will be 0. Once the task has succeeded, this will become 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the task was created, in milliseconds.

    A timestamp represents the number of milliseconds elapsed since January 1, 1970 UTC, following the RFC 3339 standard. For example, Friday, September 1, 2023 12:00:00 PM GMT is represented as 1693569600000. This applies to all timestamps in Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Timestamp of when the task was started, in milliseconds. If the task is not started yet, this property will be null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp of when the task was finished, in milliseconds. If the task is not finished yet, this property will be null.

  • Name
    expires_at
    Type
    timestamp
    Description

    Timestamp of when the task result expires, in milliseconds.

  • Name
    preceding_tasks
    Type
    integer
    Description

    The count of preceding tasks.

    The value of this field is meaningful only if the task status is PENDING.

  • Name
    task_error
    Type
    object
    Description

    Error details for failed tasks. See Errors for the full task_error object reference.

  • Name
    consumed_credits
    Type
    integer
    Description

    The number of credits consumed by this task. Present when the task status is PENDING, IN_PROGRESS, or SUCCEEDED. Returns 0 for FAILED tasks (credits are refunded on failure).

  • Name
    model_urls
    Type
    object
    Description

    Downloadable URLs for the generated 3D model. Populated once the task has SUCCEEDED: stl is always present, glb only when the preview render succeeded.

    • Name
      stl
      Type
      string
      Description

      Downloadable URL to the STL file. This is the printable deliverable — send it straight to a slicer.

    • Name
      glb
      Type
      string
      Description

      Downloadable URL to the GLB file, for previewing the model in a 3D viewer. Its colours are for preview only: STL carries no colour, and a printed fidget takes its colour from the filament. The GLB is best-effort: when the preview render is unavailable the key is omitted from model_urls entirely, so read it defensively — stl is the deliverable and is always present on a SUCCEEDED task.

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.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "stl": "https://assets.meshy.cn/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  }
}