Creative Lab Collapsible Fidget API

Trasforma una foto in un giocattolo fidget pieghevole stampabile in un pezzo unico con una sola attività. La sagoma del soggetto diventa una serie di anelli concentrici annidati che si comprimono piatti e si allungano di nuovo. Il giocattolo viene stampato in un unico pezzo, senza assemblaggio.

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

A differenza degli altri endpoint di Creative Lab, questo non ha fasi separate di prototipo e build. Non ci sono immagini candidate tra cui scegliere, quindi un'unica attività trasforma la foto in un modello 3D.

Anche la richiesta non ha impostazioni di geometria. L'app web consente di impostare dimensione, numero di strati, larghezza del varco, spessore parete, profondità di estrusione e rigonfiamento. Ogni attività API utilizza per questi gli stessi valori predefiniti.

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

Crea un'attività Collapsible Fidget

Genera un modello fidget collassabile a partire da una foto. Per i campi dell'attività, vedi L'oggetto Collapsible Fidget task.

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

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

Parametri

Name
image_url
Type
string
Obbligatorio
Description
La foto da trasformare in un fidget collassabile, come URL pubblico o data URI (data:image/jpeg;base64,<i tuoi dati immagine codificati in base64>).
L'immagine deve essere un file JPG, JPEG, PNG o WebP di massimo 20 MB.
La silhouette del soggetto diventa gli anelli, quindi un soggetto con un unico contorno chiuso e ben definito funziona meglio. Uno sfondo affollato, più soggetti separati, o forme molto sottili possono lasciare troppo poca area per le pareti annidate. In tal caso, l'attività fallisce.
Name
name
Type
string
Description
Un nome per l'attività, fino a 100 caratteri. Viene restituito nel campo name dell'attività e Meshy non lo incide sul modello. Un nome più lungo restituisce 400.

Restituisce

Il campo result contiene l'ID della nuova attività. Recupera l'attività o trasmettila in streaming finché status non è SUCCEEDED. Poi scarica il file STL stampabile da model_urls.stl. Per visualizzare prima un'anteprima del modello, scarica il file GLB da model_urls.glb quando è presente.

Modalità di fallimento

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Ad esempio:
- image_url è mancante.
- L'immagine non è un file JPG, JPEG, PNG o WebP.
- L'immagine è troppo piccola, supera i 20 MB, oppure supera il numero massimo di pixel.
- Meshy non riesce a scaricare l'immagine, ad esempio perché l'URL restituisce 404 o va in timeout.
- Il data URI non è un base64 valido.
- L'immagine è stata segnalata come NSFW.
Il messaggio di errore indica quale problema è stato rilevato. Correggi la richiesta, quindi inviala di nuovo.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'header Authorization.
Name
402 - Payment Required
Description
Si applica una di queste condizioni:
- L'account non ha crediti sufficienti.
- La chiave API, lo spazio di lavoro o il membro ha raggiunto il proprio limite di crediti.
- L'account è su un piano gratuito.
Controlla i tuoi crediti e il tuo piano, quindi riprova.
Name
403 - Forbidden
Description
Il tuo team ha attivato il Filtraggio IP, e Meshy ha segnalato l'immagine per proprietà intellettuale di terzi. Invia un'immagine che hai il diritto di usare.
Name
429 - Too Many Requests
Description
È stato raggiunto uno di questi limiti:
- Hai inviato più richieste di quante ne consenta il tuo limite di frequenza. Attendi alcuni secondi, quindi riprova. Vedi Limiti di frequenza.
- Troppe tue attività sono in coda o in esecuzione. Attendi che alcune terminino, quindi riprova.
- Su un piano illimitato senza crediti residui, hai raggiunto il numero di attività che possono essere eseguite senza crediti. Attendi che un'attività finisca, oppure aggiungi crediti.
Name
500 - Internal Server Error
Description
Meshy ha riscontrato un errore del server, ad esempio perché non è riuscita a eseguire il controllo sulla proprietà intellettuale dell'immagine. Meshy non crea l'attività e rimborsa eventuali crediti addebitati. Riprova la richiesta.

