API Ripara stampabilità

Ripara un modello 3D per la stampabilità FDM — corregge spigoli non manifold, facce degenerate, buchi e altri problemi di topology in modo che la mesh sia pronta per la stampa.

POST/openapi/v1/print/repair

Crea un task di riparazione della stampabilità

Questo endpoint crea un nuovo task di riparazione della stampabilità. Il task esegue una riparazione della topology su un modello 3D e restituisce una versione stagna (watertight) e pronta per la stampa.

Il formato di output corrisponde al formato di input. Se invii un file .stl tramite model_url, il campo model_urls.stl della risposta conterrà la mesh riparata e gli altri campi di formato saranno vuoti. Il percorso input_task_id legge sempre il GLB del task di origine, quindi l'output sarà .glb.

Parametri

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

Le texture esistenti vengono rimosse durante la riparazione a causa dei cambiamenti nella geometria. Per riaggiungere le texture, utilizza la Retexture API sul modello riparato.

Name
input_task_id
Type
string
Obbligatorio
Description
L'ID di un task completato con successo di tua proprietà. Tipi di task supportati: Immagine in 3D, Multi-immagine in 3D, Testo in 3D, Remesh e Retexture. Il task deve avere uno stato SUCCEEDED e deve aver prodotto un asset GLB.

Name
model_url
Type
string
Obbligatorio
Description
URL di un modello 3D da riparare. Formati supportati: .glb, .gltf, .obj, .fbx, .stl. Dimensione massima del file: 100 MB. È necessario utilizzare http, https, oppure un URL data: (gli URL data bypassano i controlli sull'estensione).

Name
alpha_thumbnail
Type
boolean
predefinito false
Description
Se impostato su true, il task genera inoltre una versione con sfondo trasparente (RGBA) dell'anteprima e la restituisce come alpha_thumbnail_url nella risposta GET. Il campo thumbnail_url esistente rimane invariato.

Valori restituiti

La proprietà result della risposta contiene l'id del task di riparazione della stampabilità appena creato.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non è stata accettata. Cause comuni:
- Parametro mancante: non è stato fornito né input_task_id né model_url.
- UUID non valido: input_task_id non è un UUID valido.
- URL del modello non valido: model_url è malformato, utilizza uno schema non supportato oppure ha un'estensione di file non supportata.
- File del modello troppo grande: il corpo di model_url ha superato i 100 MB.
- Task non completato: il task referenziato è ancora in attesa, in corso o è fallito.
- GLB mancante: il task referenziato non ha alcun asset GLB da riparare.
Name
401 - Unauthorized
Description
L'autenticazione non è riuscita. Controlla la tua chiave API.
Name
402 - Payment Required
Description
Cause comuni:
- Piano gratuito: la creazione di task richiede un piano a pagamento. Effettua l'upgrade dalla pagina abbonamento.
- Crediti insufficienti: è stato raggiunto il limite di crediti dello spazio di lavoro.
Name
404 - Not Found
Description
Il task referenziato non esiste oppure appartiene a un altro utente.
Name
429 - Too Many Requests
Description
Hai superato la quota di task in sospeso o il limite di frequenza.

Request

POST

/openapi/v1/print/repair

# Repair an existing task
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578"
  }'

# Or repair a model URL directly
curl https://api.meshy.ai/openapi/v1/print/repair \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "model_url": "https://example.com/model.stl"
  }'

Response

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

GET/openapi/v1/print/repair/:id

Recupera un task di Ripara stampabilità

Questo endpoint recupera un task di ripara-stampabilità tramite il suo ID.

Parametri

Name
id
Type
path
Description
L'ID del task di ripara-stampabilità da recuperare.

Valori restituiti

Il Repair Printability Task Object. Il blocco model_urls è vuoto finché il task non raggiunge lo stato SUCCEEDED. Viene popolato solo il campo model_urls corrispondente al formato di input.

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

DELETE/openapi/v1/print/repair/:id

Elimina un'attività di Ripara stampabilità

Questo endpoint elimina definitivamente un'attività di riparazione della stampabilità e il suo output riparato. Questa azione è irreversibile.

Parametri del percorso

Name
id
Type
path
Description
L'ID dell'attività di riparazione della stampabilità da eliminare.

Stato dell'attività

Un'attività ancora in stato PENDING viene eliminata e i crediti consumati al momento della creazione vengono rimborsati.

Un'attività già IN_PROGRESS non può essere eliminata: la richiesta viene rifiutata con 409 Conflict e l'attività continua a essere eseguita. I crediti per un'attività che il worker ha già avviato non sono rimborsabili, quindi eliminarla a metà esecuzione ti farebbe perdere sia i crediti sia il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.

Un'attività in uno stato terminale (SUCCEEDED, FAILED o CANCELED) viene eliminata senza rimborso.

Restituisce

Restituisce 200 OK in caso di successo, oppure 409 Conflict quando l'attività è IN_PROGRESS.

Request

DELETE

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

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/print/repair/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 is left 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."
}

GET/openapi/v1/print/repair

Elenca attività di riparazione stampabilità

Questo endpoint consente di recuperare un elenco di attività di riparazione stampabilità.

Parametri

Attributi opzionali

