meshy-5 bude vyřazen 10. 10. 2026. 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

Vytvoření konverzní úlohy

Tento koncový bod vytvoří novou úlohu pro konverzi formátu.

Parametry

Je vyžadován pouze jeden z parametrů input_task_id nebo model_url. Pokud jsou zadány oba, input_task_id má prioritu.

  • 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.

  • 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 v odpovědi obsahuje id nově vytvořené konverzní úlohy.

Chybové stavy

  • 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 adresa: model_url se nepodařilo stáhnout.
  • 401 - Unauthorized

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

  • 402 - Payment Required

Nedostatek kreditů k 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.