GET/openapi/creative-lab/fidget-collapsible/v1/:id

Recupera un'attività Collapsible Fidget

Restituisce un'attività Collapsible Fidget. Vengono restituite solo le attività create con questo endpoint. Un'attività creata da un altro endpoint di Creative Lab, o creata nell'app web, restituisce 404.

Per i campi, vedi L'oggetto attività Collapsible Fidget.

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

Parametri

Name
id
Type
path
Description
L'ID dell'attività dalla risposta di creazione.

Restituisce

L'oggetto attività Collapsible Fidget.

Modalità di errore

Name
400 - Bad Request
Description
id non è un ID attività valido. Invia l'ID result dalla risposta di creazione.
Name
403 - Forbidden
Description
Il tuo team ha il filtraggio IP attivato, e Meshy ha segnalato l'immagine dell'attività per proprietà intellettuale di terzi. I team con piano Enterprise non ricevono questo errore. Crea un'attività da un'immagine di cui hai i diritti d'uso.
Name
404 - Not Found
Description
Nessuna attività Collapsible Fidget con questo ID appartiene al tuo account, oppure l'attività non è stata creata con questo endpoint. Controlla l'ID.
Name
500 - Internal Server Error
Description
Meshy non è riuscito a eseguire il controllo sulla proprietà intellettuale. Riprova la richiesta.

DELETE/openapi/creative-lab/fidget-collapsible/v1/:id

Eliminare un task Collapsible Fidget

Annulla un task Collapsible Fidget. Annullare un task PENDING rimborsa i suoi crediti. Un task IN_PROGRESS viene annullato senza rimborso, perché un worker lo ha già avviato. Un task con uno stato finale (SUCCEEDED, FAILED o CANCELED) non può essere annullato.

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).

Parametri del percorso

Name
id
Type
path
Description
L'ID del task da annullare.

Valori restituiti

204 No Content con un corpo vuoto.

Modalità di errore

Name
400 - Bad Request
Description
Si applica uno dei seguenti casi:
- id non è un ID di task valido. Invia l'ID result ricevuto dalla risposta di creazione.
- Il task ha già uno stato finale (SUCCEEDED, FAILED o CANCELED), quindi non può essere annullato.
Name
404 - Not Found
Description
Nessun task Collapsible Fidget con questo ID appartiene al tuo account, oppure il task non è stato creato con questo endpoint. Controlla l'ID.

GET/openapi/creative-lab/fidget-collapsible/v1/:id/stream

Esegui lo streaming di un'attività Collapsible Fidget

Esegue lo streaming degli aggiornamenti di un'attività Collapsible Fidget come Server-Sent Events (SSE). Se l'attività non esiste o non è stata creata con questo endpoint, lo stream invia un evento error con status_code: 404 e si chiude.

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 following PENDING frame is shortened 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=***"
  }
}

Parametri

Name
id
Type
path
Description
L'ID dell'attività dalla risposta di creazione.

Restituisce

Uno stream di oggetti attività Collapsible Fidget. Ogni evento contiene l'oggetto attività completo, così come lo restituisce Recupera un'attività Collapsible Fidget. Mentre l'attività è PENDING o IN_PROGRESS, i suoi campi di output sono ancora vuoti (null, [] o {}), e finished_at è null.

Se il Filtraggio IP blocca il risultato dell'attività, lo stream invia al suo posto un evento error, con lo status_code che restituirebbe una richiesta get.

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

Elenca i task Collapsible Fidget

Restituisce i tuoi task Collapsible Fidget, una pagina alla volta. Sono inclusi solo i task creati con questo endpoint.

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

Parametri della query

