Creative Lab — Collapsible Fidget API

Zet een bronfoto om in een direct af te drukken inklapbare fidget-speeltje: de silhouet van het onderwerp wordt een reeks geneste concentrische ringen die plat inklappen en weer uitrekken, in één stuk geprint zonder montage.

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

In tegenstelling tot de andere Creative Lab endpoints heeft deze geen prototype/build-fase paar — er zijn geen tussenliggende kandidaten om uit te kiezen, dus één taak brengt de afbeelding helemaal tot aan een 3D-model. De geometrie-instellingen die de web app blootstelt (grootte, aantal lagen, spleetbreedte, wanddikte, extrusiediepte, bolling) maken evenmin deel uit van het verzoek: elke taak wordt gebouwd met dezelfde standaardinstellingen aan serverzijde.

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

Een taak voor een inklapbaar fidget-object maken

Genereer een inklapbaar fidget-model op basis van een bronfoto. Raadpleeg The Collapsible Fidget Task Object voor de vorm van de response.

Elke taak kost 6 credits en vereist een betaald abonnement.

Parameters

  • Name
    image_url
    Type
    string
    Verplicht
    Description

    Bronfoto die Meshy omzet in een inklapbaar fidget-object. We ondersteunen momenteel de formaten .jpg, .jpeg, .png en .webp.

    Er zijn twee manieren om de afbeelding aan te leveren:

    • Publiekelijk toegankelijke URL: Een URL die toegankelijk is vanaf het openbare internet.
    • Data URI: Een base64-gecodeerde data-URI van de afbeelding. Voorbeeld van een data-URI: data:image/jpeg;base64,<your base64-encoded image data>.

    Een onderwerp met één duidelijke, gesloten contour werkt het beste — het silhouet is wat de ringen wordt. Rommelige achtergronden, meerdere afzonderlijke onderwerpen of zeer dunne vormen kunnen te weinig ruimte overlaten voor de geneste wanden, waardoor de taak mislukt met een taakfout.

  • Name
    name
    Type
    string
    Description

    Optionele taaknaam voor weergavedoeleinden. Maximaal 100 tekens. Dit is alleen een label voor de taak; er wordt niets in het model gegraveerd.

Retourneert

De result-eigenschap van de response bevat de taak-id van de nieuw aangemaakte taak voor het inklapbare fidget-object. Poll de Get a Task-endpoint of abonneer je op de stream totdat de taak de status SUCCEEDED bereikt, en download vervolgens de printbare STL via model_urls.stl (en, indien beschikbaar, de GLB via model_urls.glb om deze eerst te bekijken).

Faalmodi

  • Name
    400 - Bad Request
    Description

    Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:

    • Ontbrekende parameter: image_url is verplicht.
    • Ongeldig afbeeldingsformaat: De opgegeven image_url heeft geen ondersteund formaat (.jpg, .jpeg, .png, .webp).
    • Afbeeldingsafmetingen buiten bereik: De afbeelding is te klein, overschrijdt de maximale bestandsgrootte of overschrijdt het maximale aantal pixels.
    • Onbereikbare URL: De image_url kon niet worden gedownload (404 of timeout).
    • Ongeldige Data URI: De base64-string is onjuist opgemaakt.
    • Content gemarkeerd: De invoerafbeelding is gemarkeerd door NSFW-moderation.
  • Name
    401 - Unauthorized
    Description

    Authenticatie mislukt. Controleer je API-sleutel.

  • Name
    402 - Payment Required
    Description

    Ofwel heeft je account een gratis abonnement — het aanmaken van taken via deze endpoint vereist een betaald abonnement — ofwel heb je onvoldoende credits.

  • Name
    403 - Forbidden
    Description

    De invoerafbeelding is gemarkeerd wegens een schending van intellectuele eigendomsrechten.

  • Name
    429 - Too Many Requests
    Description

    Je hebt je rate limit overschreden.

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

Een Collapsible Fidget-taak ophalen

Haal een collapsible fidget-taak op met een geldige id. Alleen taken die via deze endpoint zijn aangemaakt, zijn hier bereikbaar — een taak van een andere Creative Lab-endpoint, of een taak die is aangemaakt in de web-app, geeft 404 terug.

Raadpleeg Het Collapsible Fidget Task-object voor de vorm van de respons.

Parameters

  • Name
    id
    Type
    path
    Description

    Unieke identifier van de op te halen collapsible fidget-taak.

Retourwaarden

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

Een inklapbare fidget-taak verwijderen

Annuleer een inklapbare fidget-taak. Als de taak nog PENDING is, worden de credits die bij het aanmaken zijn verbruikt, terugbetaald. Taken die al IN_PROGRESS zijn, worden geannuleerd zonder terugbetaling (de worker verbruikt mogelijk al Bronnen). Taken die al een eindstatus hebben bereikt (SUCCEEDED, FAILED, CANCELED) kunnen niet worden geannuleerd.

Padparameters

  • Name
    id
    Type
    path
    Description

    Unieke identificatie van de inklapbare fidget-taak die geannuleerd moet worden.

Retourwaarden

Retourneert 204 No Content bij succes met een lege body.

