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ů. Zobrazit všechna ukončení podpory

UV Unwrap API

Vygenerujte UV rozbalení pro existující 3D model. Spusťte jej před texturováním modelu nebo když nástroj jako Blender, Substance Painter nebo Unreal potřebuje čisté, nepřekrývající se UV rozvržení.

Výstupem je UV bílý model. Má stejný tvar jako vstup, nové UV souřadnice a žádnou skutečnou texturu. Obsahuje 2×2 šedý zástupný materiál, díky kterému zůstává slot materiálu glTF platný, a standardní nástroje jej považují za netexturovaný.

UV rozbalení podporuje sítě s až 40 000 plochami. Větší model vrátí 400. Pro snížení počtu ploch nejprve spusťte Remesh.

Meshy během generování UV triangularizuje sítě se čtyřúhelníky a n-úhelníky, takže výstupem je vždy trojúhelníková síť.

POST/openapi/v1/uv-unwrap

Vytvoření úlohy UV rozbalení

Vytvoří úlohu UV rozbalení.

Úloha běží na pozadí. Informace o tom, jak dlouho úloha obvykle trvá, najdete v části Doba zpracování.

Request

POST
/openapi/v1/uv-unwrap
# Chain from an existing Meshy task
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "input_task_id": "0193bfc5-ee4f-73f8-8525-44b398884ce9"
    }'

# Or from a publicly accessible model URL
curl https://api.meshy.ai/openapi/v1/uv-unwrap \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
      "model_url": "https://example.com/path/to/model.glb"
    }'

Response

{
  "result": "019361c6-9b34-7b23-bef2-d0107c4d92e2"
}

Parametry

  • Name
    input_task_id
    Type
    string
    Povinné
    Description

    Povinné, pokud neodešlete model_url. ID úlohy Meshy API, jejíž výstup ve formátu GLB chcete rozbalit – například úlohy Obrázek na 3D, Text na 3D nebo Remesh. Úloha musí mít stav SUCCEEDED a musí vytvořit soubor GLB.

    Síť může mít nejvýše 40 000 ploch. Síť s větším počtem vrátí 400. Pro snížení počtu ploch nejprve spusťte Remesh.

  • Name
    model_url
    Type
    string
    Povinné
    Description

    Povinné, pokud neodešlete input_task_id. Model, který se má rozbalit, jako veřejná URL adresa nebo Data URI. Pokud odešlete oboje, Meshy použije input_task_id.

    Model musí být soubor .glb. Pro rozbalení jiného formátu jej nejprve převeďte na GLB pomocí Convert API.

    Soubor může mít nejvýše 400 MB, pokud je zadán jako adresa URL http nebo https, nebo 100 MB jako Data URI. Pro Data URI použijte MIME type application/octet-stream. Soubor GLB větší než 100 MB nesmí používat kompresi Draco.

    Platí stejný limit 40 000 ploch jako u input_task_id. Síť s větším počtem vrátí 400, proto nejprve spusťte Remesh.

Návratové hodnoty

Pole result v odpovědi obsahuje ID nové úlohy UV rozbalení.

Způsoby selhání

  • Name
    400 - Bad Request
    Description

    Požadavek nelze spustit. Chybová zpráva uvádí, jaký problém byl zjištěn. Například:

    • Chybějící parametr: Nebyl odeslán ani input_task_id, ani model_url.
    • Neplatná vstupní úloha: input_task_id není úspěšnou úlohou API s výsledkem ve formátu GLB.
    • Překročen počet ploch: Síť má více ploch, než UV rozbalení umožňuje. Nejprve spusťte Remesh.
    • Neplatný formát modelu: Soubor model_url má nepodporovanou příponu.
    • Nedostupná adresa URL: Meshy nemůže stáhnout soubor model_url.
    • Soubor modelu je příliš velký: Soubor model_url je větší než 400 MB, pokud je zadán jako adresa URL http nebo https, nebo větší než 100 MB jako Data URI.
    • Příliš mnoho ploch: Soubor model_url je větší než 100 MB a má více než 10 000 000 ploch. Snižte počet ploch a odešlete soubor znovu.
    • Nečitelný soubor modelu: Soubor model_url je větší než 100 MB a Meshy nemůže přečíst jeho hlavičku. Jde například o soubor GLB komprimovaný pomocí Draco.
    • Hlavička modelu je příliš složitá: Soubor 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.

    Opravte požadavek a odešlete jej znovu. Viz Chyby.

  • Name
    401 - Unauthorized
    Description

    API klíč chybí nebo je neplatný. Zkontrolujte hlavičku Authorization.

  • Name
    402 - Payment Required
    Description

    Například:

    • Nedostatek kreditů: Účet nemá dostatek kreditů pro tuto úlohu, nebo účet dosáhl limitu kreditů. Úloha UV rozbalení stojí 5 kreditů. Zkontrolujte zůstatek kreditů a zkuste to znovu.
    • Bezplatný plán: Vytvoření úlohy vyžaduje placený plán. Upgradujte svůj plán v nastavení předplatného a zkuste to znovu.
  • Name
    403 - Forbidden
    Description

    input_task_id je model bas-reliéfu, který tento koncový bod nedokáže rozbalit. Zpráva zní This model type does not support this operation. Odešlete jiný model.

  • Name
    404 - Not Found
    Description

    input_task_id neodpovídá žádné z vašich úloh. Zkontrolujte ID úlohy a odešlete požadavek znovu.

  • Name
    429 - Too Many Requests
    Description

    Překročili jste limit rychlosti. Počkejte a zkuste to znovu. Viz Limity rychlosti.

