lowpoly bude vyřazen 30. 10. 2026. Před těmito daty přejděte na jiný model, abyste předešli chybám požadavků.

Convert API

Convert API vám umožňuje převést existující 3D modely do jiných formátů souborů.

POST/openapi/v1/convert

Create a Convert Task

Tento koncový bod vytváří novou úlohu konverze formátu.

Úloha běží na pozadí. Jak dlouho to obvykle trvá, se dozvíte v části Doby zpracování.

Parametry

Povinný je pouze jeden z parametrů input_task_id nebo model_url. Pokud jsou zadány oba, má input_task_id přednost.

  • Name
    input_task_id
    Type
    string
    Povinné
    Description

    ID dokončené úlohy Meshy, jejíž model chcete převést. Úloha musí mít stav SUCCEEDED.

  • Name
    model_url
    Type
    string
    Povinné
    Description

    Veřejně přístupná URL adresa nebo data URI odkazující na soubor 3D modelu. Podporované formáty: .glb, .gltf, .obj, .fbx, .stl. Pro data URI použijte MIME type: application/octet-stream.

    Maximální velikost souboru: 400 MB pro http nebo https URL, 100 MB pro data: URI.

    Soubor GLB, glTF, FBX nebo OBJ o velikosti nad 100 MB může mít nejvýše 10 000 000 ploch. Plochy se počítají jako trojúhelníky: čtyřúhelník se počítá jako 2 a síť vykreslená vícekrát se počítá jednou za každou kopii. Nad 100 MB musí být soubor FBX binární FBX verze 7.1 nebo novější a soubor GLB nebo glTF nesmí používat kompresi Draco.

  • Name
    target_formats
    Type
    string[]
    Povinné
    Description

    Seznam výstupních formátů pro převedený model. Dostupné hodnoty: glb, fbx, obj, usdz, blend, stl, 3mf.

Návratové hodnoty

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

Režimy selhání

  • 400 - Bad Request

Požadavek byl nepřijatelný. Časté příčiny:

  • Chybějící parametr: Musí být zadán buď model_url, nebo input_task_id.
  • Chybějící target_formats: Musí být zadán alespoň jeden cílový formát.
  • Neplatná vstupní úloha: input_task_id musí odkazovat na úspěšně dokončenou úlohu.
  • Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou.
  • Nedostupná URL: Soubor na adrese model_url se nepodařilo stáhnout.
  • Soubor modelu je příliš velký: Soubor na model_url přesahuje 400 MB (URL http nebo https) nebo 100 MB (data: URI).
  • Příliš mnoho ploch: Soubor na model_url je větší než 100 MB a má více než 10 000 000 ploch. Snižte počet ploch a soubor odešlete znovu.
  • ASCII FBX nad 100 MB: Soubor na model_url je ASCII FBX větší než 100 MB. Odešlete jej jako binární FBX nebo GLB.
  • Nečitelný soubor modelu: Soubor na model_url je větší než 100 MB a jeho hlavičku nelze přečíst, například v případě GLB nebo glTF komprimovaného pomocí Draco, nebo binárního FBX staršího než 7.1.
  • Hlavička modelu je příliš složitá: Soubor na model_url je větší než 100 MB a jeho hlavička obsahuje příliš mnoho sítí, uzlů nebo záznamů ke kontrole. Snižte počet objektů v souboru a odešlete jej znovu.
  • 401 - Unauthorized

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

  • 402 - Payment Required

Nedostatek kreditů pro provedení této úlohy.

  • 429 - Too Many Requests

Překročili jste svůj limit rychlosti.

Request

POST
/openapi/v1/convert
curl https://api.meshy.ai/openapi/v1/convert \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "target_formats": ["fbx", "stl"]
  }'

Response

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

Načtení úlohy převodu

Tento koncový bod načte úlohu převodu podle jejího ID.

Parametry

  • Name
    id
    Type
    path
    Description

    ID úlohy převodu, kterou chcete načíst.

