API Creative Lab Fidget Pixel

Trasforma una foto in una tavola fidget pixel-art multicolore, stampabile in 3D, in due fasi. Un'attività di prototipo trasforma la foto in un'immagine pixel-art. Un'attività di build trasforma quell'immagine in pezzi incastrabili in un unico file 3MF, e prende l'ID dell'attività di prototipo come input_task_id.

POST /openapi/creative-lab/fidget-pixel/v1/prototype
POST /openapi/creative-lab/fidget-pixel/v1/build

Entrambi gli endpoint POST richiedono un piano a pagamento. Una richiesta da un account con piano gratuito restituisce 402.

POST/openapi/creative-lab/fidget-pixel/v1/prototype

Crea un'attività di prototipo Fidget Pixel

Genera un'immagine pixel-art da una foto. Per costruire i pezzi, passa l'ID di questa attività all'endpoint di build come input_task_id. Per i campi dell'attività, vedi L'oggetto attività di prototipo Fidget Pixel.

Se l'immagine non ti piace, crea un'altra attività di prototipo. Ogni attività viene addebitata separatamente.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/prototype

# Stage 1: pixelize the source photo
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype \
  -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>",
    "type": "person"
  }'

Response

{
  "result": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7"
}

Parametri

Name
image_url
Type
string
Obbligatorio
Description
La foto da trasformare in pixel art, 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 al massimo 20 MB. Meshy rileva il formato dai dati dell'immagine, non dall'estensione del file nell'URL. Un URL senza estensione funziona, e Meshy segue i redirect.
Name
type
Type
string
Obbligatorio
Description
Cosa mostra la foto, il che determina lo stile della pixel art. I due stili appaiono chiaramente diversi. Qualsiasi altro valore restituisce 400.
Valori disponibili:
- person: una persona, in un ritratto o in una foto a figura intera. Meshy disegna uno sprite pixel in stile chibi.
- other: qualsiasi altro soggetto, ad esempio un animale domestico, un oggetto, una mascotte, un logo o un paesaggio. Meshy disegna un'icona pixel in stile bead-art.
Name
name
Type
string
Description
Un nome per l'attività, fino a 100 caratteri. Viene restituito nel campo name dell'attività. Un nome più lungo restituisce 400.

Restituisce

Il campo result contiene l'ID della nuova attività di prototipo. Recupera l'attività o trasmettila in streaming finché status non è SUCCEEDED. Quindi passa l'ID all'endpoint di build come input_task_id.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Ad esempio:
- Manca image_url o type.
- type non è person né other.
- L'immagine non è un file JPG, JPEG, PNG o WebP.
- L'immagine è troppo piccola, supera i 20 MB o 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 è una base64 valida.
- 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 è nel 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 utilizzare.
Name
429 - Too Many Requests
Description
È stato raggiunto uno di questi limiti:
- Hai inviato più richieste di quante il tuo limite di frequenza consenta. Attendi qualche secondo, quindi riprova. Vedi Limiti di frequenza.
- Troppe delle 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à termini, oppure aggiungi crediti.
Name
500 - Internal Server Error
Description
Meshy ha riscontrato un errore del server, ad esempio perché non è riuscito a eseguire il controllo di proprietà intellettuale sull'immagine. Meshy non crea l'attività, e rimborsa eventuali crediti addebitati. Riprova la richiesta.

POST/openapi/creative-lab/fidget-pixel/v1/build

Crea un task di build Fidget Pixel

Genera i pezzi stampabili in 3D a partire da un task di prototipo riuscito. Meshy campiona l'immagine pixel art sulla griglia e la riduce ad al massimo color_count colori. Ogni cella del soggetto diventa un pezzo a incastro, e lo sfondo non viene stampato.

Il risultato è un singolo file 3MF multicolore, pronto per la stampa a colori. Ogni pezzo ha un corpo grigio e una parte superiore del colore del suo pixel. Per i suoi campi, vedi L'oggetto task di build Fidget Pixel.

Request

POST

/openapi/creative-lab/fidget-pixel/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "options": {
      "shape": "square",
      "grid_size": 32,
      "piece_size_mm": 8,
      "color_count": 8,
      "piece_height_mm": 15
    },
    "output": {
      "format": "3mf"
    }
  }'

Response

{
  "result": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98"
}

Parametri

