API di Stampa Multicolore

Converti modelli 3D nel formato 3MF multicolore per la stampa 3D, con una palette colori configurabile fino a 16 colori.

POST/openapi/v1/print/multi-color

Crea un Task di Stampa 3D Multi-Colore

Questo endpoint crea un nuovo task di stampa 3D multi-colore. Il task converte un modello 3D in un file 3MF multi-colore adatto per la stampa 3D.

Parametri

Solo uno tra input_task_id o model_url è richiesto. Se entrambi sono forniti, input_task_id ha priorità.

Name
input_task_id
Type
string
Obbligatorio
Description
L'ID di un task riuscito da utilizzare come input. Tipi di task supportati: Immagine in 3D, Multi-immagine in 3D, Testo in 3D, Remesh, e Retexture. Il task deve avere uno stato di SUCCEEDED.

Name
model_url
Type
string
Obbligatorio
Description
URL pubblicamente accessibile o Data URI di un modello 3D. Attualmente supportiamo i formati .glb e .fbx.

Name
max_colors
Type
integer
predefinito 4
Description
Numero massimo di colori nella palette di output.
Intervallo valido: 1 a 16.
Name
style
Type
string
predefinito realistic
Description
Stile visivo dei colori del file 3MF generato.
Valori disponibili:
- realistic: Campiona i colori direttamente dalla texture del modello per dettagli fini e foto-realistici. Produce un file più grande.
- cartoon: Appiattisce i colori in regioni pulite e uniformi per un aspetto stilizzato. Produce un file più piccolo.

Ritorni

La proprietà result della risposta contiene l'id del nuovo task di stampa 3D creato.

Modalità di Fallimento

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante: Devono essere forniti model_url o input_task_id.
- Formato modello non valido: Il model_url punta a un file con un'estensione non supportata (solo .glb e .fbx sono supportati).
- URL irraggiungibile: Il model_url non può essere scaricato.
- Task di input non valido: L'input_task_id deve riferirsi a un task riuscito.
- max_colors non valido: Il valore deve essere tra 1 e 16.
- Stile non valido: Il valore deve essere realistic o cartoon.
Name
401 - Unauthorized
Description
Autenticazione fallita. Si prega di controllare la propria chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questo task.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.

Request

POST

/openapi/v1/print/multi-color

# Convert a 3D model to multi-color 3MF for printing
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
  }'

Response

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

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

Recupera un'attività di stampa 3D multicolore

Questo endpoint recupera un'attività di stampa 3D multicolore tramite il suo ID.

Parametri

Name
id
Type
path
Description
L'ID dell'attività di stampa 3D da recuperare.

Restituisce

L'oggetto Attività di Stampa 3D.

Richiesta

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

Risposta

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

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

Elimina un'attività di stampa 3D multicolore

Questo endpoint elimina permanentemente un'attività di stampa 3D multicolore, inclusi tutti i modelli e i dati associati. Questa azione è irreversibile.

Parametri del percorso

Name
id
Type
path
Description
L'ID dell'attività di stampa 3D multicolore da eliminare.

Restituisce

Restituisce 200 OK in caso di successo.

Richiesta

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

Risposta

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

Elenco delle attività di stampa 3D multicolore

Questo endpoint ti consente di recuperare un elenco di attività di stampa 3D multicolore.

Parametri

Attributi opzionali

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

Restituisce

Restituisce un elenco paginato di Gli Oggetti di Attività di Stampa 3D.

Richiesta

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

Risposta

[
  {
    "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
  }
]

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

Trasmetti un'attività di stampa 3D multicolore

Questo endpoint trasmette aggiornamenti in tempo reale per un'attività di stampa 3D multicolore utilizzando Server-Sent Events (SSE).

Parametri

Name
id
Type
path
Description
Identificatore univoco per l'attività di stampa 3D multicolore da trasmettere.

Restituisce

Restituisce un flusso di Oggetti dell'attività di stampa 3D come Server-Sent Events.

Per le attività PENDING o IN_PROGRESS, il flusso di risposta includerà solo i campi necessari progress e status.

Richiesta

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

Flusso di Risposta

// Error event example
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": "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
}

L'oggetto Attività di Stampa 3D

Name
id
Type
string
Description
Identificatore univoco per l'attività. Anche se utilizziamo un UUID k-sortable per gli id delle attività come dettaglio di implementazione, non dovresti fare alcuna supposizione sul formato dell'id.
Name
type
Type
string
Description
Tipo di attività di Stampa 3D. Il valore è print-multi-color.
Name
model_urls
Type
object
Description
URL scaricabile per il file del modello 3D generato da Meshy. La proprietà per un formato sarà omessa se il formato non è generato invece di restituire una stringa vuota.
- Name
  3mf
  Type
  string
  Description
  URL scaricabile per il file 3MF multi-colore.
Name
progress
Type
integer
Description
Avanzamento dell'attività. Se l'attività non è ancora iniziata, questa proprietà sarà 0. Una volta che l'attività è riuscita, diventerà 100.
Name
status
Type
string
Description
Stato dell'attività. I valori possibili sono uno di PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
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
created_at
Type
timestamp
Description
Timestamp di quando l'attività è stata creata, in millisecondi.
Name
started_at
Type
timestamp
Description
Timestamp di quando l'attività è stata avviata, in millisecondi. Se l'attività non è ancora iniziata, questa proprietà sarà 0.
Name
finished_at
Type
timestamp
Description
Timestamp di quando l'attività è stata completata, in millisecondi. Se l'attività non è ancora completata, questa proprietà sarà 0.
Name
task_error
Type
object
Description
Dettagli degli errori per le attività fallite. Vedi Errori per il riferimento completo all'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).

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
}