Návratová hodnota

Objekt úlohy převodu.

Request

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

Response

{
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
      "glb": "",
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "obj": "",
      "usdz": "",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}
DELETE/openapi/v1/convert/:id

Smazání konverzní úlohy

Tento koncový bod trvale smaže konverzní úlohu, včetně všech souvisejících modelů a dat. Tuto akci nelze vrátit zpět.

Parametry cesty

  • Name
    id
    Type
    path
    Description

    ID konverzní úlohy, která má být smazána.

Stav úlohy

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

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

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

Návratové hodnoty

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

Request

DELETE
/openapi/v1/convert/:id
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/convert/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/convert

Seznam úkolů převodu

Tento koncový bod umožňuje načíst seznam úkolů převodu.

Parametry

  • Name
    page_num
    Type
    integer
    výchozí 1
    Description

    Číslo stránky pro stránkování.

  • Name
    page_size
    Type
    integer
    výchozí 10
    Description

    Limit velikosti stránky. 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: Seřadit podle času vytvoření vzestupně.
    • -created_at: Seřadit podle času vytvoření sestupně.

Návratová hodnota

Vrací stránkovaný seznam objektů úkolu převodu.

Request

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

Response

[
  {
    "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
    "type": "convert",
    "model_urls": {
      "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
      "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
    },
    "progress": 100,
    "status": "SUCCEEDED",
    "created_at": 1699999999000,
    "started_at": 1700000000000,
    "finished_at": 1700000001000,
    "task_error": null,
    "consumed_credits": 1
  }
]
GET/openapi/v1/convert/:id/stream

Streamování úlohy převodu

Tento koncový bod streamuje aktualizace úlohy převodu v reálném čase pomocí Server-Sent Events (SSE).

Parametry

  • Name
    id
    Type
    path
    Description

    Jedinečný identifikátor úlohy převodu, kterou chcete streamovat.

Návratová hodnota

Vrací proud objektů úlohy převodu formou Server-Sent Events.

U úloh ve stavu PENDING nebo IN_PROGRESS bude datový proud odpovědi obsahovat pouze nezbytná pole progress a status.

Request

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

Response Stream

// Message event examples illustrate task progress.
event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "0193bfc5-ee4f-73f8-8525-44b398884ce9",
  "type": "convert",
  "model_urls": {
    "fbx": "https://assets.meshy.ai/.../model.fbx?Expires=...",
    "stl": "https://assets.meshy.ai/.../model.stl?Expires=..."
  },
  "progress": 100,
  "status": "SUCCEEDED",
  "created_at": 1699999999000,
  "started_at": 1700000000000,
  "finished_at": 1700000001000,
  "task_error": null,
  "consumed_credits": 1
}

The Convert Task Object

Objekt Convert Task představuje úlohu převodu formátu.

Properties

  • id · string

Jedinečný identifikátor úlohy.

  • type · string

Typ úlohy. Hodnota je convert.

  • model_urls · object

Stažitelné URL adresy pro převedené soubory modelu. URL adresy budou k dispozici pouze pro formáty uvedené v target_formats. Ostatní vlastnosti formátů budou prázdné řetězce.

  • progress · integer

Progress úlohy (0–100).

  • status · string

Stav úlohy. Možné hodnoty: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • preceding_tasks · integer

Počet předcházejících úloh. Má smysl pouze v případě, že stav je PENDING.

  • created_at · timestamp

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

  • started_at · timestamp

Časové razítko okamžiku zahájení úlohy, v milisekundách. 0, pokud nebyla zahájena.

  • finished_at · timestamp

Časové razítko okamžiku dokončení úlohy, v milisekundách. 0, pokud nebyla dokončena.

  • task_error · object

Objekt chyby, pokud úloha selhala. Další podrobnosti naleznete v části Chyby.

  • consumed_credits · integer

Počet kreditů spotřebovaných touto úlohou (1 kredit za úlohu převodu). U úloh se stavem FAILED vrací 0.