Name
input_task_id
Type
string
Obbligatorio
Description
L'ID del task di prototipo da compilare. Deve essere un task creato dal tuo account con POST /openapi/creative-lab/fidget-pixel/v1/prototype, con stato SUCCEEDED.
Un ID che non corrisponde a uno dei tuoi task di prototipo Fidget Pixel ottenuti tramite API restituisce 404, incluso un prototipo creato nell'app web.
Name
name
Type
string
Description
Un nome per il task, fino a 100 caratteri. Viene restituito nel campo name del task. Un nome più lungo restituisce 400.

`options`

Impostazioni per la forma e la dimensione dei pezzi. Ogni campo ha un valore predefinito, quindi invia solo i campi che vuoi modificare. Uno 0 utilizza il valore predefinito del campo. Sono le stesse impostazioni presenti nell'app web Creative Lab. Altre impostazioni di forma sono fisse e Meshy le imposta in base a shape e piece_size_mm.

Name
shape
Type
string
predefinito square
Description
L'ingombro di ogni pezzo. Qualsiasi altro valore restituisce 400.
Valori disponibili:
- square: pezzi quadrati su una griglia quadrata
- hex: pezzi esagonali su una griglia esagonale, con piece_size_mm impostato a 6 o 8
Name
grid_size
Type
integer
predefinito 32
Description
Il numero di celle della griglia lungo ciascun lato della tavola, 16 o 32. Qualsiasi altro valore restituisce 400. Una griglia 32 mantiene più dettagli. Una griglia 16 produce meno pezzi della stessa dimensione, quindi la tavola è larga circa la metà.
Name
piece_size_mm
Type
integer
predefinito 8
Description
La lunghezza del lato di ogni pezzo in millimetri, 6, 8 o 10. Qualsiasi altro valore restituisce 400. Insieme a grid_size, determina la dimensione della tavola stampata. Ad esempio, una griglia 32 di pezzi da 8 mm misura circa 26,5 cm per lato.
10 non funziona con hex e restituisce 400, perché la faccia esagonale inclinata sporge sulla maggior parte delle stampanti FDM consumer.
Name
color_count
Type
integer
predefinito 8
Description
Il numero massimo di colori nella tavolozza pixel art, da 1 a 8. Un valore fuori dall'intervallo restituisce 400. Per stampare, hai bisogno di un numero di filamenti pari a color_count più uno: uno per colore e uno per i corpi grigi.
Name
piece_height_mm
Type
integer
predefinito 15
Description
L'altezza di ogni pezzo in millimetri, da 10 a 80. Un valore fuori dall'intervallo restituisce 400.

`output`

Impostazioni per il file di risultato.

Name
format
Type
string
predefinito 3mf
Description
Il formato file del risultato. Qualsiasi altro valore restituisce 400.
Valori disponibili:
- 3mf: un singolo file multicolore model.3mf, restituito in model_urls.3mf

Restituisce

Il campo result contiene l'ID del nuovo task di build. Recupera il task o trasmettilo in streaming finché status non diventa SUCCEEDED. Quindi scarica il file 3MF da model_urls.3mf.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Ad esempio:
- input_task_id è mancante o non è un ID di task valido.
- Lo stato del task di prototipo non è SUCCEEDED. Se è ancora in esecuzione, attendi e riprova. Se è fallito o è stato annullato, crea un nuovo task di prototipo.
- Il task di prototipo è riuscito ma non ha un'immagine. Crea un nuovo task di prototipo.
- Un campo di options è fuori dai valori consentiti, ad esempio un grid_size diverso da 16 o 32.
- piece_size_mm è 10 e shape è hex. I pezzi esagonali sono disponibili solo in 6 e 8 mm.
- output.format non è 3mf.
Il messaggio di errore indica quale problema è stato rilevato.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'header Authorization.
Name
402 - Payment Required
Description
Si applica uno dei seguenti casi:
- 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 è sul piano gratuito.
Controlla i tuoi crediti e il tuo piano, poi riprova.
Name
403 - Forbidden
Description
Il tuo team ha attivato IP Filtering e Meshy ha segnalato l'immagine del task di prototipo per proprietà intellettuale di terzi. Crea un task di prototipo partendo da un'immagine di cui hai i diritti d'uso.
Name
404 - Not Found
Description
input_task_id non corrisponde a nessun task di prototipo Fidget Pixel creato dal tuo account tramite API. Anche un prototipo creato nell'app web restituisce 404. Invia l'ID result ottenuto da una risposta di creazione del prototipo.
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 qualche secondo, poi riprova. Vedi Limiti di frequenza.
- Troppi tuoi task sono in coda o in esecuzione. Attendi che alcuni terminino, poi riprova.
- Su un piano illimitato senza crediti residui, hai raggiunto il numero di task eseguibili senza crediti. Attendi che un task termini, 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 del task di prototipo. Meshy non crea il task e rimborsa eventuali crediti addebitati. Riprova la richiesta.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Recupera un task Fidget Pixel

