API Opravit tisknutelnost

Opravte 3D model pro tisknutelnost FDM — opravte non-manifold hrany, degenerované plochy, díry a další problémy s topology, aby byla síť připravena k tisku.

POST/openapi/v1/print/repair

Vytvořit úlohu Opravit tisknutelnost

Tento koncový bod vytvoří novou úlohu opravy tisknutelnosti. Úloha provede opravu topology na 3D modelu a vrátí vodotěsnou verzi připravenou k tisku.

Výstupní formát odpovídá vstupnímu formátu. Pokud odešlete .stl prostřednictvím model_url, model_urls.stl v odpovědi bude obsahovat opravenou síť a ostatní pole formátů budou prázdná. Varianta input_task_id vždy načítá GLB zdrojové úlohy, takže výstupem je .glb.

Parametry

Vyžaduje se pouze jedno z input_task_id nebo model_url. Pokud jsou zadány obě, input_task_id má prioritu.

Existující textury jsou během opravy odstraněny kvůli změnám geometrie. Chcete-li textury znovu přidat, použijte Retexturování API na opravený model.

  • Name
    model_url
    Type
    string
    Povinné
    Description

    URL 3D modelu k opravě. Podporované formáty: .glb, .stl, .obj. Maximální velikost souboru: 100 MB. Musí používat URL http, https nebo data: (data URL obcházejí kontroly přípon).

  • Name
    alpha_thumbnail
    Type
    boolean
    výchozí false
    Description

    Pokud je nastaveno na true, úloha navíc vykreslí verzi náhledu s průhledným pozadím (RGBA) a vrátí ji jako alpha_thumbnail_url v odpovědi GET. Existující pole thumbnail_url zůstane beze změny.

Návratové hodnoty

Vlastnost result odpovědi obsahuje id nově vytvořené úlohy opravy tisknutelnosti.

Režimy selhání

  • Name
    400 - Bad Request
    Description

    Požadavek nebyl přijatelný. Běžné příčiny:

    • Chybějící parametr: nebylo zadáno ani input_task_id, ani model_url.
    • Neplatné UUID: input_task_id není platné UUID.
    • Neplatná URL modelu: model_url má nesprávný tvar, používá nepodporované schéma nebo má nepodporovanou příponu souboru.
    • Soubor modelu je příliš velký: tělo model_url překročilo 100 MB.
    • Úloha nebyla úspěšně dokončena: odkazovaná úloha stále čeká, probíhá nebo selhala.
    • Chybějící GLB: odkazovaná úloha nemá žádný GLB asset k opravě.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    Běžné příčiny:

    • Bezplatný plán: vytvoření úlohy vyžaduje placený plán. Upgradujte na stránce předplatné.
    • Nedostatek kreditů: byl dosažen limit kreditů pracovního prostoru.
  • Name
    404 - Not Found
    Description

    Odkazovaná úloha neexistuje nebo ji vlastní jiný uživatel.

  • Name
    429 - Too Many Requests
    Description

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

Request

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

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

Response

{
  "result": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
}
GET/openapi/v1/print/repair/:id

Načtení úlohy Opravit tisknutelnost

Tento koncový bod načte úlohu opravy tisknutelnosti podle jejího ID.

Parametry

  • Name
    id
    Type
    path
    Description

    ID úlohy opravy tisknutelnosti, která se má načíst.

Vrací

Objekt úlohy Opravit tisknutelnost. Blok model_urls je prázdný, dokud úloha nedosáhne stavu SUCCEEDED. Vyplněno je pouze pole model_urls, které odpovídá vstupnímu formátu.

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "",
    "fbx": "",
    "obj": "",
    "stl": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.stl?Expires=***",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}
DELETE/openapi/v1/print/repair/:id

Odstranit úlohu Opravit tisknutelnost

Tento koncový bod trvale odstraní úlohu opravy tisknutelnosti a její opravený výstup. Tato akce je nevratná.

Parametry cesty

  • Name
    id
    Type
    path
    Description

    ID úlohy opravy tisknutelnosti, která se má odstranit.

Návratová hodnota

Při úspěchu vrátí 200 OK.

Request

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

Response

// Returns 200 Ok on success.
GET/openapi/v1/print/repair

Vypsat úlohy Opravit tisknutelnost

Tento koncový bod umožňuje načíst seznam úloh pro Opravit tisknutelnost.

Parametry

Volitelné atributy

  • Name
    page_num
    Type
    integer
    Description

    Číslo stránky pro stránkování. Začíná na 1 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 50 položek.

  • Name
    sort_by
    Type
    string
    Description

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

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

