Creative Lab — Collapsible Fidget API

Trasforma una foto sorgente in un fidget toy pieghevole stampabile in un unico pezzo: la sagoma del soggetto diventa una serie di anelli concentrici annidati che si comprimono in piano e si allungano di nuovo, stampati in un solo pezzo senza bisogno di assemblaggio.

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

A differenza degli altri endpoint di Creative Lab, questo non prevede una coppia di fasi prototype/build — non ci sono candidati intermedi tra cui scegliere, quindi un singolo task porta l'immagine direttamente fino a un modello 3D. Anche i controlli di geometria esposti dalla web app (dimensione, numero di livelli, larghezza del gap, spessore parete, profondità di estrusione, rigonfiamento) non fanno parte della richiesta: ogni task viene generato con gli stessi valori predefiniti lato server.

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

Creare un'attività di Fidget Collassabile

Genera un modello di fidget collassabile a partire da una foto sorgente. Fai riferimento a L'oggetto Attività Fidget Collassabile per la forma della risposta.

Ogni attività costa 6 crediti e richiede un piano a pagamento.

Parametri

Name
image_url
Type
string
Obbligatorio
Description
Foto sorgente che Meshy trasformerà in un fidget collassabile. Attualmente supportiamo i formati .jpg, .jpeg, .png e .webp.
Ci sono due modi per fornire l'immagine:
- URL pubblicamente accessibile: un URL accessibile da internet pubblicamente.
- Data URI: un data URI dell'immagine codificato in base64. Esempio di data URI: data:image/jpeg;base64,<i tuoi dati immagine codificati in base64>.
Un soggetto con un contorno chiaro e chiuso funziona meglio: la sagoma è ciò che diventa gli anelli. Sfondi affollati, più soggetti separati o forme molto sottili possono lasciare troppo poco spazio per le pareti annidate, e l'attività fallisce con un errore di attività.
Name
name
Type
string
Description
Nome opzionale dell'attività per scopi di visualizzazione. Massimo 100 caratteri. Si tratta solo di un'etichetta dell'attività; nulla viene inciso sul modello.

Restituisce

La proprietà result della risposta contiene l'id dell'attività appena creata per il fidget collassabile. Interroga l'endpoint Recupera un'attività o iscriviti allo stream finché l'attività non raggiunge lo stato SUCCEEDED, quindi scarica l'STL stampabile da model_urls.stl (e, quando presente, il GLB da model_urls.glb per visualizzarlo prima in anteprima).

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante: image_url è obbligatorio.
- Formato immagine non valido: l'image_url fornito non è in un formato supportato (.jpg, .jpeg, .png, .webp).
- Dimensioni dell'immagine fuori intervallo: l'immagine è troppo piccola, supera la dimensione massima del file o supera il numero massimo di pixel.
- URL non raggiungibile: impossibile scaricare l'image_url (404 o timeout).
- Data URI non valido: la stringa base64 è malformata.
- Contenuto segnalato: l'immagine di input è stata segnalata dalla moderation NSFW.
Name
401 - Unauthorized
Description
Autenticazione fallita. Verifica la tua chiave API.
Name
402 - Payment Required
Description
O il tuo account è su un piano gratuito — la creazione di attività su questo endpoint richiede un piano a pagamento — oppure non hai crediti sufficienti.
Name
403 - Forbidden
Description
L'immagine di input è stata segnalata per violazione della proprietà intellettuale.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.

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

Recupera un'attività Fidget Collapsible

Recupera un'attività fidget collapsible dato un id di attività valido. Solo le attività create tramite questo endpoint sono accessibili qui — un'attività proveniente da un altro endpoint di Creative Lab, o una creata nell'app web, restituisce 404.

Fai riferimento a L'oggetto Collapsible Fidget Task per la struttura della risposta.

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività fidget collapsible da recuperare.

Valori restituiti

La risposta contiene l'oggetto dell'attività fidget collapsible.

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

Elimina un Collapsible Fidget Task

Annulla un collapsible fidget task. Se il task è ancora PENDING, i crediti consumati al momento della creazione vengono rimborsati. I task già IN_PROGRESS vengono annullati senza rimborso (è possibile che il worker stia già consumando risorse). I task che hanno già raggiunto uno stato terminale (SUCCEEDED, FAILED, CANCELED) non possono essere annullati.

Parametri del percorso

Name
id
Type
path
Description
Identificatore univoco del collapsible fidget task da annullare.

Restituisce

Restituisce 204 No Content in caso di successo con corpo vuoto.

Modalità di errore

Name
400 - Bad Request
Description
Il task si trova già in uno stato terminale e non può essere annullato.
Name
404 - Not Found
Description
Il task non esiste, appartiene a un altro utente o non è stato creato tramite questo 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

