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

UV rozbalení API

API pro UV rozbalení automaticky generuje vysoce kvalitní UV rozbalení pro existující 3D model. Použijte ho jako předběžný krok před texturováním — nebo kdykoli potřebujete čisté, nepřekrývající se UV rozvržení pro následné nástroje (Blender, Substance Painter, Unreal).

Výstupem je "UV bílý model" — stejný tvar jako vstup, ale s novými UV souřadnicemi a bez skutečné textury (je zahrnut šedý zástupný materiál 2×2, aby byl slot materiálu glTF platný; standardní nástroje to považují za netexturované).

Omezení. Automatické UV aktuálně podporuje sítě až do 40 000 ploch — větší modely jsou odmítnuty s 400; nejprve spusťte Remesh pro snížení počtu polygonů. Čtyřúhelníkové a n-gon sítě jsou během generování UV triangulovány, takže výstup je vždy trojúhelníková síť.

POST/openapi/v1/uv-unwrap

Vytvořit úlohu UV rozbalení

Tento koncový bod vytvoří novou úlohu UV rozbalení.

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

Parametry

Je vyžadován právě jeden z parametrů input_task_id nebo model_url. Pokud jsou zadány oba, input_task_id má přednost.

  • Name
    input_task_id
    Type
    string
    Povinné
    Description

    ID dokončené úlohy Meshy API, jejíž výstup ve formátu GLB chcete UV rozbalit (například výsledek Obrázek na 3D, Text na 3D nebo Remesh). Zdrojová úloha musí mít stav SUCCEEDED a musí vytvořit soubor GLB.

    Pokud zdrojová síť přesáhne limit 40 000 stěn, bude požadavek odmítnut s kódem 400 a měli byste nejprve spustit Remesh, abyste snížili počet polygonů.

  • Name
    model_url
    Type
    string
    Povinné
    Description

    Poskytněte 3D model přímo prostřednictvím veřejně přístupné URL adresy nebo Data URI. Podporován je pouze formát .glb — API čte binární glTF a neumí parsovat jiné formáty. Chcete-li UV rozbalit model v jiném formátu (.fbx, .obj, .stl, .gltf), nejprve jej převeďte do formátu .glb pomocí Convert API a poté sem jako input_task_id předejte ID výsledné úlohy nebo URL adresu jejího GLB výstupu.

    Pro Data URI použijte MIME type application/octet-stream.

    Maximální velikost souboru: 400 MB pro URL adresu typu http nebo https, 100 MB pro data: URI. Soubor GLB nad 100 MB nesmí používat kompresi Draco.

    Platí stejný limit 40 000 stěn jako u input_task_id: nadměrně velké sítě jsou odmítnuty s kódem 400 — nejprve spusťte Remesh.

Návratové hodnoty

Vlastnost result v odpovědi obsahuje id nově vytvořené úlohy UV rozbalení.

Způsoby selhání

  • Name
    400 - Bad Request
    Description

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

    • Chybějící parametr: Musí být zadán buď input_task_id, nebo model_url.
    • Neplatná vstupní úloha: input_task_id musí odkazovat na úspěšnou úlohu s výsledkem ve formátu GLB.
    • Překročen počet stěn: Zdrojová síť má více stěn, než je limit pro UV rozbalení. Nejprve spusťte Remesh.
    • Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou.
    • Nedostupná URL adresa: Soubor z model_url se nepodařilo stáhnout.
    • Soubor modelu je příliš velký: Soubor z model_url přesahuje 400 MB (URL adresa http nebo https) nebo 100 MB (data: URI).
    • Příliš mnoho stěn: Soubor z model_url je větší než 100 MB a má více než 10 000 000 stěn. Snižte počet stěn a soubor odešlete znovu.
    • Nečitelný soubor modelu: Soubor z model_url je větší než 100 MB a jeho hlavičku nelze přečíst, například u GLB komprimovaného pomocí Draco.
    • Hlavička modelu je příliš složitá: Soubor z 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.
  • Name
    401 - Unauthorized
    Description

    Autentizace se nezdařila. Zkontrolujte prosím svůj API klíč.

  • Name
    402 - Payment Required
    Description

    Nedostatek kreditů k provedení této úlohy. UV rozbalení stojí 5 kreditů za volání.

  • Name
    404 - Not Found
    Description

    Tato funkce není pro váš účet povolena. UV rozbalení je během zavádění řízeno příznakem Statsig — pokud potřebujete přístup, kontaktujte podporu Meshy.

  • Name
    429 - Too Many Requests
    Description

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

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"
}
GET/openapi/v1/uv-unwrap/:id

Získání úkolu UV rozbalení

Tento koncový bod získává aktuální stav úkolu UV rozbalení podle ID.

Vrací

Vrací objekt úkolu UV rozbalení.

Požadavek

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}"

Viz příklad objektu úkolu níže.

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

Odstranění úlohy UV rozbalení

Trvale odstraní úlohu UV rozbalení. Úloha a její výstupy se stanou nepřístupnými.

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

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

Úloha v konečném stavu (SUCCEEDED, FAILED nebo CANCELED) je odstraněna bez vrácení kreditů.

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}"
GET/openapi/v1/uv-unwrap

Seznam úkolů UV rozbalení

Vrací stránkovaný seznam úkolů UV rozbalení volajícího, od nejnovějších. Standardní stránkování pomocí 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

Streamování úkolu UV rozbalení

Přihlaste se k odběru progressu úkolu jako události zasílané serverem. Každá událost message nese objekt úkolu UV rozbalení; stream se uzavře, jakmile úkol dosáhne stavu SUCCEEDED, FAILED nebo CANCELED.

Použijte toto místo dotazování GET /openapi/v1/uv-unwrap/:id pro nižší latenci při dokončení.

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 úlohy UV rozbalení

  • Name
    id
    Type
    string
    Description

    Unikátní identifikátor úlohy.

  • Name
    type
    Type
    string
    Description

    Vždy uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    Předem podepsané URL ke stažení pro generovaný UV bílý model. UV rozbalení vždy vrací jediný záznam glb — výstup zachovává vstupní geometrie, nahrazuje nové UV souřadnice a používá výchozí šedý materiál místo jakékoli textury.

  • Name
    thumbnail_url
    Type
    string
    Description

    Předem podepsané URL k náhledu PNG UV bílého modelu.

  • Name
    progress
    Type
    integer
    Description

    Progress úlohy, od 0 do 100.

  • Name
    status
    Type
    string
    Description

    Jeden z PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Počet úloh ve frontě před touto. Přítomno, pokud je status 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, kdy začalo zpracování, v milisekundách. 0 dokud nezačne.

  • Name
    finished_at
    Type
    timestamp
    Description

    Časové razítko dokončení, v milisekundách. 0 dokud není dokončeno.

  • Name
    expires_at
    Type
    timestamp
    Description

    Časové razítko, po kterém vyprší platnost podepsaných URL ke stažení, v milisekundách.

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě pro neúspěšné úlohy. Viz Chyby pro úplný odkaz na objekt task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Kredity spotřebované touto úlohou. Vrací 0 pro úlohy FAILED (kredity jsou vráceny při selhání). UV rozbalení účtuje 5 kreditů při úspěchu.

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
}