Vrací

Vrací stránkovaný seznam objektů úloh Opravit tisknutelnost.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "print-repair",
    "status": "SUCCEEDED",
    "progress": 100,
    "preceding_tasks": 0,
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000030000,
    "expires_at": 1715725401000,
    "task_error": null,
    "model_urls": {
      "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
      "fbx": "",
      "obj": "",
      "stl": "",
      "usdz": "",
      "3mf": "",
      "mtl": ""
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
    "texture_urls": [],
    "consumed_credits": 10
  }
]
GET/openapi/v1/print/repair/:id/stream

Streamovat úlohu Opravit tisknutelnost

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

Parametry

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy opravy tisknutelnosti, která se má streamovat.

Vrací

Vrací stream objektů úlohy Opravit tisknutelnost jako Server-Sent Events.

U úloh PENDING nebo IN_PROGRESS bude stream odpovědi obsahovat pouze nezbytná pole progress a status. Blok model_urls se odešle až poté, co úloha dosáhne stavu SUCCEEDED.

Request

GET
/openapi/v1/print/repair/a43b5c6d-7e8f-901a-234b-567c890d1e2f/stream
curl -N https://api.meshy.ai/openapi/v1/print/repair/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-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/model.glb?Expires=***",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/a43b5c6d-7e8f-901a-234b-567c890d1e2f/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}

Objekt úlohy Opravit tisknutelnost

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Typ úlohy opravy tisknutelnosti. Hodnota je print-repair.

  • 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 úspěšně skončí, změní se na 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

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

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

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

    Časové razítko 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 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, kdy výsledek úlohy v systému vyprší, 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. Další podrobnosti najdete v části Chyby.

    • Name
      message
      Type
      string
      Description

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

  • Name
    model_urls
    Type
    object
    Description

    Stáhnutelné adresy URL opraveného 3D modelu. Vyplněno je pouze pole odpovídající vstupnímu formátu; ostatní pole formátů jsou prázdné řetězce.

    • Name
      glb
      Type
      string
      Description

      Stáhnutelná adresa URL opraveného GLB. Vyplněno, když vstupem byl GLB nebo když byl použit input_task_id.

    • Name
      fbx
      Type
      string
      Description

      Rezervováno pro výstup FBX. Pro úlohy opravy tisknutelnosti vždy prázdný řetězec.

    • Name
      obj
      Type
      string
      Description

      Stáhnutelná adresa URL opraveného OBJ. Vyplněno, když vstupem bylo nahrání OBJ.

    • Name
      stl
      Type
      string
      Description

      Stáhnutelná adresa URL opraveného STL. Vyplněno, když vstupem bylo nahrání STL.

    • Name
      usdz
      Type
      string
      Description

      Rezervováno pro výstup USDZ. Pro úlohy opravy tisknutelnosti vždy prázdný řetězec.

    • Name
      3mf
      Type
      string
      Description

      Rezervováno pro výstup 3MF. Pro úlohy opravy tisknutelnosti vždy prázdný řetězec.

    • Name
      mtl
      Type
      string
      Description

      Rezervováno pro výstup MTL. Pro úlohy opravy tisknutelnosti vždy prázdný řetězec.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL náhledového obrázku vyrenderovaného z opraveného modelu.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Stáhnutelná adresa URL verze thumbnail_url s průhledným pozadím (RGBA). Přítomna pouze tehdy, když byla úloha vytvořena s alpha_thumbnail: true a průhledný náhled byl úspěšně vyrenderován; jinak je toto pole vynecháno.

  • Name
    texture_urls
    Type
    array
    Description

    Vždy prázdné pole. Oprava zachovává pouze vstupní geometrii a textury znovu nevypéká.

  • Name
    consumed_credits
    Type
    integer
    Description

    Počet kreditů spotřebovaných touto úlohou. 10, jakmile úloha dosáhne stavu SUCCEEDED. Pro úlohy ve stavu FAILED vrací 0 (kredity jsou při selhání vráceny).

The Repair Printability Task Object

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "print-repair",
  "status": "SUCCEEDED",
  "progress": 100,
  "preceding_tasks": 0,
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000030000,
  "expires_at": 1715725401000,
  "task_error": null,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/model.glb?Expires=***",
    "fbx": "",
    "obj": "",
    "stl": "",
    "usdz": "",
    "3mf": "",
    "mtl": ""
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/0193bfc5-ee4f-73f8-8525-44b398884ce9/output/preview.png?Expires=***",
  "texture_urls": [],
  "consumed_credits": 10
}