Opravit tisknutelnost API

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ření úlohy Opravit tisknutelnost

Tento koncový bod vytvoří novou úlohu opravy tisknutelnosti. Úloha provede opravu topology 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 přes model_url, bude model_urls.stl v odpovědi obsahovat opravenou síť a ostatní pole formátů budou prázdná. Cesta input_task_id vždy čte GLB zdrojové úlohy, takže výstupem je .glb.

Parametry

Je vyžadováno pouze jedno z input_task_id nebo model_url. Pokud jsou zadána obě, má input_task_id přednost.

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

  • Name
    model_url
    Type
    string
    Povinné
    Description

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

  • 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. Stávající pole thumbnail_url zůstává beze změny.

Návratové hodnoty

Vlastnost result v odpovědi obsahuje id nově vytvořené úlohy opravy 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ě formátováno, používá nepodporované schéma nebo má nepodporovanou příponu souboru.
    • Soubor modelu je příliš velký: obsah model_url překročil 100 MB.
    • Úloha nebyla úspěšná: 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

    Časté příčiny:

    • Bezplatný plán: vytvoření úlohy vyžaduje placený plán. Upgradujte na stránce předplatného.
    • 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 svou 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

Získání ú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, kterou chcete načíst.

Návratová hodnota

Objekt úlohy Opravit tisknutelnost. Blok model_urls je prázdný, dokud úloha nedosáhne stavu SUCCEEDED. Vyplněné je pouze pole model_urls odpovídající 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": "",
    "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 opravy tisknutelnosti

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

Parametry cesty

  • Name
    id
    Type
    path
    Description

    ID úlohy opravy tisknutelnosti, kterou chcete smazat.

Stav úlohy

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

Úlohu, která je již ve stavu IN_PROGRESS, nelze smazat: požadavek je odmítnut s chybou 409 Conflict a úloha běží dál. Kredity za úlohu, kterou už worker začal zpracovávat, nelze vrátit, takže smazání úlohy uprostřed zpracování by vás stálo jak kredity, tak výsledek. Počkejte, až úloha dosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

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

Návratová hodnota

Při úspěchu vrací 200 OK, nebo 409 Conflict, pokud je úloha ve stavu IN_PROGRESS.

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

// 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/repair

Seznam úloh Opravit tisknutelnost

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

Parametry

Volitelné 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á řadit. Dostupné hodnoty:

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

Návratové hodnoty

Vrací stránkovaný seznam objektů úlohy 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

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, kterou chcete streamovat.

Návratové hodnoty

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

Každý rámec obsahuje kompletní objekt úlohy pro danou fázi — stejnou podobu, jakou vrací koncový bod Get — takže dokud je úloha ve stavu PENDING nebo IN_PROGRESS, výstupní pole zatím nejsou naplněna (null, [] nebo {}) a finished_at má hodnotu null. Blok model_urls je odeslán 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.
// 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-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

    Jedinečný identifikátor úlohy. I když jako implementační detail používáme pro id úloh k-seřaditelné UUID, 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

    Průběh úlohy. Pokud úloha ještě nebyla zahájena, bude tato vlastnost 0. Jakmile úloha uspěje, změní se 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 vytvoření úlohy, v milisekundách.

  • Name
    started_at
    Type
    timestamp
    Description

    Časové razítko zahájení úlohy, v milisekundách. Pokud úloha ještě nebyla zahájena, bude tato vlastnost 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko dokončení úlohy, v milisekundách. Pokud úloha ještě nebyla dokončena, bude tato vlastnost 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ě nebyla dokončena.

  • Name
    task_error
    Type
    object
    Description

    Informace o chybě, pokud se úloha nezdařila. Tato vlastnost je null, pokud úloha selhala. Další podrobnosti naleznete v části Chyby.

    • Name
      message
      Type
      string
      Description

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

  • Name
    model_urls
    Type
    object
    Description

    Stažitelné URL adresy k opravenému 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

      Stažitelná URL adresa k opravenému GLB. Vyplněno, pokud byl vstupem GLB nebo pokud bylo použito input_task_id.

    • Name
      gltf
      Type
      string
      Description

      Stažitelná URL adresa k opravenému GLTF. Vyplněno, pokud byl vstupem nahraný GLTF.

    • Name
      fbx
      Type
      string
      Description

      Stažitelná URL adresa k opravenému FBX. Vyplněno, pokud byl vstupem nahraný FBX.

    • Name
      obj
      Type
      string
      Description

      Stažitelná URL adresa k opravenému OBJ. Vyplněno, pokud byl vstupem nahraný OBJ.

    • Name
      stl
      Type
      string
      Description

      Stažitelná URL adresa k opravenému STL. Vyplněno, pokud byl vstupem nahraný STL.

    • Name
      usdz
      Type
      string
      Description

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

    • Name
      3mf
      Type
      string
      Description

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

    • Name
      mtl
      Type
      string
      Description

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

  • Name
    thumbnail_url
    Type
    string
    Description

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

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Stažitelná URL adresa k verzi thumbnail_url s průhledným pozadím (RGBA). Přítomno pouze v případě, že úloha byla 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í geometrii a textury znovu nezapéká.

  • Name
    consumed_credits
    Type
    integer
    Description

    Počet kreditů spotřebovaných touto úlohou. 10, jakmile úloha dosáhne stavu SUCCEEDED. U úloh se stavem FAILED vrací 0 (v případě selhání jsou kredity 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
}