Restituisce un task di tipo prototype o build. Il percorso deve corrispondere allo stage del task. Un task build richiesto tramite /prototype/:id restituisce 404, e lo stesso vale per un task prototype richiesto tramite /build/:id.

Per i campi, consulta L'oggetto task prototype di Fidget Pixel e L'oggetto task build di Fidget Pixel.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
  ]
}

Build Response

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Parametri

Name
id
Type
path
Description
L'ID del task dalla risposta di creazione.

Restituisce

L'oggetto task prototype o l'oggetto task build, a seconda dello stage indicato nel percorso.

Modalità di errore

Name
400 - Bad Request
Description
id non è un ID task valido. Invia l'ID result ricevuto nella risposta di creazione.
Name
403 - Forbidden
Description
Il tuo team ha attivato il Filtro IP, e Meshy ha segnalato l'immagine del task prototype per proprietà intellettuale di terzi. I task build e i team con piano Enterprise non ricevono questo errore. Crea un task prototype partendo da un'immagine su cui hai i diritti d'uso.
Name
404 - Not Found
Description
Nessun task Fidget Pixel con questo ID appartiene al tuo account, oppure lo stage del task non corrisponde al percorso. Controlla l'ID e usa /prototype o /build in base al task.
Name
500 - Internal Server Error
Description
Meshy non è riuscita a eseguire il controllo sulla proprietà intellettuale. Riprova la richiesta.

DELETE/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id

Elimina un'attività Fidget Pixel

Annulla un'attività Fidget Pixel. Annullare un'attività PENDING rimborsa i suoi crediti. Un'attività IN_PROGRESS viene annullata senza rimborso, perché un worker l'ha già avviata. Un'attività con uno stato finale (SUCCEEDED, FAILED o CANCELED) non può essere annullata.

Il percorso deve corrispondere alla fase dell'attività. Ad esempio, DELETE su /prototype/:id con l'ID di un'attività di build restituisce 404.

Request

DELETE

/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype/019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7 \
  -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 dell'attività da annullare.

Restituisce

204 No Content con un corpo vuoto.

Modalità di errore

Name
400 - Bad Request
Description
Si applica una delle seguenti condizioni:
- id non è un ID attività valido. Invia l'ID result dalla risposta di creazione.
- L'attività ha già uno stato finale (SUCCEEDED, FAILED o CANCELED), quindi non può essere annullata.
Name
404 - Not Found
Description
Nessuna attività Fidget Pixel con questo ID appartiene al tuo account, oppure la fase dell'attività non corrisponde al percorso. Controlla l'ID e usa /prototype o /build per far corrispondere l'attività.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)/:id/stream

Esegui lo streaming di un task Fidget Pixel

Esegue lo streaming degli aggiornamenti di un task Fidget Pixel come Server-Sent Events (SSE). Il percorso deve corrispondere alla fase del task. Se non corrisponde, ad esempio l'ID di un task di build su /prototype/:id/stream, lo stream invia un evento error con status_code: 404 e si chiude. Un id che non è un ID di task valido fa lo stesso con status_code: 400.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream

curl -N https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object for the stage; fields not yet populated are null / empty.
event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "PENDING",
  "progress": 0,
  "created_at": 1757001300000,
  "started_at": null,
  "finished_at": null,
  "expires_at": 1757260500000,
  "preceding_tasks": 2,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {}
}

event: message
data: {
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?Expires=***"
  }
}

Parametri

Name
id
Type
path
Description
L'ID del task dalla risposta di creazione.

Restituisce

Uno stream di oggetti task prototype o build. Ogni evento contiene l'oggetto task completo, come restituito da Recupera un task Fidget Pixel. Mentre il task è 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 del task, lo stream invia al suo posto un evento error, con lo status_code che una richiesta get restituirebbe.

GET/openapi/creative-lab/fidget-pixel/v1/(prototype|build)

Elenco dei task Fidget Pixel

Restituisce i tuoi task Fidget Pixel di una fase, una pagina alla volta. Il percorso seleziona la fase. /prototype restituisce solo i task di prototipo, e /build restituisce solo i task di build.

Request

GET

/openapi/creative-lab/fidget-pixel/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
    "type": "creative-lab-fidget-pixel-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1757001000000,
    "started_at": 1757001005000,
    "finished_at": 1757001178000,
    "expires_at": 1757260378000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/pixel-art.jpg?Expires=***"
    ]
  }
]

