API pro Analyzovat tisknutelnost

Analyzujte 3D model z hlediska tisknutelnosti pro FDM — vodotěsnost, objem, díry, non-manifold hrany a degenerované plochy.

POST/openapi/v1/print/analyze

Vytvoření úlohy Analyzovat tisknutelnost

Tento koncový bod vytvoří novou úlohu analýzy tisknutelnosti. Úloha vyhodnotí 3D model a vrátí metriky jeho tisknutelnosti.

Pokud vstupní úloha již má tisknutelnost uloženou v mezipaměti, vrácená úloha je okamžitě připravena a první GET na ni vrátí výsledek analýzy bez nutnosti průchodu workerem.

Parametry

Vyžadován je pouze jeden z parametrů input_task_id nebo model_url. Pokud jsou zadány oba, má přednost input_task_id.

  • Name
    model_url
    Type
    string
    Povinné
    Description

    URL 3D modelu k analýze. Podporované formáty: .glb, .gltf, .obj, .fbx, .stl. Maximální velikost souboru: 100 MB. Musí používat http, https, nebo data: URL (data URL obcházejí kontrolu přípony).

Návratová hodnota

Vlastnost result v odpovědi obsahuje id nově vytvořené úlohy analýzy tisknutelnosti.

Režimy selhání

  • Name
    400 - Bad Request
    Description

    Požadavek byl nepřijatelný. Časté příčiny:

    • Chybějící parametr: nebyl zadán ani input_task_id, ani model_url.
    • Neplatné UUID: input_task_id není platné UUID.
    • Neplatná URL modelu: model_url je nesprávně zformátovaná, používá nepodporované schéma nebo má nepodporovanou příponu souboru.
    • Soubor modelu je příliš velký: obsah model_url přesáhl 100 MB.
    • Úloha nebyla úspěšně dokončena: odkazovaná úloha stále čeká na zpracování, právě se zpracovává, nebo selhala.
  • Name
    401 - Unauthorized
    Description

    Autentizace selhala. Zkontrolujte prosím svůj API klíč.

  • Name
    403 - Forbidden
    Description

    Úloha existuje, ale vlastní ji jiný uživatel.

  • Name
    404 - Not Found
    Description

    Časté příčiny:

    • Úloha neexistuje nebo byla smazána.
    • Úloha používá model starší než Meshy 6, nebo její mode nevytváří 3D asset.
    • Podkladový soubor modelu již není dostupný v úložišti.
  • Name
    429 - Too Many Requests
    Description

    Překročili jste kvótu čekajících úloh nebo limit rychlosti.

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

Retrieve an Analyze Printability Task

Tento koncový bod získává úlohu pro analýzu tisknutelnosti podle jejího ID.

Parametry

  • Name
    id
    Type
    path
    Description

    ID úlohy pro analýzu tisknutelnosti, kterou chcete získat.

Vrací

Objekt úlohy Analyzovat tisknutelnost. Pole printability je null, dokud úloha nedosáhne stavu 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

Smazání úlohy Analyzovat tisknutelnost

Tento koncový bod trvale smaže úlohu analýzy tisknutelnosti a její uložený výsledek. Tato akce je nevratná.

Parametry cesty

  • Name
    id
    Type
    path
    Description

    ID úlohy analýzy tisknutelnosti, která má být smazána.

Stav úlohy

Úloha, která je stále ve stavu PENDING, je smazána a kredity spotřebované při jejím vytvoření jsou vráceny.

Úlohu, která je již ve stavu IN_PROGRESS, nelze smazat: požadavek je odmítnut s kódem 409 Conflict a úloha běží dál. Kredity za úlohu, kterou už worker začal zpracovávat, nejsou vratné, takže smazání během zpracování by vás stálo kredity i výsledek zároveň. Počkejte, až úloha dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a teprve poté ji smažte.

Úloha v koncovém stavu (SUCCEEDED, FAILED nebo CANCELED) je smazána bez vrácení kreditů.

Návratové hodnoty

Vrací 200 OK při úspěchu, nebo 409 Conflict, pokud je úloha ve stavu 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

Zobrazit seznam úloh Analyzovat tisknutelnost

Tento koncový bod umožňuje získat seznam úloh analýzy tisknutelnosti.

Parametry

Nepovinné atributy

  • Name
    page_num
    Type
    integer
    Description

    Číslo stránky pro stránkování. Začíná a výchozí hodnota je 1.

  • Name
    page_size
    Type
    integer
    Description

    Limit velikosti stránky. Výchozí hodnota je 10 položek. Maximální povolená hodnota je 100 položek.

  • Name
    sort_by
    Type
    string
    Description

    Pole, podle kterého se má seřazovat. Dostupné hodnoty:

    • +created_at: Seřadit podle času vytvoření vzestupně.
    • -created_at: Seřadit podle času vytvoření sestupně.

