API för Analysera utskrivbarhet

Analysera en 3D-modell med avseende på utskrivbarhet — vattentäthet, volym, hål, non-manifold-kanter och degenererade ytor. Kontrollera även valfritt väggtjocklek vid den storlek du planerar att skriva ut i.

POST/openapi/v1/print/analyze

Create an Analyze Printability Task

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

Om den angivna uppgiften redan har cachad utskrivbarhet är den returnerade uppgiften direkt klar, och den första GET-förfrågan på den returnerar analysresultatet utan att gå via arbetaren.

För att även kontrollera väggtjocklek vid den storlek du planerar att skriva ut i, skicka printer_type, en utskriftsstorlek, eller båda. Resultatet returneras i printability.thin_walls. Kontroll av väggtjocklek tar längre tid, så uppgiften är vanligtvis inte klar direkt, även om modellen analyserats tidigare.

Parametrar

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

Name
input_task_id
Type
string
Obligatorisk
Description
ID:t för en lyckad uppgift som du äger. Uppgiftstyper som stöds: Bild till 3D, Flera bilder till 3D, Text till 3D, Remesh, och Omtexturering. Uppgiften måste använda Meshy 6 eller senare (inklusive Meshy 7) och måste ha statusen SUCCEEDED. Uppgifter av typen Reparera utskrivbarhet accepteras också.

Name
model_url
Type
string
Obligatorisk
Description
URL till en 3D-modell att analysera. 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 kontroll av filändelse).

Skicka högst ett av de två fälten för utskriftsstorlek. Om du skickar printer_type utan en storlek är standardstorleken:

.glb och alla input_task_id: 150 mm hög.
.stl: filens egen längsta sida, tolkad som millimeter. För en STL i andra enheter, skicka intended_print_longest_side_mm.
.obj, .fbx, .gltf: 150 mm på den längsta sidan.

Name
printer_type
Type
string
Description
Skrivaren du planerar att använda. Den anger minsta väggtjocklek för kontrollen av väggtjocklek. Standardvärdet är fdm när du skickar en utskriftsstorlek utan den.
Tillgängliga värden:
- fdm: filament, 1,0 mm minsta vägg.
- sla: hartsbaserad, 0,8 mm minsta vägg.
- full_color: fullfärg, 2,0 mm minsta vägg.
Name
intended_print_height_mm
Type
number
Description
Höjden på utskriften, i millimeter. Intervall: [1, 1000]. Avrundas till närmaste millimeter. Endast GLB-indata.
Name
intended_print_longest_side_mm
Type
number
Description
Längden på utskriftens längsta sida, i millimeter. Intervall: [1, 1000]. Avrundas till närmaste millimeter. Fungerar med alla indataformat.

Returvärden

Svarets result-egenskap innehåller id för den nyskapade uppgiften för analys av utskrivbarhet.

Felscenarier

Name
400 - Bad Request
Description
Förfrågan var inte godtagbar. 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 icke-stött schema, eller har en filändelse som inte stöds.
- Modellfilen är för stor: model_url-innehållet översteg 100 MB.
- Uppgift inte lyckad: den refererade uppgiften väntar fortfarande, pågår, eller misslyckades.
- Ogiltig utskriftsstorlek: intended_print_height_mm eller intended_print_longest_side_mm ligger utanför [1, 1000], eller båda skickades.
- Okänd skrivartyp: printer_type är inte fdm, sla, eller full_color.
- Höjd på en modell som inte är GLB: intended_print_height_mm skickades med en model_url som inte är .glb. Använd intended_print_longest_side_mm istället.
- Kan inte anpassa storlek på denna modell efter höjd: vid den begärda höjden (eller standardvärdet 150 mm) skulle modellens längsta sida hamna utanför [1, 1000] mm, modellen är platt, eller dess storlek kan inte fastställas. Använd intended_print_longest_side_mm istället. För en .glb model_url och vissa input_task_id-uppgifter upptäcks detta först efter att uppgiften startat, och uppgiften slutar då med FAILED istället.
- STL-storlek kan inte användas: printer_type skickades utan en storlek, och STL-filens egen längsta sida kan inte läsas eller ligger utanför [1, 1000] mm. Skicka intended_print_longest_side_mm.
Name
401 - Unauthorized
Description
Autentisering 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 tagits bort.
- Uppgiften använder en modell äldre än Meshy 6, eller dess mode genererar inte ett 3D-asset.
- Den underliggande modellfilen finns 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"
  }'

# Also check wall thickness for a 100 mm tall SLA print
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",
    "printer_type": "sla",
    "intended_print_height_mm": 100
  }'

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 med 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. När väggtjocklek har kontrollerats innehåller printability även intended_print och thin_walls.

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
}

Response (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "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
}

Objektet för Analysera utskrivbarhet-uppgiften

