API pro opravu tisknutelnosti

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

POST/openapi/v1/print/repair

Vytvoření úlohy Opravit tisknutelnost

Tento koncový bod vytváří novou úlohu opravy tisknutelnosti. Úloha provádí opravu topologie na 3D modelu a vrací vodotěsnou, k tisku připravenou verzi.

Výstupní formát odpovídá vstupnímu formátu. Pokud odešlete .stl přes model_url, odpověď model_urls.stl bude obsahovat opravenou síť a ostatní pole formátu budou prázdná. Cesta input_task_id vždy čte zdrojovou úlohu GLB, takže výstup je .glb.

Parametry

Pouze jeden z input_task_id nebo model_url je požadován. Pokud jsou oba poskytnuty, input_task_id má prioritu.

Existující textury jsou během opravy odstraněny kvůli změnám geometrie. Pro přidání textur zpět použijte Retexture API na opraveném modelu.

  • Name
    model_url
    Type
    string
    Povinné
    Description

    URL 3D modelu k opravě. 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ází kontrolu 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ůstává nezměněno.

Návraty

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

Režimy selhání

  • Name
    400 - Bad Request
    Description

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

    • Chybějící parametr: nebyl poskytnut ani input_task_id, ani model_url.
    • Neplatný UUID: input_task_id není platný UUID.
    • Neplatná URL modelu: model_url je špatně formátovaná, používá nepodporované schéma nebo má nepodporovanou příponu souboru.
    • Příliš velký soubor modelu: tělo model_url překročilo 100 MB.
    • Úloha nebyla úspěšná: odkazovaná úloha je stále čekající, v průběhu nebo selhala.
    • Chybějící GLB: odkazovaná úloha nemá 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ého.
    • Nedostatečné kredity: byl dosažen limit kreditů pracovního prostoru.
  • Name
    404 - Not Found
    Description

    Odkazovaná úloha neexistuje nebo je vlastněna jiným uživatelem.

  • Name
    429 - Too Many Requests
    Description

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

Požadavek

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"
  }'

Odpověď

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

Načíst úkol Opravit tisknutelnost

Tento koncový bod načítá úkol opravy tisknutelnosti podle jeho ID.

Parametry

  • Name
    id
    Type
    path
    Description

    ID úkolu opravy tisknutelnosti, který chcete načíst.

Vrací

Objekt úkolu Opravit tisknutelnost. Blok model_urls je prázdný, dokud úkol nedosáhne stavu SUCCEEDED. Pouze pole model_urls odpovídající vstupnímu formátu je naplněno.

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": "",
    "gltf": "",
    "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

Smazat úlohu Opravit tisknutelnost

Tento koncový bod trvale smaže úlohu opravit tisknutelnost a její opravený výstup. Tato akce je nevratná.

Parametry cesty

  • Name
    id
    Type
    path
    Description

    ID úlohy opravit tisknutelnost, kterou chcete smazat.

Vrací

Vrací 200 OK při úspěchu.

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

Seznam úkolů pro Opravit tisknutelnost

Tento koncový bod vám umožňuje získat seznam úkolů pro opravu tisknutelnosti.

Parametry

Volitelné atributy

  • Name
    page_num
    Type
    integer
    Description

    Číslo stránky pro stránkování. Začíná a výchozí 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 pro třídění. Dostupné hodnoty:

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

Návraty

Vrací stránkovaný seznam Objektů úkolů pro 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=***",
      "gltf": "",
      "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

Streamování úlohy 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

    Unikátní identifikátor pro úlohu opravy tisknutelnosti ke streamování.

Návratové hodnoty

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

Pro úlohy ve stavu PENDING nebo IN_PROGRESS bude stream odpovědi obsahovat pouze potřebná pole progress a status. Blok model_urls je odeslán pouze tehdy, když ú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=***",
    "gltf": "",
    "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

    Unikátní identifikátor pro úlohu. I když používáme k-tříditelné UUID pro id úloh jako implementační detail, neměli byste dělat žádné předpoklady o formátu 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

    Pokrok úlohy. Pokud úloha ještě nezačala, tato vlastnost bude 0. Jakmile úloha uspěje, stane se 100.

  • Name
    preceding_tasks
    Type
    integer
    Description

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

    Hodnota tohoto pole má smysl pouze pokud je stav úlohy PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Časové razítko, kdy byla úloha vytvořena, v milisekundách.

  • Name
    started_at
    Type
    timestamp
    Description

    Časové razítko, kdy byla úloha zahájena, v milisekundách. Pokud úloha ještě nezačala, tato vlastnost bude 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko, kdy byla úloha dokončena, v milisekundách. Pokud úloha ještě není dokončena, tato vlastnost bude 0.

  • Name
    expires_at
    Type
    timestamp
    Description

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

  • Name
    task_error
    Type
    object
    Description

    Informace o chybě, pokud úloha selhala. Tato vlastnost je null, pokud úloha neselhala. Viz Chyby pro více podrobností.

    • Name
      message
      Type
      string
      Description

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

  • Name
    model_urls
    Type
    object
    Description

    Stahovatelné URL k opravenému 3D modelu. Pouze pole odpovídající vstupnímu formátu je vyplněno; ostatní pole formátu jsou prázdné řetězce.

    • Name
      glb
      Type
      string
      Description

      Stahovatelné URL k opravenému GLB. Vyplněno, když vstup byl GLB nebo když byl použit input_task_id.

    • Name
      gltf
      Type
      string
      Description

      Stahovatelné URL k opravenému GLTF. Vyplněno, když vstup byl nahrání GLTF.

    • Name
      fbx
      Type
      string
      Description

      Stahovatelné URL k opravenému FBX. Vyplněno, když vstup byl nahrání FBX.

    • Name
      obj
      Type
      string
      Description

      Stahovatelné URL k opravenému OBJ. Vyplněno, když vstup byl nahrání OBJ.

    • Name
      stl
      Type
      string
      Description

      Stahovatelné URL k opravenému STL. Vyplněno, když vstup byl nahrání STL.

    • Name
      usdz
      Type
      string
      Description

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

    • Name
      3mf
      Type
      string
      Description

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

    • Name
      mtl
      Type
      string
      Description

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

  • Name
    thumbnail_url
    Type
    string
    Description

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

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Stahovatelné URL k verzi thumbnail_url s průhledným pozadím (RGBA). Přítomno pouze, když byla úloha vytvořena s alpha_thumbnail: true a průhledný náhled byl úspěšně vykreslen; jinak je toto pole vynecháno.

  • Name
    texture_urls
    Type
    array
    Description

    Vždy prázdné pole. Oprava zachovává pouze vstupní geometrie a nepřebaluje textury.

  • Name
    consumed_credits
    Type
    integer
    Description

    Počet kreditů spotřebovaných touto úlohou. 10, jakmile úloha dosáhne SUCCEEDED. Vrací 0 pro úlohy FAILED (kredity jsou v případě 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=***",
    "gltf": "",
    "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
}