Parametri del percorso

Name
stage
Type
path
Obbligatorio
Description
La fase da elencare, prototype o build.

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 di prototipo o oggetti task di build, corrispondenti alla fase indicata nel percorso.

L'oggetto task di prototipo Fidget Pixel

Un task di prototipo trasforma una foto in un'immagine pixel-art. Per trasformare l'immagine in pezzi stampabili in 3D, passa l'ID del task all'endpoint di build come input_task_id.

Proprietà

Example Fidget Pixel Prototype Task Object

{
  "id": "019c4a1e-2b7d-7d03-8f6a-5c2e91f0a1b7",
  "type": "creative-lab-fidget-pixel-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001000000,
  "started_at": 1757001005000,
  "finished_at": 1757001178000,
  "expires_at": 1757260378000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/pixel-art.jpg?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-pixel-prototype.
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 del lavoro completato, da 0 a 100. È 0 finché il task non inizia e 100 quando ha successo.
Name
created_at
Type
timestamp
Description
Momento in cui il task è stato creato, 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. È 3 giorni dopo finished_at, oppure 3 giorni dopo created_at finché il task non termina. Per gli account Enterprise, che conservano i risultati API a tempo indeterminato, è circa 100 anni più tardi. 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 lascia la coda, e sempre 0 nei risultati di elenco.
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 tal caso, riprova la richiesta.
Name
image_urls
Type
array of strings
Description
URL di download per l'immagine pixel-art. L'array contiene un URL dopo che il task ha successo, ed è vuoto fino ad allora.
Gli URL sono firmati, quindi recuperali senza un header Authorization. Rimangono validi fino a expires_at. Ottenere nuovamente il task prima di allora restituisce gli stessi URL, non URL firmati di nuovo. Un URL scaduto non può essere aggiornato, quindi scarica e salva i file prima di allora.

L'oggetto task di build Fidget Pixel

Un task di build genera i pezzi stampabili in 3D a partire da un task di prototipo riuscito. Meshy campiona l'immagine pixel art sulla griglia e restituisce i pezzi in un unico file 3MF multicolore.

Proprietà

Example Fidget Pixel Build Task Object

{
  "id": "019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98",
  "type": "creative-lab-fidget-pixel-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1757001300000,
  "started_at": 1757001304000,
  "finished_at": 1757001309000,
  "expires_at": 1757260509000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 30,
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/019c4a2f-6e81-7b44-9a1d-0d7f3c5e2b98/output/model.3mf?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-pixel-build.
Name
name
Type
string
Description
Il name inviato durante la creazione del task, oppure "" se non ne è stato 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. Corrisponde a 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 inizierà come 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 tal caso, riprova la richiesta.
Name
model_urls
Type
object
Description
URL di download per il risultato, indicizzati per formato file. L'oggetto ha una sola voce, per il output.format inviato, ed è vuoto finché il task non ha successo.
Gli URL sono firmati, quindi recuperali senza un'intestazione Authorization. Rimangono validi fino a expires_at. Richiedere nuovamente il task prima di allora restituisce gli stessi URL, non URL firmati di nuovo. Un URL scaduto non può essere aggiornato, quindi scarica e salva i file prima di allora.
- Name
  3mf
  Type
  string
  Description
  URL di download per il file 3MF multicolore. Ogni pezzo ha un corpo grigio e una parte superiore del colore del suo pixel. Presente quando output.format è 3mf, che è il valore predefinito.

Esempio end-to-end

I seguenti script cURL e Python eseguono l'intero flusso. Ogni script crea un task di prototipo a partire da una foto e attende che vada a buon fine. Poi crea un task di build, attende il completamento di quel task e scarica il file 3MF da model_urls.3mf.

Lo script cURL richiede curl e jq, mentre lo script Python richiede il pacchetto requests. Per eseguire uno script, segui questi passaggi:

Imposta MESHY_API_KEY sulla tua chiave API.
Imposta IMAGE_PATH sul percorso di una foto locale, oppure IMAGE_URL su un URL pubblico dell'immagine.
Facoltativo: per pixelare un soggetto diverso da una persona, imposta PIXEL_TYPE su other.
Esegui lo script.

Un task di prototipo di solito termina nel giro di pochi minuti. Un task di build di solito termina in meno di un minuto.

Nella tua app, mostra all'utente l'immagine proveniente da image_urls prima di creare il task di build. Se non gli piace, crea invece un altro task di prototipo. In questo modo, spendi crediti di build solo per un'immagine che l'utente approva.

Complete flow

POST

/openapi/creative-lab/fidget-pixel/v1

#!/usr/bin/env bash
set -euo pipefail

# Requires curl and jq. Point IMAGE_PATH at a local photo, or IMAGE_URL at a public one:
#   export MESHY_API_KEY=msy_...
#   export IMAGE_PATH=./portrait.jpg          # or: export IMAGE_URL=https://...
#   export PIXEL_TYPE=person                  # or: other
: "${MESHY_API_KEY:?export MESHY_API_KEY first}"
if [[ -z "${IMAGE_PATH:-}" && -z "${IMAGE_URL:-}" ]]; then
  echo "export IMAGE_PATH (local file) or IMAGE_URL (public url) first" >&2
  exit 1
fi
PIXEL_TYPE=${PIXEL_TYPE:-person}

BASE="https://api.meshy.ai/openapi/creative-lab/fidget-pixel/v1"
AUTH="Authorization: Bearer $MESHY_API_KEY"

# api METHOD URL [curl args...] -> prints the response body, non-zero on failure.
# Note we do not use -f/--fail: it discards the body, and the body is the only
# place the reason appears.
api() {
  local method=$1 url=$2 out http_code body
  shift 2
  out=$(curl --silent --show-error --max-time 60 --write-out $'\n%{http_code}' \
    -X "$method" "$url" -H "$AUTH" "$@") || return 1
  http_code=${out##*$'\n'}
  body=${out%$'\n'*}
  if ((http_code >= 400)); then
    echo "HTTP $http_code for $url: $body" >&2
    return 1
  fi
  printf '%s' "$body"
}

# Each task gets its own 40-minute budget.
poll() {
  local kind=$1 id=$2 delay=5 task_status deadline
  deadline=$(($(date +%s) + 2400))
  while :; do
    if (($(date +%s) >= deadline)); then
      echo "gave up waiting for $kind $id" >&2
      return 1
    fi
    task_status=$(api GET "$BASE/$kind/$id" | jq -r '.status')
    echo "$kind: $task_status"
    case "$task_status" in
    SUCCEEDED) return 0 ;;
    FAILED | CANCELED) return 1 ;;
    esac
    sleep "$delay"
    delay=$((delay * 2 > 30 ? 30 : delay * 2))
  done
}

# Build the request body in a file. A base64 data URI must never go on the
# command line or into an exported variable - a photo of any real size will
# exceed the OS argument limit.
BODY=$(mktemp)
trap 'rm -f "$BODY"' EXIT
if [[ -n "${IMAGE_PATH:-}" ]]; then
  # Declare the real type: the API accepts JPEG, PNG and WebP.
  case "$(printf '%s' "${IMAGE_PATH##*.}" | tr 'A-Z' 'a-z')" in
    png) MIME=image/png ;;
    webp) MIME=image/webp ;;
    *) MIME=image/jpeg ;;
  esac
  {
    printf '{"type":"%s","image_url":"data:%s;base64,' "$PIXEL_TYPE" "$MIME"
    base64 <"$IMAGE_PATH" | tr -d '\n'
    printf '"}'
  } >"$BODY"