Name
id
Type
string
Description
Unik identifierare för uppgiften. Även om vi använder en k-sorterbar UUID för uppgifts-id:n som implementationsdetalj bör du inte göra några antaganden om id:ts format.
Name
type
Type
string
Description
Typ av analyze-printability-uppgift. Värdet är print-analyze.
Name
status
Type
string
Description
Status för uppgiften. Möjliga värden är ett av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Progress för uppgiften. Om uppgiften ännu inte har startat kommer denna egenskap att vara 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 meningsfullt 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 ännu inte har startat kommer denna egenskap att vara 0.
Name
finished_at
Type
timestamp
Description
Tidsstämpel för när uppgiften avslutades, i millisekunder. Om uppgiften ännu inte har avslutats kommer denna egenskap att vara 0.
Name
expires_at
Type
timestamp
Description
Tidsstämpel för när uppgiftens resultat upphör att gälla i systemet, i millisekunder. 0 om uppgiften ännu inte har avslutats.
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 utskrivbarhetsbedömning. 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.
  
  När väggtjocklek kontrollerades är detta det sämre av ovanstående kontroller och thin_walls.status. Från sämst till bäst: error, warning, unknown, healthy.
- Name
  issue_count
  Type
  integer
  Description
  Totalt antal problem, lika med error_count + warning_count.
- Name
  error_count
  Type
  integer
  Description
  Antal problem på fel-nivå. Fel uppstår när modellen inte är vattentät, har icke-positiv volym, eller har non-manifold-kanter. När väggtjocklek kontrollerades räknas väggar som är för tunna (thin_walls.status är error) som ytterligare ett fel.
- Name
  warning_count
  Type
  integer
  Description
  Antal problem på varnings-nivå. Varningar utfärdas när modellen innehåller degenererade ytor eller hål.
- Name
  metrics
  Type
  object
  Description
  Rå geometri-mätdata 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 nollarea eller ogiltiga ytor).
  Name
  holes
  Type
  integer
  Description
  Antal hål (gränsslingor) i nätet.
- Name
  intended_print
  Type
  object
  Description
  Skrivaren och storleken som väggtjockleks-kontrollen använde. Finns endast med när väggtjocklek kontrollerades.
  Name
  printer_type
  Type
  string
  Description
  fdm, sla, eller full_color.
  Name
  height_mm
  Type
  number
  Description
  Utskriftens höjd i millimeter, om utskriften dimensionerades efter höjd. Annars null.
  Name
  longest_side_mm
  Type
  number
  Description
  Utskriftens längsta sida i millimeter. Vid dimensionering efter höjd beräknas detta utifrån modellens proportioner.
  Name
  wall_thickness_mm
  Type
  number
  Description
  Minsta väggtjocklek för printer_type, i millimeter. Väggar tunnare än detta rapporteras som för tunna.
  Name
  dimensions_mm
  Type
  array
  Description
  Utskriftens [width, depth, height] i millimeter. Höjden kan skilja sig från height_mm med en bråkdel av en millimeter. null för annan indata än GLB, eller om modellens storlek inte kan fastställas.
- Name
  thin_walls
  Type
  object
  Description
  Resultatet av väggtjockleks-kontrollen. Finns endast med när väggtjocklek kontrollerades.
  Name
  thin_area_ratio
  Type
  number
  Description
  Andel av ytan, från 0 till 1, som är tunnare än intended_print.wall_thickness_mm. null om modellen inte kunde mätas.
  Name
  has_thin_walls
  Type
  boolean
  Description
  true om någon del av ytan är för tunn. Skarpa hörn ensamma kan utlösa detta, så använd status för att avgöra om väggarna behöver förtjockas. null om modellen inte kunde mätas.
  Name
  status
  Type
  string
  Description
  Utslaget för väggtjockleken. Ett av:
  
  healthy: 5 % eller mindre av ytan är för tunn.
  
  error: mer än 5 % av ytan är för tunn. För att förtjocka väggarna, skicka denna uppgifts id till Reparera utskrivbarhet som input_task_id (för en .stl, .fbx, eller .gltf model_url, skicka istället filen som model_url).
  
  unknown: modellen kunde inte mätas. Om själva väggtjockleks-kontrollen misslyckas avslutas uppgiften med FAILED.
- 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
}

The Analyze Printability Task Object (wall thickness checked)

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-analyze",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000012000,
  "expires_at": 1715725412000,
  "task_error": null,
  "printability": {
    "_version": "v1",
    "status": "error",
    "issue_count": 2,
    "error_count": 1,
    "warning_count": 1,
    "metrics": {
      "is_watertight": true,
      "volume": 1.316167354292668,
      "non_manifold_edges": 0,
      "degenerate_faces": 43242,
      "holes": 0
    },
    "intended_print": {
      "printer_type": "sla",
      "height_mm": 100,
      "longest_side_mm": 118,
      "wall_thickness_mm": 0.8,
      "dimensions_mm": [118, 72.41, 99.87]
    },
    "thin_walls": {
      "thin_area_ratio": 0.083,
      "has_thin_walls": true,
      "status": "error"
    },
    "evaluated_at": 1700000012000
  },
  "consumed_credits": 0
}