API di stampa multicolore

Converti un modello 3D in un file 3MF multicolore per la stampa 3D. Scegli una palette fino a 16 colori e un preset dello slicer per la marca della tua stampante.

POST/openapi/v1/print/multi-color

Crea un task di stampa multicolore

Crea un task di stampa multicolore, che converte un modello 3D in un file 3MF multicolore per la stampa 3D. Il task viene eseguito in background. Per sapere quanto dura di solito un task, vedi Tempi di elaborazione.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to a multi-color 3MF with a Creality slicer preset
curl https://api.meshy.ai/openapi/v1/print/multi-color \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "max_colors": 8,
    "printer_brand": "creality"
  }'

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}

Parametri

Name
input_task_id
Type
string
Obbligatorio
Description
Obbligatorio a meno che non invii model_url. L'ID del task il cui modello vuoi stampare, ad esempio un task Immagine in 3D, Multi-immagine in 3D, Testo in 3D, Remesh o Retexture. Il task deve essere uno che hai creato con l'API e avere lo stato SUCCEEDED.
La stampa multicolore legge il file GLB del task, che può avere al massimo 8.000.000 di facce. Un modello con più facce restituisce 400. In tal caso, esegui prima un task Remesh su di esso, e invia l'ID del task Remesh al suo posto.

Name
model_url
Type
string
Obbligatorio
Description
Obbligatorio a meno che non invii input_task_id. Il modello da stampare, come URL pubblico o Data URI. Se invii entrambi, Meshy usa input_task_id.
Un URL http o https deve puntare a un file .glb o .fbx di massimo 400 MB. Un Data URI deve contenere un file GLB in base64 di massimo 100 MB. Usa data:model/gltf-binary;base64,. Invia un file .fbx come URL http o https.
Un file oltre 100 MB deve anche rispettare queste regole:
- Può avere al massimo 8.000.000 di facce. Meshy conta le facce come triangoli, quindi un quad conta come 2, e una mesh disegnata più volte conta una volta per copia.
- Un file FBX deve essere FBX binario 7.1 o successivo.
- Un file GLB non deve usare la compressione Draco.

Name
max_colors
Type
integer
predefinito 4
Description
Il numero massimo di colori nella palette di output, da 1 a 16. Per usare il valore predefinito, ometti il parametro invece di inviare 0.
Name
style
Type
string
predefinito realistic
Description
Lo stile di colore del file 3MF.
Valori disponibili:
- realistic: campiona i colori direttamente dalla texture del modello per un dettaglio fine e fotorealistico, e produce un file più grande.
- cartoon: appiattisce i colori in regioni uniformi e pulite per un aspetto stilizzato, e produce un file più piccolo.
Il modello deve avere colore. realistic richiede una singola texture di colore base, con UV su ogni parte della mesh, mentre cartoon accetta anche i colori dei vertici. Meshy rifiuta un modello senza texture (bianco). Vedi model_missing_texture.
Name
max_depth
Type
integer
predefinito 4
Description
La profondità di suddivisione che Meshy usa per campionare i colori della texture sulla mesh, da 3 a 6. 0 equivale a omettere il parametro. Valori più alti catturano un dettaglio di colore più fine e producono un file più grande. Solo lo stile realistic lo usa, mentre cartoon lo ignora.
Name
printer_brand
Type
string
predefinito bambu
Description
La marca di stampante il cui preset slicer Meshy scrive nel file 3MF. Il file si apre quindi nello slicer di quella marca con un profilo corrispondente di stampante, filamento e processo. Il preset usa la stampante predefinita della marca, con un ugello da 0,4 mm.
Valori disponibili:
- bambu
- anycubic
- creality
- elegoo
- flashforge
- prusa
- qidi
- snapmaker
- ankermake
Qualsiasi altro valore restituisce 400.

Valori restituiti