GET/openapi/v1/uv-unwrap/:id

Získání úlohy UV rozbalení

Vrátí aktuální stav úlohy UV rozbalení podle jejího ID.

Request

GET
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Příklad odpovědi naleznete v příkladu objektu úlohy UV rozbalení.

Návratová hodnota

Objekt úlohy UV rozbalení.

DELETE/openapi/v1/uv-unwrap/:id

Smazání úlohy UV rozbalení

Trvale smaže úlohu UV rozbalení, včetně jejích výstupů. Smazání nelze vrátit zpět.

Request

DELETE
/openapi/v1/uv-unwrap/:id
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2 \
-X DELETE \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Stav úlohy

Smazání úlohy ve stavu PENDING vrátí kredity, které byly použity při jejím vytvoření.

Úlohu ve stavu IN_PROGRESS nelze smazat. Požadavek vrátí 409 Conflict a úloha pokračuje v běhu. Meshy nevrací kredity za úlohu, která již byla spuštěna, takže její smazání by vás stálo jak kredity, tak výsledek. Počkejte, dokud nedosáhne stavu SUCCEEDED, FAILED nebo CANCELED, a poté ji smažte.

Smazání úlohy v konečném stavu (SUCCEEDED, FAILED nebo CANCELED) kredity nevrací.

GET/openapi/v1/uv-unwrap

Seznam úloh UV rozbalení

Vrátí stránkovaný seznam vašich úloh UV rozbalení, seřazený od nejnovějších. Pro procházení seznamu použijte page_num a page_size.

Request

GET
/openapi/v1/uv-unwrap
curl "https://api.meshy.ai/openapi/v1/uv-unwrap?page_num=1&page_size=20" \
-H "Authorization: Bearer ${YOUR_API_KEY}"
GET/openapi/v1/uv-unwrap/:id/stream

Stream UV Unwrap task

Streamuje aktualizace úlohy UV rozbalení jako Server-Sent Events (SSE). Každá událost message nese objekt úlohy UV rozbalení. Stream se uzavře, jakmile úloha dosáhne stavu SUCCEEDED, FAILED nebo CANCELED.

Chcete-li se dříve dozvědět, že úloha skončila, použijte tento koncový bod místo opakovaného dotazování na GET /openapi/v1/uv-unwrap/:id.

Request

GET
/openapi/v1/uv-unwrap/:id/stream
curl https://api.meshy.ai/openapi/v1/uv-unwrap/019361c6-9b34-7b23-bef2-d0107c4d92e2/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-N

Objekt úkolu UV rozbalení

Objekt úkolu UV rozbalení popisuje jedno UV rozbalení 3D modelu. Obsahuje stav, progress a soubor modelu, pokud byl úkol úspěšný.

Example UV Unwrap Task Object

{
  "id": "019361c6-9b34-7b23-bef2-d0107c4d92e2",
  "type": "uv-unwrap",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/019361c6-9b34-7b23-bef2-d0107c4d92e2/output/preview.png?Expires=***",
  "progress": 100,
  "status": "SUCCEEDED",
  "preceding_tasks": 0,
  "created_at": 1716579120000,
  "started_at": 1716579122000,
  "finished_at": 1716579180000,
  "expires_at": 1716665580000,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 5
}
  • Name
    id
    Type
    string
    Description

    ID úkolu. Považujte jej za neprůhledný řetězec a nespoléhejte na jeho formát.

  • Name
    type
    Type
    string
    Description

    Typ úkolu, vždy uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    Podepsané URL adresy ke stažení pro UV bílý model. UV rozbalení vždy vrací jediný klíč glb. Model zachovává vstupní geometrii, má nové UV souřadnice a používá výchozí šedý materiál místo textury.

  • Name
    thumbnail_url
    Type
    string
    Description

    Podepsaná URL adresa ke stažení náhledového obrázku PNG pro UV bílý model.

  • Name
    progress
    Type
    integer
    Description

    Jak velká část úkolu je hotová, v procentech od 0 do 100.

  • Name
    status
    Type
    string
    Description

    Stav úkolu, jeden z PENDING, IN_PROGRESS, SUCCEEDED, FAILED nebo CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Počet úkolů před tímto úkolem ve frontě. Přítomno, dokud je úkol ve stavu PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Čas vytvoření úkolu, v milisekundách Unix.

  • Name
    started_at
    Type
    timestamp
    Description

    Čas spuštění úkolu, v milisekundách Unix. Je 0, dokud úkol nezačne.

  • Name
    finished_at
    Type
    timestamp
    Description

    Čas dokončení úkolu, v milisekundách Unix. Je 0, dokud úkol neskončí.

  • Name
    expires_at
    Type
    timestamp
    Description

    Čas vypršení platnosti podepsaných URL adres ke stažení, v milisekundách Unix.

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě, pokud úkol selže. Viz Chyby.

  • Name
    consumed_credits
    Type
    integer
    Description

    Počet kreditů, které úkol spotřeboval. Úspěšný úkol UV rozbalení stojí 5 kreditů. U úkolu se stavem FAILED je to 0, protože Meshy vrací kredity, pokud úkol selže.