API Analizza stampabilità

Analizza un modello 3D per la stampabilità FDM — tenuta stagna, volume, fori, spigoli non manifold e facce degenerate.

POST/openapi/v1/print/analyze

Crea un'attività Analizza stampabilità

Questo endpoint crea una nuova attività di analisi della stampabilità. L'attività valuta un modello 3D e ne riporta le metriche di stampabilità.

Se l'attività di input ha già una stampabilità memorizzata nella cache, l'attività restituita è immediatamente pronta e il primo GET su di essa restituirà il risultato dell'analisi senza passare dal worker.

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 di tua proprietà. Tipi di attività supportati: Immagine in 3D, Multi-immagine in 3D, Testo in 3D, Remesh e Retexture. L'attività deve usare Meshy 6 (o qualsiasi modello Preview) e deve avere uno stato SUCCEEDED.

Name
model_url
Type
string
Obbligatorio
Description
URL di un modello 3D da analizzare. Formati supportati: .glb, .gltf, .obj, .fbx, .stl. Dimensione massima del file: 100 MB. Deve usare un URL http, https o data: (gli URL data ignorano i controlli sull'estensione).

Restituisce

La proprietà result della risposta contiene l'id dell'attività di analisi 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 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 non riuscita.
Name
401 - Unauthorized
Description
Autenticazione non riuscita. Controlla la tua chiave API.
Name
403 - Forbidden
Description
L'attività esiste ma appartiene a un utente diverso.
Name
404 - Not Found
Description
Cause comuni:
- L'attività non esiste o è stata eliminata.
- L'attività usa un modello precedente a Meshy 6, oppure il suo mode non produce un asset 3D.
- Il file del modello sottostante non è più disponibile nello storage.
Name
429 - Too Many Requests
Description
Hai superato la tua quota di attività in sospeso o il limite di frequenza.

Request

POST

/openapi/v1/print/analyze

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

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

Response

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

GET/openapi/v1/print/analyze/:id

Recupera un task Analizza stampabilità

Questo endpoint recupera un task analyze-printability tramite il suo ID.

Parametri

Name
id
Type
path
Description
L'ID del task analyze-printability da recuperare.

Restituisce

Il Task Object Analizza stampabilità. Il campo printability è null finché il task non raggiunge SUCCEEDED.

Request

GET

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

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

DELETE/openapi/v1/print/analyze/:id

Elimina un'attività Analizza stampabilità

Questo endpoint elimina definitivamente un'attività di Analizza stampabilità e il suo risultato memorizzato nella cache. Questa azione è irreversibile.

Parametri di percorso

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

Restituisce

Restituisce 200 OK in caso di successo.

Request

DELETE

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

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

Response

// Returns 200 Ok on success.

GET/openapi/v1/print/analyze

Elenca attività Analizza stampabilità

Questo endpoint consente di recuperare un elenco di attività di analisi della stampabilità.

Parametri

Attributi facoltativi

Name
page_num
Type
integer
Description
Numero di pagina per la paginazione. Inizia e il valore predefinito è 1.
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à Analizza stampabilità.

Request

GET

/openapi/v1/print/analyze

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-analyze",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "expires_at": 1715725401000,
    "task_error": null,
    "printability": {
      "_version": "v1",
      "status": "warning",
      "issue_count": 1,
      "error_count": 0,
      "warning_count": 1,
      "metrics": {
        "is_watertight": true,
        "volume": 1.316167354292668,
        "non_manifold_edges": 0,
        "degenerate_faces": 43242,
        "holes": 0
      },
      "evaluated_at": 1700000001000
    },
    "consumed_credits": 0
  }
]

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

Trasmetti in streaming un'attività Analizza stampabilità

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

Parametri

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

Restituisce

Restituisce uno stream di oggetti attività Analizza stampabilità come Server-Sent Events.

Per le attività PENDING o IN_PROGRESS, lo stream di risposta includerà solo i campi necessari progress e status. Il blocco printability viene inviato solo quando l'attività raggiunge SUCCEEDED.

Request

GET

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

curl -N https://api.meshy.ai/openapi/v1/print/analyze/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-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}

L'oggetto task Analizza stampabilità

Name
id
Type
string
Description
Identificatore univoco del task. Sebbene usiamo un UUID k-sortable per gli id dei task come dettaglio di implementazione, non dovresti fare alcuna assunzione sul formato dell'id.
Name
type
Type
string
Description
Tipo del task analyze-printability. Il valore è print-analyze.
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 è riuscito, diventerà 100.
Name
preceding_tasks
Type
integer
Description
Il numero di 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 completato, 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 completato.
Name
task_error
Type
object
Description
Informazioni sull'errore se il task non è riuscito. Questa proprietà è null se il task non è fallito. Consulta Errori per maggiori dettagli.
- Name
  message
  Type
  string
  Description
  Messaggio di errore che descrive cosa è andato storto.
Name
printability
Type
object
Description
Risultato della valutazione della stampabilità. null finché il task non raggiunge SUCCEEDED.
- Name
  _version
  Type
  string
  Description
  Versione dello schema del risultato della stampabilità. Attualmente v1.
- Name
  status
  Type
  string
  Description
  Stato complessivo. Uno tra:
  
  healthy: nessun errore e nessun avviso.
  
  warning: almeno un avviso, nessun errore.
  
  error: almeno un errore.
  
  unknown: il modello non ha potuto essere analizzato.
- Name
  issue_count
  Type
  integer
  Description
  Conteggio totale dei problemi, uguale a error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Numero di problemi a livello di errore. Gli errori vengono generati quando il modello non è watertight, ha volume non positivo o ha spigoli non manifold.
- Name
  warning_count
  Type
  integer
  Description
  Numero di problemi a livello di avviso. Gli avvisi vengono generati quando il modello contiene facce degenerate o fori.
- Name
  metrics
  Type
  object
  Description
  Metriche di geometria grezze restituite dal valutatore.
  Name
  is_watertight
  Type
  boolean
  Description
  true quando la mesh non ha spigoli di contorno (cioè è chiusa).
  Name
  volume
  Type
  number
  Description
  Volume del modello in metri cubi.
  Name
  non_manifold_edges
  Type
  integer
  Description
  Conteggio degli spigoli non manifold.
  Name
  degenerate_faces
  Type
  integer
  Description
  Conteggio delle facce degenerate (facce con area zero o non valide).
  Name
  holes
  Type
  integer
  Description
  Conteggio dei fori (loop di contorno) nella mesh.
- Name
  evaluated_at
  Type
  timestamp
  Description
  Timestamp di quando l'analisi è stata calcolata, in millisecondi dall'epoch.
Name
consumed_credits
Type
integer
Description
Sempre 0. Questo endpoint è gratuito.

The Analyze Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "expires_at": 1715725401000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "warning",
    "issue_count": 1,
    "error_count": 0,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "evaluated_at": 1700000001000
  },
  "consumed_credits": 0
}