Il campo result della risposta contiene l'ID del nuovo task di stampa multicolore.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Il messaggio di errore indica quale problema ha trovato. Ad esempio:
- Parametro mancante: Non è stato inviato né model_url né input_task_id.
- Formato modello non valido: Il file model_url non è un file .glb o .fbx.
- URL non raggiungibile: Meshy non può scaricare il file model_url.
- File modello troppo grande: Il file model_url supera i 400 MB da un URL http o https, oppure supera i 100 MB come Data URI.
- Troppe facce: Il file model_url supera i 100 MB e ha più di 8.000.000 di facce. Riduci il numero di facce, poi invia di nuovo il file.
- FBX ASCII oltre 100 MB: Il file model_url è un FBX ASCII oltre i 100 MB. Inviarlo come FBX binario o GLB.
- File modello illeggibile: Il file model_url supera i 100 MB, e Meshy non riesce a leggerne l'header. Ad esempio, è un GLB compresso con Draco, o un FBX binario precedente alla versione 7.1.
- Header del modello troppo complesso: Il file model_url supera i 100 MB, e il suo header ha troppe mesh, nodi o record da verificare. Riduci il numero di oggetti nel file, poi invialo di nuovo.
- Task di input non valido: input_task_id non è un task riuscito.
- Troppe facce nel task di input: Il modello di input_task_id ha più di 8.000.000 di facce. Esegui un task Remesh su di esso, poi invia l'ID del task Remesh al suo posto.
- max_colors non valido: max_colors è negativo o superiore a 16.
- style non valido: style non è realistic né cartoon.
- max_depth non valido: max_depth è fuori dall'intervallo 3-6, e non è 0.
- printer_brand non valido: printer_brand non è uno dei suoi valori disponibili.
- Nessuna fonte di colore: Al modello manca il colore richiesto da style. realistic richiede una singola texture di colore base, con UV, su ogni parte della mesh. cartoon accetta una texture di colore base o colori dei vertici. Applica prima la texture al modello, oppure usa cartoon per un modello con colori dei vertici. Meshy verifica un caricamento .fbx solo dopo che il task lo ha normalizzato, quindi il task fallisce con model_missing_texture invece.
Correggi la richiesta, poi invia di nuovo. Vedi Errori.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'header Authorization.
Name
402 - Payment Required
Description
Ad esempio:
- Crediti insufficienti: L'account non ha abbastanza crediti per questo task, oppure l'account ha raggiunto un limite di crediti. Controlla il tuo saldo crediti, poi riprova.
- Piano gratuito: La creazione di un task richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, poi riprova.
Name
403 - Forbidden
Description
input_task_id è un modello a bassorilievo, che questo endpoint non può stampare. Il messaggio è This model type does not support this operation. Invia un modello diverso.
Name
404 - Not Found
Description
input_task_id non corrisponde a nessuno dei tuoi task. Controlla l'ID del task, poi invia di nuovo la richiesta.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza. Attendi, poi riprova. Vedi Limiti di frequenza.

GET/openapi/v1/print/multi-color/:id

Recupera un task di stampa multicolore

Restituisce un task di stampa multicolore in base al suo ID.

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

Parametri

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

Restituisce

L'oggetto task di stampa multicolore.

DELETE/openapi/v1/print/multi-color/:id

Elimina un'attività di stampa multicolore

Elimina definitivamente un'attività di stampa multicolore, inclusi i suoi modelli e dati. Non è possibile annullare un'eliminazione.

Request

DELETE

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

Parametri del percorso

Name
id
Type
path
Description
L'ID dell'attività da eliminare.

Stato dell'attività

Eliminare un'attività PENDING rimborsa i crediti utilizzati al momento della sua creazione.

Un'attività IN_PROGRESS non può essere eliminata. La richiesta restituisce 409 Conflict, e l'attività continua a essere eseguita. Meshy non rimborsa un'attività che è già iniziata, quindi eliminarla ti farebbe perdere sia i crediti sia il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, poi eliminala.

