UV Unwrap API

De UV Unwrap API genereert automatisch een hoogwaardige UV-unwrap voor een bestaand 3D-model. Gebruik het als de vereiste stap vóór het textureren — of wanneer je een schoon, niet-overlappend UV-layout nodig hebt voor downstream tools (Blender, Substance Painter, Unreal).

De output is een "UV-witmodel" — dezelfde vorm als de input maar met gloednieuwe UV-coördinaten en geen echte textuur (een 2×2 grijs placeholder-materiaal is inbegrepen om de glTF-materiaal slot geldig te houden; standaardtools behandelen dit als ongetextureerd).

Beperkingen. Auto UV ondersteunt momenteel meshes tot 40.000 vlakken — grotere modellen worden afgewezen met een 400; voer eerst Remesh uit om het polygonaantal te verminderen. Quad en n-gon meshes worden getrianguleerd tijdens de UV-generatie, dus de output is altijd een driehoekmesh.

POST/openapi/v1/uv-unwrap

Maak een UV-unwrap-taak

Deze endpoint creëert een nieuwe UV-unwrap-taak.

Parameters

Exact één van input_task_id of model_url is vereist. Als beide worden verstrekt, heeft input_task_id prioriteit.

  • Name
    input_task_id
    Type
    string
    Verplicht
    Description

    De ID van een voltooide Meshy API-taak waarvan je de GLB-uitvoer wilt UV-unwrappen (bijvoorbeeld een Afbeelding naar 3D, Tekst naar 3D, of Remesh resultaat). De bronopdracht moet een status van SUCCEEDED hebben en een GLB-bestand hebben geproduceerd.

    Als de bronmesh de grens van 40.000 vlakken overschrijdt, wordt het verzoek afgewezen met een 400 en moet je eerst Remesh uitvoeren om het polygonaantal te verlagen.

  • Name
    model_url
    Type
    string
    Verplicht
    Description

    Bied een 3D-model direct aan via een openbaar toegankelijke URL of Data URI. Alleen .glb wordt ondersteund — de API leest glTF-binary en parseert geen andere formaten. Om een model in een ander formaat (.fbx, .obj, .stl, .gltf) te UV-unwrappen, converteer het eerst naar .glb via de Convert API, en geef dan de resulterende taak-ID door als input_task_id of de GLB-uitvoer-URL hier.

    Voor Data URI's, gebruik de MIME type application/octet-stream.

    Dezelfde grens van 40.000 vlakken geldt als voor input_task_id: te grote meshes worden afgewezen met een 400 — voer eerst Remesh uit.

Retourneert

De result eigenschap van de respons bevat de id van de nieuw gecreëerde UV-unwrap-taak.

Foutmodi

  • Name
    400 - Bad Request
    Description

    Het verzoek was onacceptabel. Veelvoorkomende oorzaken:

    • Ontbrekende parameter: Ofwel input_task_id of model_url moet worden verstrekt.
    • Ongeldige invoertaak: De input_task_id moet verwijzen naar een succesvolle taak met een GLB-resultaat.
    • Vlakkenaantal overschreden: De bronmesh heeft meer vlakken dan de UV-unwrap-grens. Voer eerst Remesh uit.
    • Ongeldig modelformaat: De model_url wijst naar een bestand met een niet-ondersteunde extensie.
    • Onbereikbare URL: De model_url kon niet worden gedownload.
  • Name
    401 - Unauthorized
    Description

    Authenticatie mislukt. Controleer je API-sleutel.

  • Name
    402 - Payment Required
    Description

    Onvoldoende credits om deze taak uit te voeren. UV Unwrap kost 5 credits per oproep.

  • Name
    404 - Not Found
    Description

    De functie is niet ingeschakeld voor je account. UV Unwrap is beperkt door een Statsig-vlag tijdens de uitrol — neem contact op met Meshy-ondersteuning als je toegang nodig hebt.

  • Name
    429 - Too Many Requests
    Description

    Je hebt je rate limit overschreden.

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

Haal een UV-unwrap-taak op

Deze endpoint haalt de huidige status van een UV-unwrap-taak op via ID.

Retourneert

Retourneert een UV-unwrap-taakobject.

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

Zie het voorbeeldtaakobject hieronder.

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

Verwijder een UV-unwrap taak

Verwijder permanent een UV-unwrap taak. De taak en de resultaten ervan worden ontoegankelijk.

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

Lijst UV-unwrap taken

Geeft een gepagineerde lijst van de UV-unwrap taken van de beller, nieuwste eerst. Standaard paginering via page_num en 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 een UV-unwrap-taak

Abonneer je op taakprogress als Server-Sent Events. Elk message-event draagt een UV-unwrap-taakobject; de stream sluit zodra de taak SUCCEEDED, FAILED of CANCELED bereikt.

Gebruik dit in plaats van het pollen van GET /openapi/v1/uv-unwrap/:id voor lagere latentie bij voltooiing.

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

Het UV Unwrap Taakobject

  • Name
    id
    Type
    string
    Description

    Unieke identificatie voor de taak.

  • Name
    type
    Type
    string
    Description

    Altijd uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    Vooraf ondertekende download-URL's voor het gegenereerde UV-witmodel. UV Unwrap retourneert altijd een enkele glb-vermelding — de output behoudt de invoergeometrie, vervangt deze door nieuwe UV-coördinaten en gebruikt een standaard grijs materiaal in plaats van een textuur.

  • Name
    thumbnail_url
    Type
    string
    Description

    Vooraf ondertekende URL naar een PNG-voorbeeld van het UV-witmodel.

  • Name
    progress
    Type
    integer
    Description

    Taakvoortgang, van 0 tot 100.

  • Name
    status
    Type
    string
    Description

    Een van PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Aantal taken in de wachtrij voor deze. Aanwezig terwijl de status PENDING is.

  • Name
    created_at
    Type
    timestamp
    Description

    Tijdstempel van taakcreatie, in milliseconden.

  • Name
    started_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de verwerking begon, in milliseconden. 0 tot gestart.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tijdstempel van voltooiing, in milliseconden. 0 tot voltooid.

  • Name
    expires_at
    Type
    timestamp
    Description

    Tijdstempel waarna de ondertekende download-URL's verlopen, in milliseconden.

  • Name
    task_error
    Type
    object
    Description

    Foutdetails voor mislukte taken. Zie Fouten voor de volledige task_error objectreferentie.

  • Name
    consumed_credits
    Type
    integer
    Description

    Credits verbruikt door deze taak. Retourneert 0 voor FAILED taken (credits worden terugbetaald bij mislukking). UV Unwrap kost 5 credits bij succes.

Voorbeeld UV Unwrap Taakobject

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