lowpoly wordt op 30 okt 2026 uitgefaseerd. Stap vóór deze datums over op een ander model om fouten bij verzoeken te voorkomen.

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

Create an UV Unwrap Task

Deze endpoint maakt een nieuwe UV-unwrap-taak aan.

De taak wordt op de achtergrond uitgevoerd. Voor een indicatie van de benodigde tijd, zie Verwerkingstijden.

Parameters

Precies één van input_task_id of model_url is vereist. Als beide worden opgegeven, krijgt input_task_id prioriteit.

  • Name
    input_task_id
    Type
    string
    Verplicht
    Description

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

    Als de bronmesh de limiet 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

    Geef een 3D-model direct op via een publiek toegankelijke URL of data-URI. Alleen .glb wordt ondersteund — de API leest binaire glTF en parseert geen andere formaten. Om een model in een ander formaat (.fbx, .obj, .stl, .gltf) te UV-unwrappen, converteer je het eerst naar .glb via de Convert API, en geef je vervolgens de resulterende taak-ID op als input_task_id of de GLB-outputURL hier.

    Gebruik voor Data URI's het MIME type application/octet-stream.

    Maximale bestandsgrootte: 400 MB voor een http- of https-URL, 100 MB voor een data:-URI. Een GLB groter dan 100 MB mag geen Draco-compressie gebruiken.

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

Returns

De result-eigenschap van de response bevat de id van de nieuw aangemaakte UV-unwrap-taak.

Foutmodi

  • Name
    400 - Bad Request
    Description

    Het verzoek was onacceptabel. Veelvoorkomende oorzaken:

    • Ontbrekende parameter: Ofwel input_task_id ofwel model_url moet worden opgegeven.
    • Ongeldige invoertaak: input_task_id moet verwijzen naar een succesvolle taak met een GLB-resultaat.
    • Vlakkenaantal overschreden: De bronmesh heeft meer vlakken dan de limiet voor UV-unwrap. Voer eerst Remesh uit.
    • Ongeldig modelformaat: model_url verwijst naar een bestand met een niet-ondersteunde extensie.
    • Onbereikbare URL: Het model_url-bestand kon niet worden gedownload.
    • Modelbestand te groot: Het model_url-bestand overschrijdt 400 MB (http- of https-URL) of 100 MB (data:-URI).
    • Te veel vlakken: Het model_url-bestand is groter dan 100 MB en heeft meer dan 10.000.000 vlakken. Verminder het aantal vlakken en stuur het bestand opnieuw.
    • Onleesbaar modelbestand: Het model_url-bestand is groter dan 100 MB en de header kan niet worden gelezen, bijvoorbeeld een Draco-gecomprimeerde GLB.
    • Modelheader te complex: Het model_url-bestand is groter dan 100 MB en de header bevat te veel meshes, nodes of records om te controleren. Verminder het aantal objecten in het bestand en stuur het opnieuw.
  • 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 aanroep.

  • Name
    404 - Not Found
    Description

    Deze functie is niet ingeschakeld voor je account. UV-unwrap wordt tijdens de uitrol afgeschermd door een Statsig-vlag — neem contact op met Meshy-support 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 een UV-unwrap-taak permanent. De taak en de bijbehorende output worden ontoegankelijk.

Een taak die nog PENDING is, wordt verwijderd en de credits die bij het aanmaken zijn verbruikt, worden terugbetaald.

Een taak die al IN_PROGRESS is, kan niet worden verwijderd: het verzoek wordt geweigerd met 409 Conflict en de taak blijft actief. Credits voor een taak waarmee de worker al is begonnen, worden niet terugbetaald, dus het verwijderen ervan tijdens het uitvoeren zou u zowel de credits als het resultaat kosten. Wacht tot de status SUCCEEDED, FAILED of CANCELED is, en verwijder de taak dan.

Een taak in een eindstatus (SUCCEEDED, FAILED of CANCELED) wordt verwijderd zonder terugbetaling.

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
}