Creative Lab — API Collapsible Fidget

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

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

A differenza degli altri endpoint di Creative Lab, questo non ha nessuna coppia di fasi prototipo/build — non ci sono candidati intermedi tra cui scegliere, quindi un singolo task porta l'immagine fino in fondo, ovvero a un modello 3D. Anche i controlli della 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 costruito con gli stessi valori predefiniti lato server.

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

Crea un'attività Fidget Pieghevole

Genera un modello di fidget pieghevole a partire da una foto sorgente. Fai riferimento a The Collapsible Fidget Task Object 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 pieghevole. Attualmente supportiamo i formati .jpg, .jpeg, .png e .webp.
Ci sono due modi per fornire l'immagine:
- URL accessibile pubblicamente: un URL accessibile dalla rete pubblica.
- 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 silhouette è 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à a scopo 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à dell'attività fidget pieghevole appena creata. Effettua il polling dell'endpoint Get a Task 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 immagine fuori intervallo: l'immagine è troppo piccola, supera la dimensione massima del file o supera il numero massimo di pixel.
- URL non raggiungibile: non è stato possibile scaricare image_url (404 o timeout).
- Data URI non valido: la stringa base64 è malformata.
- Contenuto segnalato: l'immagine fornita è stata segnalata dalla moderation NSFW.
Name
401 - Unauthorized
Description
Autenticazione non riuscita. Controlla la tua chiave API.
Name
402 - Payment Required
Description
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 fornita è 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 una Collapsible Fidget Task

Recupera una collapsible fidget task dato un id di task valido. Solo le task create tramite questo endpoint sono raggiungibili qui — una task 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 della collapsible fidget task da recuperare.

Valori restituiti

La risposta contiene l'oggetto collapsible fidget task.

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'attività Fidget Collapsible

Annulla un'attività fidget collapsible. Se l'attività è ancora PENDING, i crediti consumati al momento della creazione vengono rimborsati. Le attività già IN_PROGRESS vengono annullate senza rimborso (il worker potrebbe già star consumando risorse). Le attività che hanno già raggiunto uno stato finale (SUCCEEDED, FAILED, CANCELED) non possono essere annullate.

Parametri del percorso

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

Restituisce

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

Modalità di errore

Name
400 - Bad Request
Description
L'attività si trova già in uno stato finale e non può essere annullata.
Name
404 - Not Found
Description
L'attività non esiste, appartiene a un altro utente o non è stata creata 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

Effettuare lo streaming di un'attività Fidget Collapsible

Effettua 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 event: error payload con status_code: 404 e chiude lo stream.

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività fidget collapsible da monitorare in streaming.

Valori restituiti

Restituisce uno stream di oggetti attività Collapsible Fidget come Server-Sent Events. Per le attività PENDING o IN_PROGRESS, lo stream di risposta includerà solo i campi progress e status necessari.

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.
// 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.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 Attività Fidget Pieghevoli

Recupera un elenco paginato delle tue attività fidget pieghevoli. Sono incluse solo le attività create 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.

Restituisce

Restituisce un elenco paginato di oggetto attività fidget pieghevole.

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 di partenza in un modello fidget pieghevole stampabile in un unico pezzo (print-in-place). È un'attività a fase singola: non esiste un prototipo da cui concatenare, e la silhouette intermedia non fa parte della risposta.

Proprietà

Name
id
Type
string
Description
Identificatore univoco dell'attività. Sebbene come dettaglio implementativo utilizziamo un UUID k-sortable per gli id delle attività, non dovresti fare alcuna assunzione sul formato dell'id.
Name
type
Type
string
Description
Tipo dell'attività. Il valore è creative-lab-fidget-collapsible.
Name
name
Type
string
Description
Il nome dell'attività fornito al momento della creazione. Stringa vuota se non è stato fornito alcun nome.
Name
status
Type
string
Description
Stato dell'attività. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Avanzamento dell'attività (progress). Se l'attività non è ancora iniziata, questa proprietà sarà 0. Una volta che l'attività è andata a buon fine, diventerà 100.
Name
created_at
Type
timestamp
Description
Timestamp di quando l'attività è stata creata, 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 in Meshy API.
Name
started_at
Type
timestamp
Description
Timestamp di quando l'attività è stata avviata, in millisecondi. Se l'attività non è ancora iniziata, questa proprietà sarà null.
Name
finished_at
Type
timestamp
Description
Timestamp di quando l'attività è stata completata, in millisecondi. Se l'attività non è ancora terminata, questa proprietà sarà null.
Name
expires_at
Type
timestamp
Description
Timestamp di quando il risultato dell'attività scade, in millisecondi.
Name
preceding_tasks
Type
integer
Description
Il conteggio delle attività precedenti.
Il valore di questo campo è significativo solo se lo stato dell'attività è PENDING.
Name
task_error
Type
object
Description
Dettagli dell'errore per le attività non riuscite. Vedi Errori per il riferimento completo dell'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questa attività. Presente quando lo stato dell'attività è PENDING, IN_PROGRESS o SUCCEEDED. Restituisce 0 per le attività 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 l'attività ha SUCCEEDED: stl è sempre presente, glb solo quando il render di anteprima è riuscito.
- Name
  stl
  Type
  string
  Description
  URL scaricabile per il file STL. Questo è il deliverable 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 per l'anteprima: l'STL non porta alcun colore, e un fidget stampato assume il colore del filamento. Il GLB viene fornito con il massimo impegno (best-effort): quando il render di anteprima non è disponibile, la chiave viene omessa del tutto da model_urls, quindi leggila in modo defensivo — stl è il deliverable ed è sempre presente su un'attività 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=***"
  }
}