Analysera utskrivbarhet API

Analysera en 3D-modell för FDM-utskrivbarhet — vattentäthet, volym, hål, non-manifold-kanter och degenererade ytor.

POST/openapi/v1/print/analyze

Skapa en analysera-utskrivbarhet-uppgift

Denna endpoint skapar en ny analysera-utskrivbarhet-uppgift. Uppgiften utvärderar en 3D-modell och rapporterar dess utskrivbarhetsmått.

Om inmatningsuppgiften redan har cachad utskrivbarhet är den returnerade uppgiften omedelbart klar, och den första GET på den kommer att returnera analysresultatet utan att gå via workern.

Parametrar

Endast en av input_task_id eller model_url krävs. Om båda anges har input_task_id prioritet.

  • Name
    model_url
    Type
    string
    Obligatorisk
    Description

    URL till en 3D-modell som ska analyseras. Format som stöds: .glb, .gltf, .obj, .fbx, .stl. Maximal filstorlek: 100 MB. Måste använda http, https eller en data:-URL (data-URL:er kringgår filändelsekontroller).

Returer

Egenskapen result i svaret innehåller id för den nyskapade analysera-utskrivbarhet-uppgiften.

Felscenarier

  • Name
    400 - Bad Request
    Description

    Begäran var oacceptabel. Vanliga orsaker:

    • Saknad parameter: varken input_task_id eller model_url angavs.
    • Ogiltig UUID: input_task_id är inte en giltig UUID.
    • Ogiltig modell-URL: model_url är felformaterad, använder ett schema som inte stöds, eller har en filändelse som inte stöds.
    • Modellfilen är för stor: innehållet i model_url överskred 100 MB.
    • Uppgiften har inte lyckats: den refererade uppgiften väntar fortfarande, pågår, eller misslyckades.
  • Name
    401 - Unauthorized
    Description

    Autentiseringen misslyckades. Kontrollera din API-nyckel.

  • Name
    403 - Forbidden
    Description

    Uppgiften finns men ägs av en annan användare.

  • Name
    404 - Not Found
    Description

    Vanliga orsaker:

    • Uppgiften finns inte eller har raderats.
    • Uppgiften använder en modell äldre än Meshy 6, eller dess mode genererar inte en 3D-tillgång.
    • Den underliggande modellfilen är inte längre tillgänglig i lagringen.
  • Name
    429 - Too Many Requests
    Description

    Du har överskridit din kvot för väntande uppgifter eller din hastighetsgräns.

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

Hämta en Analysera utskrivbarhet-uppgift

Denna endpoint hämtar en analysera-utskrivbarhet-uppgift baserat på dess ID.

Parametrar

  • Name
    id
    Type
    path
    Description

    ID:t för den analysera-utskrivbarhet-uppgift som ska hämtas.

Returnerar

Analysera utskrivbarhet-uppgiftsobjektet. Fältet printability är null tills uppgiften når 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

Ta bort en Analysera utskrivbarhet-uppgift

Denna endpoint tar permanent bort en analysera-utskrivbarhet-uppgift och dess cachade resultat. Denna åtgärd är oåterkallelig.

Sökvägsparametrar

  • Name
    id
    Type
    path
    Description

    ID:t för den analysera-utskrivbarhet-uppgift som ska tas bort.

Uppgiftsstatus

En uppgift som fortfarande är PENDING tas bort och de credits som förbrukades vid skapandet återbetalas.

En uppgift som redan är IN_PROGRESS kan inte tas bort: begäran avvisas med 409 Conflict och uppgiften fortsätter att köras. Credits för en uppgift som arbetaren redan har påbörjat kan inte återbetalas, så att ta bort den mitt i körningen skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, och ta sedan bort den.

En uppgift i ett slutgiltigt tillstånd (SUCCEEDED, FAILED eller CANCELED) tas bort utan återbetalning.

Returer

Returnerar 200 OK vid framgång, eller 409 Conflict när uppgiften är 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

Lista över uppgifter för att analysera utskrivbarhet

Denna endpoint låter dig hämta en lista över uppgifter för Analysera utskrivbarhet.

Parametrar

Valfria attribut

  • Name
    page_num
    Type
    integer
    Description

    Sidnummer för paginering. Börjar och har standardvärdet 1.

  • Name
    page_size
    Type
    integer
    Description

    Gräns för sidstorlek. Standardvärdet är 10 objekt. Maximalt tillåtet är 100 objekt.

  • Name
    sort_by
    Type
    string
    Description

    Fält att sortera efter. Tillgängliga värden:

    • +created_at: Sortera efter skapandetid i stigande ordning.
    • -created_at: Sortera efter skapandetid i fallande ordning.

