API di stampa multicolore

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

POST/openapi/v1/print/multi-color

Crea un'attività di stampa 3D multicolore

Questo endpoint crea una nuova attività di stampa 3D multicolore. L'attività converte un modello 3D in un file 3MF multicolore adatto alla stampa 3D.

Parametri

È richiesto solo uno tra input_task_id o model_url. Se vengono forniti entrambi, input_task_id ha la priorità.

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

Name
model_url
Type
string
Obbligatorio
Description
URL accessibile pubblicamente 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: da 1 a 16.
Name
max_depth
Type
integer
predefinito 4
Description
Profondità del quadtree per la precisione del colore. Valori più alti producono confini di colore più dettagliati, ma aumentano la dimensione del file.
Intervallo valido: da 3 a 6.

Restituisce

La proprietà result della risposta contiene l'id dell'attività di stampa 3D appena creata.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante: Deve essere fornito model_url o input_task_id.
- Formato del modello non valido: model_url punta a un file con un'estensione non supportata (sono supportati solo .glb e .fbx).
- URL non raggiungibile: Impossibile scaricare model_url.
- Attività di input non valida: input_task_id deve fare riferimento a un'attività completata con successo.
- max_colors non valido: Il valore deve essere compreso tra 1 e 16.
- max_depth non valido: Il valore deve essere compreso tra 3 e 6.
Name
401 - Unauthorized
Description
Autenticazione non riuscita. Controlla la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questa attività.
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,
    "max_depth": 5
  }'

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 dell'attività di stampa 3D.

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
}

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

Eliminare un'attività di stampa 3D multicolore

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

Parametri di percorso

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

Restituisce

Restituisce 200 OK in caso di successo.

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

// Returns 200 Ok on success.

GET/openapi/v1/print/multi-color

Elenca le attività di stampa 3D multicolore

Questo endpoint 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 da 1 ed è il valore predefinito.
Name
page_size
Type
integer
Description
Limite della dimensione della pagina. Il valore predefinito è 10 elementi. Il massimo consentito è 50 elementi.
Name
sort_by
Type
string
Description
Campo in base al quale ordinare. Valori disponibili:
- +created_at: Ordina per ora di creazione in ordine crescente.
- -created_at: Ordina per ora di creazione in ordine decrescente.

Restituisce

Restituisce un elenco paginato degli oggetti attività di stampa 3D.

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

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

Trasmetti in streaming 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 dell'attività di stampa 3D multicolore da trasmettere in streaming.

Restituisce

Restituisce uno stream di oggetti attività di stampa 3D come Server-Sent Events.

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

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.
// 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à. Sebbene utilizziamo un UUID k-ordinabile per gli ID delle attività come dettaglio di implementazione, non dovresti fare alcuna supposizione sul formato dell'id.
Name
type
Type
string
Description
Tipo dell'attività di stampa 3D. Il valore è print-multi-color.
Name
model_urls
Type
object
Description
URL scaricabile del file del modello 3D generato da Meshy. La proprietà per un formato verrà omessa se il formato non viene generato, invece di restituire una stringa vuota.
- Name
  3mf
  Type
  string
  Description
  URL scaricabile del file 3MF multicolore.
Name
progress
Type
integer
Description
progress 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 tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED.
Name
preceding_tasks
Type
integer
Description
Il numero di 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 dell'errore per le attività non riuscite. Consulta 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 errore).

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
}