Creative Lab — Collapsible Fidget API

Verander een bronfoto in een print-in-place inklapbare fidget-toy: de silhouet van het onderwerp wordt een set 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-fasepaar — er zijn geen tussenliggende kandidaten om uit te kiezen, dus één taak draagt de afbeelding helemaal tot aan een 3D-model. De geometriebediening die de webapp blootstelt (grootte, aantal lagen, breedte van de opening, wanddikte, extrusiediepte, uitstulping) maakt evenmin deel uit van het verzoek: elke taak wordt gebouwd met dezelfde standaardinstellingen aan serverzijde.

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

Een Collapsible Fidget-taak aanmaken

Genereer een inklapbaar (collapsible) 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 inklapbare fidget. We ondersteunen momenteel de formaten .jpg, .jpeg, .png en .webp.

    Er zijn twee manieren om de afbeelding aan te leveren:

    • Publiek toegankelijke URL: Een URL die toegankelijk is vanaf het publieke 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 omtrek werkt het best — het silhouet vormt de ringen. Rommelige achtergronden, meerdere afzonderlijke onderwerpen of erg 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 taaklabel; er wordt niets in het model gegraveerd.

Retourwaarden

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

Foutmodi

  • Name
    400 - Bad Request
    Description

    Het verzoek was onaanvaardbaar. Veelvoorkomende oorzaken:

    • Ontbrekende parameter: image_url is vereist.
    • 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 is mislukt. Controleer je API-sleutel.

  • Name
    402 - Payment Required
    Description

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

  • Name
    403 - Forbidden
    Description

    De invoerafbeelding is gemarkeerd wegens schending van intellectueel eigendom.

  • Name
    429 - Too Many Requests
    Description

    Je hebt je rate limit overschreden.

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

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 beschikbaar — een taak van een andere Creative Lab-endpoint, of een taak die in de web-app is aangemaakt, geeft 404 terug.

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

Parameters

  • Name
    id
    Type
    path
    Description

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

Retourneert

De response bevat het 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

Annuleer een collapsible 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 resources). Taken die al een eindtoestand hebben bereikt (SUCCEEDED, FAILED, CANCELED) kunnen niet worden geannuleerd.

Path Parameters

  • Name
    id
    Type
    path
    Description

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

Returns

Geeft 204 No Content terug bij succes met een leeg body.

Failure Modes

  • Name
    400 - Bad Request
    Description

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

  • Name
    404 - Not Found
    Description

    De taak bestaat niet, hoort bij 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.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 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 één event: error payload met status_code: 404 terug 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. Voor taken met status PENDING of IN_PROGRESS bevat de responsstream alleen de noodzakelijke velden progress en status.

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

Collapsible Fidget-taken opvragen

Haal een gepagineerde lijst op van uw collapsible fidget-taken. 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

    Maximale pagina-omvang. Het maximaal toegestane aantal is 100 items.

  • Name
    sort_by
    Type
    string
    standaard -created_at
    Description

    Veld om op te sorteren. Beschikbare waarden:

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

Retourwaarden

Retourneert een gepagineerde lijst van het collapsible fidget-taakobject.

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

Het Collapsible Fidget Task-object

Het Collapsible Fidget Task-object is een werkeenheid die Meshy bijhoudt om een bronfoto om te zetten in een print-in-place inklapbaar fidgetmodel. Het is een eenfasige taak: er is geen prototype om vanaf 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, mag u geen aannames doen over het formaat 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 de 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. Retourneert 0 voor FAILED-taken (credits worden terugbetaald bij een mislukking).

  • Name
    model_urls
    Type
    object
    Description

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

    • 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 hiervan zijn alleen ter voorbeeld: STL bevat geen kleur, en een geprinte fidget krijgt zijn kleur van het filament. Het GLB-bestand is best-effort: wanneer de voorbeeldweergave niet beschikbaar is, wordt de key volledig weggelaten uit model_urls, dus lees het 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.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=***"
  }
}