Foutmodi

  • Name
    400 - Bad Request
    Description

    De taak bevindt zich al in een eindstatus en kan niet worden geannuleerd.

  • Name
    404 - Not Found
    Description

    De taak bestaat niet, behoort toe aan een andere gebruiker, of is niet via deze endpoint aangemaakt.

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

Stream een Collapsible Fidget-taak

Stream realtime updates voor een collapsible fidget-taak via Server-Sent Events (SSE). Een taak die niet bestaat, of niet via deze endpoint is aangemaakt, geeft een enkele event: error payload met status_code: 404 en sluit de stream.

Parameters

  • Name
    id
    Type
    path
    Description

    Unieke identifier voor de collapsible fidget-taak die gestreamd moet worden.

Retourneert

Retourneert een stream van Collapsible Fidget taakobjecten als Server-Sent Events. Elk frame bevat het volledige taakobject voor de fase — dezelfde vorm die de Get-endpoint retourneert — dus terwijl de taak PENDING of IN_PROGRESS is, zijn de outputvelden simpelweg nog niet ingevuld (null, [] of {}) en is finished_at gelijk aan 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

Lijst van inklapbare fidget-taken

Haal een gepagineerde lijst van je inklapbare fidget-taken op. Alleen taken die via deze endpoint zijn aangemaakt, worden opgenomen.

Query-parameters

  • Name
    page_num
    Type
    integer
    standaard 1
    Description

    Paginanummer voor paginering.

  • Name
    page_size
    Type
    integer
    standaard 10
    Description

    Limiet voor paginagrootte. Maximaal toegestaan is 100 items.

  • Name
    sort_by
    Type
    string
    standaard -created_at
    Description

    Veld waarop gesorteerd wordt. Beschikbare waarden:

    • +created_at: Sorteer op aanmaaktijd in oplopende volgorde.
    • -created_at: Sorteer op aanmaaktijd in aflopende volgorde.

Retourwaarden

Geeft een gepagineerde lijst terug van het inklapbare fidget-taakobject.

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

Het opvouwbare fidget-taakobject

Het opvouwbare fidget-taakobject is een werkeenheid die Meshy bijhoudt om een bronfoto om te zetten in een print-in-place opvouwbaar fidgetmodel. Het is een taak met één fase: er is geen prototype om van te vertrekken, en het tussenliggende silhouet maakt geen deel uit van de respons.

Eigenschappen

  • Name
    id
    Type
    string
    Description

    Unieke identifier voor de taak. Hoewel we een k-sorteerbare UUID gebruiken voor taak-id's als implementatiedetail, moet je geen aannames doen over de indeling van de id.

  • Name
    type
    Type
    string
    Description

    Type van de taak. De waarde is creative-lab-fidget-collapsible.

  • Name
    name
    Type
    string
    Description

    De taaknaam die is opgegeven bij het aanmaken van de taak. Lege string als er geen naam is opgegeven.

  • Name
    status
    Type
    string
    Description

    Status van de taak. Mogelijke waarden zijn PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Voortgang van de taak. Als de taak nog niet is gestart, is deze eigenschap 0. Zodra de taak is geslaagd, wordt dit 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de taak is aangemaakt, in milliseconden.

    Een tijdstempel vertegenwoordigt het aantal milliseconden dat is verstreken sinds 1 januari 1970 UTC, volgens de RFC 3339-standaard. Vrijdag 1 september 2023 12:00:00 PM GMT wordt bijvoorbeeld weergegeven als 1693569600000. Dit geldt voor alle tijdstempels in Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de taak is gestart, in milliseconden. Als de taak nog niet is gestart, is deze eigenschap null.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de taak is voltooid, in milliseconden. Als de taak nog niet is voltooid, is deze eigenschap null.

  • Name
    expires_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer het taakresultaat verloopt, in milliseconden.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Het aantal voorgaande taken.

    De waarde van dit veld is alleen relevant als de taakstatus PENDING is.

  • Name
    task_error
    Type
    object
    Description

    Foutdetails voor mislukte taken. Zie Fouten voor de volledige referentie van het task_error-object.

  • Name
    consumed_credits
    Type
    integer
    Description

    Het aantal credits dat door deze taak is verbruikt. Aanwezig wanneer de taakstatus PENDING, IN_PROGRESS of SUCCEEDED is. Geeft 0 terug voor FAILED-taken (credits worden terugbetaald bij falen).

  • Name
    model_urls
    Type
    object
    Description

    Downloadbare URL's voor het gegenereerde 3D-model. Wordt ingevuld zodra de taak SUCCEEDED is: stl is altijd aanwezig, glb alleen wanneer de previewrender geslaagd is.

    • Name
      stl
      Type
      string
      Description

      Downloadbare URL naar het STL-bestand. Dit is het printbare eindresultaat — stuur het rechtstreeks naar een slicer.

    • Name
      glb
      Type
      string
      Description

      Downloadbare URL naar het GLB-bestand, voor het bekijken van het model in een 3D-viewer. De kleuren zijn alleen bedoeld voor de preview: STL bevat geen kleur, en een geprinte fidget krijgt zijn kleur van het filament. De GLB wordt op basis van beste inspanning geleverd: wanneer de previewrender niet beschikbaar is, wordt de sleutel volledig weggelaten uit model_urls, dus lees dit defensief — stl is het eindresultaat en is altijd aanwezig bij een SUCCEEDED-taak.

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