Návratové hodnoty

Vrací stránkovaný seznam objektů úlohy Analyzovat tisknutelnost.

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

Stream an Analyze Printability Task

Tento koncový bod streamuje aktualizace v reálném čase pro úlohu analýzy tisknutelnosti pomocí Server-Sent Events (SSE).

Parametry

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy analýzy tisknutelnosti, kterou chcete streamovat.

Návratová hodnota

Vrací proud objektů úlohy Analyzovat tisknutelnost jako Server-Sent Events.

Každý snímek obsahuje kompletní objekt úlohy pro danou fázi — stejný tvar, jaký vrací koncový bod Get — takže dokud je úloha ve stavu PENDING nebo IN_PROGRESS, výstupní pole zatím jednoduše nejsou naplněna (null, [] nebo {}) a finished_at je null. Blok printability je odeslán až poté, co úloha dosáhne stavu 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
}

Objekt úlohy Analyzovat tisknutelnost

  • Name
    id
    Type
    string
    Description

    Jedinečný identifikátor úlohy. Ačkoli jako implementační detail používáme pro id úloh k-sortable UUID, neměli byste dělat žádné předpoklady o formátu id.

  • Name
    type
    Type
    string
    Description

    Typ úlohy analýzy tisknutelnosti. Hodnota je print-analyze.

  • Name
    status
    Type
    string
    Description

    Stav úlohy. Možné hodnoty jsou jedna z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress úlohy. Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0. Jakmile úloha uspěje, hodnota se změní na 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Počet předcházejících úloh.

    Hodnota tohoto pole má smysl pouze v případě, že stav úlohy je PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Časové razítko okamžiku vytvoření úlohy, v milisekundách.

  • Name
    started_at
    Type
    timestamp
    Description

    Časové razítko okamžiku spuštění úlohy, v milisekundách. Pokud úloha ještě nebyla spuštěna, tato vlastnost bude 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko okamžiku dokončení úlohy, v milisekundách. Pokud úloha ještě nebyla dokončena, tato vlastnost bude 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Časové razítko okamžiku, kdy výsledek úlohy vyprší ze systému, v milisekundách. 0, pokud úloha ještě nebyla dokončena.

  • Name
    task_error
    Type
    object
    Description

    Informace o chybě, pokud úloha selhala. Tato vlastnost je null, pokud úloha neselhala. Více podrobností naleznete v části Chyby.

    • Name
      message
      Type
      string
      Description

      Chybová zpráva popisující, co se pokazilo.

  • Name
    printability
    Type
    object
    Description

    Výsledek vyhodnocení tisknutelnosti. null, dokud úloha nedosáhne stavu SUCCEEDED.

    • Name
      _version
      Type
      string
      Description

      Verze schématu výsledku tisknutelnosti. Aktuálně v1.

    • Name
      status
      Type
      string
      Description

      Celkový stav. Jedna z hodnot:

      • healthy: žádné chyby a žádná varování.
      • warning: alespoň jedno varování, žádné chyby.
      • error: alespoň jedna chyba.
      • unknown: model nebylo možné analyzovat.
    • Name
      issue_count
      Type
      integer
      Description

      Celkový počet problémů, rovný error_count + warning_count.

    • Name
      error_count
      Type
      integer
      Description

      Počet problémů na úrovni chyby. Chyby jsou hlášeny, pokud model není vodotěsný, má nekladný objem nebo obsahuje non-manifold hrany.

    • Name
      warning_count
      Type
      integer
      Description

      Počet problémů na úrovni varování. Varování jsou hlášena, pokud model obsahuje degenerované plochy nebo díry.

    • Name
      metrics
      Type
      object
      Description

      Surové metriky geometrie vrácené hodnotícím nástrojem.

      • Name
        is_watertight
        Type
        boolean
        Description

        true, pokud síť nemá žádné hraniční hrany (tj. je uzavřená).

      • Name
        volume
        Type
        number
        Description

        Objem modelu v krychlových metrech.

      • Name
        non_manifold_edges
        Type
        integer
        Description

        Počet non-manifold hran.

      • Name
        degenerate_faces
        Type
        integer
        Description

        Počet degenerovaných ploch (plochy s nulovou plochou nebo neplatné plochy).

      • Name
        holes
        Type
        integer
        Description

        Počet děr (hraničních smyček) v síti.

    • Name
      evaluated_at
      Type
      timestamp
      Description

      Časové razítko okamžiku výpočtu analýzy, v milisekundách od epochy.

  • Name
    consumed_credits
    Type
    integer
    Description

    Vždy 0. Tento koncový bod je zdarma.

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
}