API Ripara stampabilità

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

POST/openapi/v1/print/repair

Crea un'attività di Ripara stampabilità

Questo endpoint crea una nuova attività di riparazione della stampabilità. L'attività esegue la riparazione della topology su un modello 3D e restituisce una versione a tenuta stagna, pronta per la stampa.

Il formato di output corrisponde al formato di input. Se invii un .stl tramite model_url, il campo model_urls.stl della risposta conterrà il mesh riparato e gli altri campi di formato saranno vuoti. Il percorso input_task_id legge sempre il GLB dell'attività di origine, quindi l'output è .glb.

Parametri

È richiesto 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 delle modifiche alla geometria. Per aggiungere nuovamente le texture, usa la Retexture API sul modello riparato.

  • Name
    model_url
    Type
    string
    Obbligatorio
    Description

    URL di un modello 3D da riparare. Formati supportati: .glb, .stl, .obj. Dimensione massima del file: 100 MB. Deve usare un URL http, https o data: (gli URL data ignorano i controlli sull'estensione).

  • Name
    alpha_thumbnail
    Type
    boolean
    predefinito false
    Description

    Quando impostato su true, l'attività esegue inoltre il rendering di una versione dell'anteprima con sfondo trasparente (RGBA) e la restituisce come alpha_thumbnail_url nella risposta GET. Il campo thumbnail_url esistente rimane invariato.

Restituisce

La proprietà result della risposta contiene l'id dell'attività di riparazione della stampabilità appena creata.

Modalità di errore

  • Name
    400 - Bad Request
    Description

    La richiesta non era accettabile. 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, usa uno schema non supportato o ha un'estensione di file non supportata.
    • File del modello troppo grande: il corpo di model_url ha superato 100 MB.
    • Attività non riuscita: l'attività referenziata è ancora in sospeso, in progress o failed.
    • GLB mancante: l'attività referenziata non ha alcun asset GLB da riparare.
  • Name
    401 - Unauthorized
    Description

    Autenticazione non riuscita. Controlla la tua chiave API.

  • Name
    402 - Payment Required
    Description

    Cause comuni:

    • Piano gratuito: la creazione di attività richiede un piano a pagamento. Esegui l'upgrade nella pagina dell'abbonamento.
    • Crediti insufficienti: è stato raggiunto il limite di crediti dello spazio di lavoro.
  • Name
    404 - Not Found
    Description

    L'attività referenziata non esiste o appartiene a un altro utente.

  • Name
    429 - Too Many Requests
    Description

    Hai superato la quota di attività 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'attività Ripara stampabilità

Questo endpoint recupera un'attività repair-printability tramite il suo ID.

Parametri

  • Name
    id
    Type
    path
    Description

    L'ID dell'attività repair-printability da recuperare.

Restituisce

L'Oggetto attività Ripara stampabilità. Il blocco model_urls è vuoto finché l'attività non raggiunge 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": "",
    "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 Ripara stampabilità e il relativo output riparato. Questa azione è irreversibile.

Parametri del percorso

  • Name
    id
    Type
    path
    Description

    L'ID dell'attività di Ripara stampabilità da eliminare.

Restituisce

Restituisce 200 OK in caso di successo.

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

// Returns 200 Ok on success.
GET/openapi/v1/print/repair

Elenca attività Ripara stampabilità

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

Parametri

Attributi facoltativi

  • 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 di Oggetti attività Ripara 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=***",
      "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 stream di un'attività Ripara stampabilità

Questo endpoint trasmette 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à di cui eseguire lo stream.

Restituisce

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

Per le attività PENDING o IN_PROGRESS, lo stream di risposta includerà solo i campi progress e status necessari. Il blocco model_urls viene inviato solo quando l'attività raggiunge 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.
// 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-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=***",
    "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 attività Ripara stampabilità

  • Name
    id
    Type
    string
    Description

    Identificatore univoco dell'attività. Anche se usiamo un UUID k-ordinabile per gli id delle attività come dettaglio implementativo, non dovresti fare alcuna supposizione sul formato dell'id.

  • Name
    type
    Type
    string
    Description

    Tipo dell'attività Ripara stampabilità. Il valore è print-repair.

  • Name
    status
    Type
    string
    Description

    Stato dell'attività. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress dell'attività. Se l'attività non è ancora iniziata, questa proprietà sarà 0. Una volta completata con successo, diventerà 100.

  • 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
    expires_at
    Type
    timestamp
    Description

    Timestamp di quando il risultato dell'attività scadrà dal sistema, in millisecondi. 0 se l'attività non è ancora stata completata.

  • Name
    task_error
    Type
    object
    Description

    Informazioni sull'errore se l'attività non è riuscita. Questa proprietà è null se l'attività non è fallita. Consulta 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 per il modello 3D riparato. Viene popolato solo il campo corrispondente al formato di input; gli altri campi di formato sono stringhe vuote.

    • Name
      glb
      Type
      string
      Description

      URL scaricabile per il GLB riparato. Popolato quando l'input era un GLB o quando è stato usato input_task_id.

    • Name
      fbx
      Type
      string
      Description

      Riservato per l'output FBX. Sempre una stringa vuota per le attività Ripara stampabilità.

    • Name
      obj
      Type
      string
      Description

      URL scaricabile per l'OBJ riparato. Popolato quando l'input era un caricamento OBJ.

    • Name
      stl
      Type
      string
      Description

      URL scaricabile per l'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 le attività Ripara stampabilità.

    • Name
      3mf
      Type
      string
      Description

      Riservato per l'output 3MF. Sempre una stringa vuota per le attività Ripara stampabilità.

    • Name
      mtl
      Type
      string
      Description

      Riservato per l'output MTL. Sempre una stringa vuota per le attività 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 per una versione con sfondo trasparente (RGBA) di thumbnail_url. Presente solo quando l'attività è stata creata 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 conserva solo la geometria di input e non rigenera le texture.

  • Name
    consumed_credits
    Type
    integer
    Description

    Il numero di crediti consumati da questa attività. 10 una volta che l'attività ha raggiunto SUCCEEDED. Restituisce 0 per le attività FAILED (i crediti vengono rimborsati in caso di errore).

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=***",
    "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
}