Name
page_num
Type
integer
Description
Numero di pagina per la paginazione. Inizia e ha come valore predefinito 1.
Name
page_size
Type
integer
Description
Limite di dimensione della pagina. Il valore predefinito è 10 elementi. Il massimo consentito è 100 elementi.
Name
sort_by
Type
string
Description
Campo su cui ordinare. Valori disponibili:
- +created_at: Ordina per data di creazione in ordine crescente.
- -created_at: Ordina per data di creazione in ordine decrescente.

Restituisce

Restituisce un elenco paginato di Oggetti Attività di Riparazione Stampabilità.

Request

GET

/openapi/v1/print/repair

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-repair",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000030000,
    "expires_at": 1715725401000,
    "task_error": null,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "gltf": "",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]

GET/openapi/v1/print/repair/:id/stream

Esegui lo streaming di un'attività di riparazione della stampabilità

Questo endpoint trasmette in streaming aggiornamenti in tempo reale per un'attività di riparazione della stampabilità utilizzando Server-Sent Events (SSE).

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività di riparazione della stampabilità da trasmettere in streaming.

Restituisce

Restituisce uno stream di Oggetti Attività di Ripara stampabilità come Server-Sent Events.

Ogni frame trasporta l'oggetto attività completo per la fase corrente — la stessa struttura restituita dall'endpoint Get — quindi mentre l'attività è PENDING o IN_PROGRESS i campi di output semplicemente non sono ancora popolati (null, [] o {}) e finished_at è null. Il blocco model_urls viene inviato solo quando l'attività raggiunge lo stato SUCCEEDED.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/print/repair/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.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "a43b5c6d-7e8f-901a-234b-567c890d1e2f",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

L'oggetto Task Ripara stampabilità

Name
id
Type
string
Description
Identificatore univoco del task. Sebbene utilizziamo un UUID k-sortable per gli id dei task come dettaglio implementativo, non dovresti fare alcuna assunzione sul formato dell'id.
Name
type
Type
string
Description
Tipo del task di ripara stampabilità. Il valore è print-repair.
Name
status
Type
string
Description
Stato del task. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress del task. Se il task non è ancora iniziato, questa proprietà sarà 0. Una volta che il task ha avuto successo, diventerà 100.
Name
preceding_tasks
Type
integer
Description
Il conteggio dei task precedenti.
Il valore di questo campo è significativo solo se lo stato del task è PENDING.
Name
created_at
Type
timestamp
Description
Timestamp di quando il task è stato creato, in millisecondi.
Name
started_at
Type
timestamp
Description
Timestamp di quando il task è stato avviato, in millisecondi. Se il task non è ancora iniziato, questa proprietà sarà 0.
Name
finished_at
Type
timestamp
Description
Timestamp di quando il task è stato completato, in millisecondi. Se il task non è ancora terminato, questa proprietà sarà 0.
Name
expires_at
Type
timestamp
Description
Timestamp di quando il risultato del task scadrà dal sistema, in millisecondi. 0 se il task non è ancora terminato.
Name
task_error
Type
object
Description
Informazioni sull'errore se il task è fallito. Questa proprietà è null se il task non è fallito. Vedi Errori per maggiori dettagli.
- Name
  message
  Type
  string
  Description
  Messaggio di errore che descrive cosa è andato storto.
Name
model_urls
Type
object
Description
URL scaricabili del modello 3D riparato. Solo il campo corrispondente al formato di input viene popolato; gli altri campi di formato sono stringhe vuote.
- Name
  glb
  Type
  string
  Description
  URL scaricabile del GLB riparato. Popolato quando l'input era un GLB o quando è stato usato input_task_id.
- Name
  gltf
  Type
  string
  Description
  URL scaricabile del GLTF riparato. Popolato quando l'input era un caricamento GLTF.
- Name
  fbx
  Type
  string
  Description
  URL scaricabile del FBX riparato. Popolato quando l'input era un caricamento FBX.
- Name
  obj
  Type
  string
  Description
  URL scaricabile dell'OBJ riparato. Popolato quando l'input era un caricamento OBJ.
- Name
  stl
  Type
  string
  Description
  URL scaricabile dello STL riparato. Popolato quando l'input era un caricamento STL.
- Name
  usdz
  Type
  string
  Description
  Riservato per l'output USDZ. Sempre una stringa vuota per i task di ripara stampabilità.
- Name
  3mf
  Type
  string
  Description
  Riservato per l'output 3MF. Sempre una stringa vuota per i task di ripara stampabilità.
- Name
  mtl
  Type
  string
  Description
  Riservato per l'output MTL. Sempre una stringa vuota per i task di ripara stampabilità.
Name
thumbnail_url
Type
string
Description
URL di un'immagine di anteprima renderizzata dal modello riparato.
Name
alpha_thumbnail_url
Type
string
Description
URL scaricabile di una versione con sfondo trasparente (RGBA) di thumbnail_url. Presente solo quando il task è stato creato con alpha_thumbnail: true e l'anteprima trasparente è stata renderizzata correttamente; altrimenti questo campo viene omesso.
Name
texture_urls
Type
array
Description
Sempre un array vuoto. La riparazione preserva solo la geometria dell'input e non ri-elabora le texture.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questo task. 10 una volta che il task ha raggiunto lo stato SUCCEEDED. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di fallimento).

The Repair Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "gltf": "",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}