Esegui lo streaming di un'attività Fidget Collapsible

Esegui lo streaming degli aggiornamenti in tempo reale per un'attività fidget collapsible tramite Server-Sent Events (SSE). Un'attività che non esiste, o che non è stata creata tramite questo endpoint, emette un singolo payload event: error con status_code: 404 e chiude lo stream.

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività fidget collapsible di cui eseguire lo streaming.

Restituisce

Restituisce uno stream di oggetti attività Collapsible Fidget come Server-Sent Events. Ogni frame contiene l'oggetto attività completo relativo alla fase — la stessa struttura restituita dall' endpoint Get — quindi finché l'attività è in stato PENDING o IN_PROGRESS i campi di output semplicemente non sono ancora popolati (null, [] o {}) e 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

Elenca Task Collapsible Fidget

Recupera un elenco paginato dei tuoi task collapsible fidget. Sono inclusi solo i task creati tramite questo endpoint.

Parametri di query

Name
page_num
Type
integer
predefinito 1
Description
Numero di pagina per la paginazione.
Name
page_size
Type
integer
predefinito 10
Description
Limite di dimensione della pagina. Il massimo consentito è 100 elementi.
Name
sort_by
Type
string
predefinito -created_at
Description
Campo per l'ordinamento. Valori disponibili:
- +created_at: Ordina per data di creazione in ordine crescente.
- -created_at: Ordina per data di creazione in ordine decrescente.

Risultato

Restituisce un elenco paginato di oggetti task collapsible fidget.

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

L'oggetto Collapsible Fidget Task

L'oggetto Collapsible Fidget Task è un'unità di lavoro che Meshy tiene traccia per trasformare una foto sorgente in un modello di fidget spinner richiudibile stampabile in un unico pezzo. È un task a stadio unico: non esiste un prototipo da cui concatenare, e la silhouette intermedia non fa parte della risposta.

Proprietà

Name
id
Type
string
Description
Identificatore univoco del task. Sebbene per gli id dei task venga usato, come dettaglio implementativo, un UUID ordinabile per chiave (k-sortable), non si dovrebbe fare alcuna assunzione sul formato dell'id.
Name
type
Type
string
Description
Tipo del task. Il valore è creative-lab-fidget-collapsible.
Name
name
Type
string
Description
Il nome del task fornito al momento della creazione del task. Stringa vuota se non è stato fornito alcun nome.
Name
status
Type
string
Description
Stato del task. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progresso del task. Se il task non è ancora iniziato, questa proprietà sarà 0. Una volta che il task è andato a buon fine, diventerà 100.
Name
created_at
Type
timestamp
Description
Timestamp di quando il task è stato creato, in millisecondi.
Un timestamp rappresenta il numero di millisecondi trascorsi dal 1° gennaio 1970 UTC, seguendo lo standard RFC 3339. Ad esempio, venerdì 1° settembre 2023 12:00:00 PM GMT è rappresentato come 1693569600000. Questo si applica a tutti i timestamp nella Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp di quando il task è stato avviato, in millisecondi. Se il task non è ancora iniziato, questa proprietà sarà null.
Name
finished_at
Type
timestamp
Description
Timestamp di quando il task è terminato, in millisecondi. Se il task non è ancora terminato, questa proprietà sarà null.
Name
expires_at
Type
timestamp
Description
Timestamp di quando il risultato del task scade, in millisecondi.
Name
preceding_tasks
Type
integer
Description
Il conteggio dei task precedenti.
Il valore di questo campo è significativo solo se lo stato del task è PENDING.
Name
task_error
Type
object
Description
Dettagli dell'errore per i task falliti. Vedi Errori per il riferimento completo dell'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questo task. Presente quando lo stato del task è PENDING, IN_PROGRESS, o SUCCEEDED. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di fallimento).
Name
model_urls
Type
object
Description
URL scaricabili per il modello 3D generato. Popolato una volta che il task ha avuto esito SUCCEEDED: stl è sempre presente, glb solo quando il rendering di anteprima è andato a buon fine.
- Name
  stl
  Type
  string
  Description
  URL scaricabile per il file STL. Questo è il file finale stampabile: inviatelo direttamente a uno slicer.
- Name
  glb
  Type
  string
  Description
  URL scaricabile per il file GLB, per visualizzare in anteprima il modello in un visualizzatore 3D. I suoi colori sono solo a scopo di anteprima: STL non contiene alcun colore, e un fidget stampato assume il colore dal filamento. Il GLB viene fornito su base "best-effort": quando il rendering di anteprima non è disponibile, la chiave viene omessa del tutto da model_urls, quindi va letta in modo defensivo — stl è il file finale ed è sempre presente in un task 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=***"
  }
}