Returnerar

Returnerar en paginerad lista med objekt för uppgifter att analysera utskrivbarhet.

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

Streama en Analysera utskrivbarhet-uppgift

Denna endpoint strömmar uppdateringar i realtid för en analyze-printability-uppgift med hjälp av Server-Sent Events (SSE).

Parametrar

  • Name
    id
    Type
    path
    Description

    Unik identifierare för analyze-printability-uppgiften som ska strömmas.

Returnerar

Returnerar en ström av Analyze Printability Task-objekt som Server-Sent Events.

Varje frame innehåller det fullständiga uppgiftsobjektet för steget — samma form som Get-endpointen returnerar — så medan uppgiften är PENDING eller IN_PROGRESS är utdatafälten helt enkelt ännu inte ifyllda (null, [] eller {}) och finished_at är null. Blocket printability skickas först när uppgiften når 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
}

The Analyze Printability Task Object

  • Name
    id
    Type
    string
    Description

    Unik identifierare för uppgiften. Även om vi använder en k-sorterbar UUID för uppgifts-id som en implementationsdetalj bör du inte göra några antaganden om formatet på id:t.

  • Name
    type
    Type
    string
    Description

    Typ av analysera-utskrivbarhet-uppgiften. Värdet är print-analyze.

  • Name
    status
    Type
    string
    Description

    Uppgiftens status. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress för uppgiften. Om uppgiften inte har startat än är denna egenskap 0. När uppgiften har lyckats blir den 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Antalet föregående uppgifter.

    Värdet i detta fält är endast relevant om uppgiftens status är PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften skapades, i millisekunder.

  • Name
    started_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften startades, i millisekunder. Om uppgiften inte har startat än är denna egenskap 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften slutfördes, i millisekunder. Om uppgiften inte är slutförd än är denna egenskap 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiftens resultat kommer att upphöra att gälla i systemet, i millisekunder. 0 om uppgiften ännu inte är slutförd.

  • Name
    task_error
    Type
    object
    Description

    Felinformation om uppgiften har misslyckats. Denna egenskap är null om uppgiften inte har misslyckats. Se Fel för mer information.

    • Name
      message
      Type
      string
      Description

      Felmeddelande som beskriver vad som gick fel.

  • Name
    printability
    Type
    object
    Description

    Resultat av utskrivbarhetsutvärderingen. null tills uppgiften når SUCCEEDED.

    • Name
      _version
      Type
      string
      Description

      Schemaversion för utskrivbarhetsresultatet. För närvarande v1.

    • Name
      status
      Type
      string
      Description

      Övergripande status. En av:

      • healthy: inga fel och inga varningar.
      • warning: minst en varning, inga fel.
      • error: minst ett fel.
      • unknown: modellen kunde inte analyseras.
    • Name
      issue_count
      Type
      integer
      Description

      Totalt antal problem, lika med error_count + warning_count.

    • Name
      error_count
      Type
      integer
      Description

      Antal problem på felnivå. Fel utlöses när modellen inte är vattentät, har icke-positiv volym, eller har non-manifold-kanter.

    • Name
      warning_count
      Type
      integer
      Description

      Antal problem på varningsnivå. Varningar utlöses när modellen innehåller degenererade ytor eller hål.

    • Name
      metrics
      Type
      object
      Description

      Rådata för geometri-mått som returneras av utvärderaren.

      • Name
        is_watertight
        Type
        boolean
        Description

        true när nätet inte har några gränskanter (dvs. är slutet).

      • Name
        volume
        Type
        number
        Description

        Modellens volym i kubikmeter.

      • Name
        non_manifold_edges
        Type
        integer
        Description

        Antal non-manifold-kanter.

      • Name
        degenerate_faces
        Type
        integer
        Description

        Antal degenererade ytor (ytor med noll area eller ogiltiga ytor).

      • Name
        holes
        Type
        integer
        Description

        Antal hål (gränsslingor) i nätet.

    • Name
      evaluated_at
      Type
      timestamp
      Description

      Tidsstämpel för när analysen beräknades, i millisekunder sedan epoch.

  • Name
    consumed_credits
    Type
    integer
    Description

    Alltid 0. Denna endpoint är gratis.

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
}