API pro UV rozbalení

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

Výstupem je „UV bílý model“ — stejný tvar jako vstup, ale se zcela novými UV souřadnicemi a bez skutečné textury (je zahrnut šedý zástupný materiál 2×2, aby slot materiálu glTF zůstal platný; standardní nástroje s tím pracují jako s modelem bez textury).

Omezení. Automatické UV aktuálně podporuje sítě až do 40 000 plošek — větší modely jsou odmítnuty s 400; nejprve spusťte Remesh, abyste snížili počet polygonů. Sítě se čtyřúhelníky a n-gony jsou během generování UV triangulovány, takže výstupem 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í.

Parametry

Je vyžadován právě jeden z 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 API, jejíž výstup 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řekročí limit počtu stěn 40 000, požadavek bude odmítnut s kódem 400 a nejprve byste měli 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 nebo Data URI. Podporováno je pouze .glb — API čte binární glTF a neparsuje jiné formáty. Chcete-li UV rozbalit model v jiném formátu (.fbx, .obj, .stl, .gltf), nejprve jej převeďte na .glb prostřednictvím API Převést, poté zde předejte ID výsledné úlohy jako input_task_id nebo URL jejího výstupu GLB.

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

    Platí stejný limit 40 000 stěn jako pro input_task_id: příliš velké sítě jsou odmítnuty s kódem 400 — nejprve spusťte Remesh.

Vrací

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

Režimy selhání

  • Name
    400 - Bad Request
    Description

    Požadavek byl nepřijatelný. Běžné 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 GLB.
    • Překročen počet stěn: Zdrojová síť má více stěn než limit UV rozbalení. Nejprve spusťte Remesh.
    • Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou.
    • Nedostupná URL: model_url se nepodařilo stáhnout.
  • Name
    401 - Unauthorized
    Description

    Selhala autentizace. 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

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

Tento koncový bod načte aktuální stav úlohy UV rozbalení podle ID.

Vrací

Vrací objekt úlohy UV rozbalení.

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

Viz ukázkový objekt úlohy níže.

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

Odstranění úlohy UV rozbalení

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

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

Vrací stránkovaný seznam úloh 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

Streamovat úlohu UV rozbalení

Odebírejte progress úlohy jako události Server-Sent Events. Každá událost message nese objekt úlohy UV rozbalení; stream se uzavře, jakmile úloha 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

    Jedinečný identifikátor úlohy.

  • Name
    type
    Type
    string
    Description

    Vždy uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    Předem podepsané adresy URL ke stažení vygenerovaného UV bílého modelu. UV rozbalení vždy vrací jednu položku glb — výstup zachovává vstupní geometrii, dosadí nové UV souřadnice a místo jakékoli textury použije výchozí šedý materiál.

  • Name
    thumbnail_url
    Type
    string
    Description

    Předem podepsaná adresa 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

    Jedna z hodnot PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Počet úloh zařazených ve frontě před touto úlohou. Přítomno, když je stav 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 zahájení zpracování, v milisekundách. 0 do zahájení.

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

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

  • Name
    task_error
    Type
    object
    Description

    Podrobnosti o chybě pro neúspěšné úlohy. Úplnou referenci objektu task_error najdete v části Chyby.

  • Name
    consumed_credits
    Type
    integer
    Description

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

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
}