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

Creazione di un task di Analisi stampabilità

Questo endpoint crea un nuovo task di analisi stampabilità. Il task valuta un modello 3D e riporta le sue metriche di stampabilità.

Se il task di input ha già una stampabilità in cache, il task restituito è immediatamente pronto e la prima GET su di esso restituirà il risultato dell'analisi senza passare per il 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 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 utilizzare Meshy 6 o versioni successive (incluso Meshy 7) 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 utilizzare http, https oppure un URL data: (gli URL data bypassano i controlli sull'estensione).

Restituisce

La proprietà result della risposta contiene l'id del task di analisi 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 o 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.
  • Name
    401 - Unauthorized
    Description

    Autenticazione non riuscita. Controlla la tua chiave API.

  • Name
    403 - Forbidden
    Description

    Il task esiste ma è di proprietà di un altro utente.

  • Name
    404 - Not Found
    Description

    Cause comuni:

    • Il task non esiste o è stato eliminato.
    • Il task utilizza un modello più vecchio di 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 task in attesa 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'attività di Analizza stampabilità

Questo endpoint recupera un'attività di analisi della stampabilità tramite il suo ID.

Parametri

  • Name
    id
    Type
    path
    Description

    L'ID dell'attività di analisi della stampabilità da recuperare.

Restituisce

L'oggetto Attività di Analizza stampabilità. Il campo printability è null finché l'attività non raggiunge lo stato 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à di Analizza stampabilità

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

Parametri del percorso

  • Name
    id
    Type
    path
    Description

    L'ID dell'attività di analisi 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 stato 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à iniziato a elaborare non sono rimborsabili, quindi eliminarla a metà esecuzione ti farebbe perdere sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.

Un'attività in uno stato finale (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/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

// 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/analyze

List Analyze Printability Tasks

Questo endpoint consente di recuperare un elenco di task di Analizza 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 Task di 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

Analizza stampabilità in streaming di un task

Questo endpoint trasmette in streaming gli aggiornamenti in tempo reale di un task di analisi stampabilità utilizzando Server-Sent Events (SSE).

Parametri

  • Name
    id
    Type
    path
    Description

    Identificatore univoco del task di analisi stampabilità da trasmettere in streaming.

Restituisce

Restituisce uno stream di oggetti Task di analisi stampabilità come Server-Sent Events.

Ogni frame contiene l'oggetto task completo relativo allo stadio corrente — la stessa struttura restituita dall'endpoint Get — quindi mentre il task è PENDING o IN_PROGRESS i campi di output semplicemente non sono ancora popolati (null, [] o {}) e finished_at è null. Il blocco printability viene inviato solo quando il task raggiunge lo stato 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.
// 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-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 per gli id dei task venga utilizzato come dettaglio implementativo un UUID k-sortable, non si dovrebbero fare assunzioni sul formato dell'id.

  • Name
    type
    Type
    string
    Description

    Tipo del task di analisi stampabilità. 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 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 stato avviato, questa proprietà sarà 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp di quando il task è stato completato, in millisecondi. Se il task non è ancora stato 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 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
    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 di stampabilità. Attualmente v1.

    • Name
      status
      Type
      string
      Description

      Stato generale. 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, pari a error_count + warning_count.

    • Name
      error_count
      Type
      integer
      Description

      Numero di problemi di livello errore. Gli errori vengono generati quando il modello non è a tenuta stagna (watertight), ha volume non positivo, oppure presenta spigoli non manifold.

    • Name
      warning_count
      Type
      integer
      Description

      Numero di problemi di livello avviso. Gli avvisi vengono generati quando il modello contiene facce degenerate o buchi.

    • Name
      metrics
      Type
      object
      Description

      Metriche geometriche grezze restituite dal valutatore.

      • Name
        is_watertight
        Type
        boolean
        Description

        true quando la mesh non ha spigoli di confine (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 nulla o non valide).

      • Name
        holes
        Type
        integer
        Description

        Conteggio dei buchi (anelli di confine) 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
}