else
  jq -n --arg t "$PIXEL_TYPE" --arg u "$IMAGE_URL" \
    '{type: $t, image_url: $u}' >"$BODY"
fi

# 1. Create the prototype task
PROTO_ID=$(api POST "$BASE/prototype" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 2. Wait for the pixel-art image (show image_urls[0] to a user in production)
poll prototype "$PROTO_ID"

# 3. Create the build task (defaults: square pieces, 32x32 grid, 8 mm, 8 colors, 15 mm tall)
jq -n --arg p "$PROTO_ID" \
  '{input_task_id: $p, options: {shape: "square", grid_size: 32, piece_size_mm: 8, color_count: 8, piece_height_mm: 15}, output: {format: "3mf"}}' >"$BODY"
BUILD_ID=$(api POST "$BASE/build" \
  -H 'Content-Type: application/json' --data-binary @"$BODY" | jq -r '.result')

# 4. Wait for the pieces
poll build "$BUILD_ID"

# 5. Download the 3MF. This is a signed URL: no Authorization header,
#    and it stays valid for 3 days after the task finishes.
TASK=$(api GET "$BASE/build/$BUILD_ID")
curl --silent --show-error --fail --max-time 900 \
  -o fidget-pixel.3mf "$(jq -r '.model_urls["3mf"]' <<<"$TASK")"
echo "Done: fidget-pixel.3mf"