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ření úkolu UV rozbalení

Tento koncový bod vytváří nový úkol UV rozbalení.

Parametry

Je vyžadován přesně jeden z input_task_id nebo model_url. Pokud jsou poskytnuty oba, input_task_id má prioritu.

  • Name
    input_task_id
    Type
    string
    Povinné
    Description

    ID dokončeného úkolu Meshy API, jehož GLB výstup chcete UV rozbalit (například výsledek Obrázek na 3D, Text na 3D nebo Remesh). Zdrojový úkol musí mít stav SUCCEEDED a musí produkovat GLB soubor.

    Pokud zdrojová síť překročí strop počtu ploch 40 000 ploch, požadavek bude odmítnut s 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 nebo Data URI. Podporován 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 Convert API, poté zde zadejte ID úkolu jako input_task_id nebo jeho GLB výstupní URL.

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

    Stejný strop 40 000 ploch platí jako pro input_task_id: nadměrné sítě jsou odmítnuty s 400 — nejprve spusťte Remesh.

Návratové hodnoty

Vlastnost result odpovědi obsahuje id nově vytvořeného úkolu 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 poskytnut buď input_task_id nebo model_url.
    • Neplatný vstupní úkol: input_task_id musí odkazovat na úspěšný úkol s GLB výsledkem.
    • Překročený počet ploch: Zdrojová síť má více ploch než strop UV rozbalení. Nejprve spusťte Remesh.
    • Neplatný formát modelu: model_url odkazuje na soubor s nepodporovanou příponou.
    • Nedosažitelná URL: model_url nelze stáhnout.
  • Name
    401 - Unauthorized
    Description

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

  • Name
    402 - Payment Required
    Description

    Nedostatečné kredity pro provedení tohoto úkolu. UV rozbalení stojí 5 kreditů za volání.

  • Name
    404 - Not Found
    Description

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

  • Name
    429 - Too Many Requests
    Description

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

Požadavek

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

Odpověď

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

Smazat úkol UV rozbalení

Trvale smažte úkol UV rozbalení. Úkol a jeho 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 ú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
}