Name
page_num
Type
integer
predefinito 1
Description
La pagina da restituire, da 1 a 255. 0 restituisce la prima pagina. Un valore al di fuori dell'intervallo 0-255 restituisce 400.
Name
page_size
Type
integer
predefinito 10
Description
Numero di task per pagina, fino a 100. Un valore da 101 a 255 restituisce 100 task, e 0 utilizza il valore predefinito. Un valore al di fuori dell'intervallo 0-255 restituisce 400.
Name
sort_by
Type
string
predefinito -created_at
Description
L'ordine di ordinamento.
Valori disponibili:
- -created_at: prima i più recenti
- +created_at: prima i più vecchi

Restituisce

Un array di oggetti task Collapsible Fidget.

L'oggetto task Collapsible Fidget

Un task Collapsible Fidget trasforma una foto in un modello di fidget pieghevole stampabile in un solo pezzo (print-in-place). È un task a stadio singolo, quindi non c'è un task prototipo da cui concatenarlo. La risposta non include la silhouette che Meshy crea durante il processo.

Proprietà

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

Name
id
Type
string
Description
L'ID del task. Non fare affidamento sul suo formato.
Name
type
Type
string
Description
Il tipo di task, sempre creative-lab-fidget-collapsible.
Name
name
Type
string
Description
Il name inviato alla creazione del task, oppure "" se non ne hai inviato uno.
Name
status
Type
string
Description
Lo stato del task.
Valori disponibili:
- PENDING: in attesa in coda
- IN_PROGRESS: generazione del risultato in corso
- SUCCEEDED: finale, con il risultato
- FAILED: finale, con il motivo in task_error
- CANCELED: finale, senza risultato
Name
progress
Type
integer
Description
Percentuale di lavoro completato, da 0 a 100. È 0 finché il task non inizia e 100 quando ha successo.
Name
created_at
Type
timestamp
Description
Momento di creazione del task, in millisecondi Unix.
Name
started_at
Type
timestamp
Description
Momento in cui un worker ha avviato il task, in millisecondi Unix. null fino ad allora.
Name
finished_at
Type
timestamp
Description
Momento in cui il task ha raggiunto uno stato finale, in millisecondi Unix. null fino ad allora.
Name
expires_at
Type
timestamp
Description
Momento in cui il risultato del task scade, in millisecondi Unix. Sono 3 giorni dopo finished_at, oppure 3 giorni dopo created_at finché il task non termina. Per gli account Enterprise, che conservano i risultati delle API a tempo indeterminato, è circa 100 anni dopo. Vedi Conservazione degli asset.
Name
preceding_tasks
Type
integer
Description
La posizione del task in coda mentre è PENDING. 1 significa che parte per prossimo. 0 dopo che il task esce dalla coda, e sempre 0 nei risultati degli elenchi.
Name
task_error
Type
object
Description
Il motivo per cui il task è fallito. null a meno che status non sia FAILED. Vedi Errori.
Name
consumed_credits
Type
integer
Description
Numero di crediti addebitati per il task, dopo eventuali rimborsi. Una richiesta che restituisce un errore non viene addebitata. Un task fallito è 0, perché Meshy lo rimborsa. L'annullamento rimborsa un task solo mentre è PENDING. Se Meshy non riesce a leggere l'addebito, una risposta get o stream omette il campo, e una richiesta di elenco restituisce 500. In quel caso, riprova la richiesta.
Name
model_urls
Type
object
Description
URL di download per il modello 3D, vuoto finché il task non ha successo. Un task riuscito ha sempre stl, e ha glb solo se Meshy ha renderizzato l'anteprima.
- Name
  stl
  Type
  string
  Description
  URL di download per il file STL, che è il file da stampare. Puoi aprirlo direttamente in uno slicer.
- Name
  glb
  Type
  string
  Description
  URL di download per un file GLB per visualizzare in anteprima il modello in un visualizzatore 3D. I suoi colori sono solo per l'anteprima. Il file STL non ha colore, quindi il fidget stampato prende il colore dal filamento.
  Se Meshy non riesce a renderizzare l'anteprima, model_urls non ha la chiave glb, quindi controlla la presenza della chiave prima di leggerla. Un task SUCCEEDED ha sempre stl.