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.