Eliminare un'attività in uno stato finale (SUCCEEDED, FAILED o CANCELED) non rimborsa i suoi crediti.

Restituisce

200 OK quando l'attività viene eliminata, oppure 409 Conflict quando l'attività è IN_PROGRESS.

GET/openapi/v1/print/multi-color

Elenca i task di Multi-Color Print

Restituisce un elenco dei tuoi task di Multi-Color Print.

Request

GET

/openapi/v1/print/multi-color

curl https://api.meshy.ai/openapi/v1/print/multi-color?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-multi-color",
    "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
  "consumed_credits": 10
  }
]

Parametri

Name
page_num
Type
integer
predefinito 1
Description
Il numero di pagina da restituire. I numeri di pagina iniziano da 1.
Name
page_size
Type
integer
predefinito 10
Description
Il numero di task per pagina, fino a 100.
Name
sort_by
Type
string
Description
L'ordine di ordinamento.
Valori disponibili:
- +created_at: dal più vecchio
- -created_at: dal più recente

Restituisce

Un elenco paginato di oggetti task Multi-Color Print.

GET/openapi/v1/print/multi-color/:id/stream

Esegui lo streaming di un task di stampa multicolore

Esegue lo streaming degli aggiornamenti di un task di stampa multicolore come Server-Sent Events (SSE).

Request

GET

/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream

curl -N https://api.meshy.ai/openapi/v1/print/multi-color/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-multi-color",
  "model_urls": {
    "3mf": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.3mf?Expires=***"
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

Parametri

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

Valori restituiti

Uno stream di oggetti task di stampa multicolore come Server-Sent Events.

Ogni evento contiene l'oggetto task completo, nello stesso formato restituito dall'endpoint Get. Mentre il task è PENDING o IN_PROGRESS, i suoi campi di risultato non hanno ancora valori.

L'oggetto task di stampa multicolore

Un oggetto task di stampa multicolore descrive una conversione di un modello 3D in un file 3MF multicolore. Contiene lo stato, il progress e il file 3MF quando il task ha successo.

The 3D Print Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-multi-color",
  "model_urls": {
      "3mf": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.3mf?Expires=***"
},
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
"consumed_credits": 10
}

Name
id
Type
string
Description
L'ID del task. Trattalo come una stringa opaca e non fare affidamento sul suo formato.
Name
type
Type
string
Description
Il tipo di task, sempre print-multi-color.
Name
model_urls
Type
object
Description
URL di download per il modello stampato, uno per ogni formato di file. Un formato che il task non ha generato non ha una chiave, anziché una stringa vuota.
- Name
  3mf
  Type
  string
  Description
  Il file 3MF multicolore.
Name
progress
Type
integer
Description
Quanta parte del task è stata completata, in percentuale. È 0 finché il task non inizia e 100 quando ha successo.
Name
status
Type
string
Description
Lo stato del task, uno tra PENDING, IN_PROGRESS, SUCCEEDED o FAILED.
Name
preceding_tasks
Type
integer
Description
Il numero di task che precedono questo nella coda. Il valore è significativo solo mentre il task è PENDING.
Name
created_at
Type
timestamp
Description
Ora di creazione del task, in millisecondi Unix.
Name
started_at
Type
timestamp
Description
Ora di avvio del task, in millisecondi Unix. È 0 finché il task non inizia.
Name
finished_at
Type
timestamp
Description
Ora di completamento del task, in millisecondi Unix. È 0 finché il task non termina.
Name
task_error
Type
object
Description
I dettagli dell'errore quando il task fallisce. Vedi Errori.
Name
consumed_credits
Type
integer
Description
Il numero di crediti utilizzati dal task. Presente quando lo stato è PENDING, IN_PROGRESS o SUCCEEDED. È 0 per un task FAILED, perché Meshy rimborsa i crediti quando un task fallisce.