UV Unwrap API

Genereer een UV-unwrap voor een bestaand 3D-model. Voer dit uit voordat je het model textureert, of wanneer een tool zoals Blender, Substance Painter of Unreal een schone, niet-overlappende UV-layout nodig heeft.

De uitvoer is een UV-witmodel. Het heeft dezelfde vorm als de invoer, nieuwe UV-coördinaten en geen echte textuur. Het bevat een 2×2 grijs placeholder-materiaal, zodat de glTF-materiaalslot geldig blijft en standaardtools het als niet-getextureerd beschouwen.

UV Unwrap ondersteunt meshes met maximaal 40.000 vlakken. Een groter model geeft 400 terug. Om het aantal vlakken te verminderen, voer je eerst Remesh uit.

Meshy trianguleert vierhoekige en n-hoekige meshes tijdens het genereren van UV's, waardoor de uitvoer altijd een driehoeksmesh is.

POST/openapi/v1/uv-unwrap

Een UV-unwrap-taak maken

Maakt een UV-unwrap-taak.

De taak wordt op de achtergrond uitgevoerd. Voor hoe lang een taak gewoonlijk duurt, zie Verwerkingstijden.

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

Parameters

Name
input_task_id
Type
string
Verplicht
Description
Vereist, tenzij je model_url meestuurt. De ID van een Meshy API-taak waarvan je de GLB-output wilt unwrappen, bijvoorbeeld een Afbeelding naar 3D-, Tekst naar 3D- of Remesh-taak. De taak moet de status SUCCEEDED hebben en een GLB-bestand hebben geproduceerd.
De mesh mag maximaal 40.000 gezichtsvlakken (faces) hebben. Een mesh met meer geeft 400 terug. Om het aantal gezichtsvlakken te verminderen, voer eerst Remesh uit.

Name
model_url
Type
string
Verplicht
Description
Vereist, tenzij je input_task_id meestuurt. Het model dat moet worden unwrapped, als een publieke URL of een Data URI. Als je beide meestuurt, gebruikt Meshy input_task_id.
Het model moet een .glb-bestand zijn. Om een ander formaat te unwrappen, converteer het eerst naar GLB met de Convert API.
Het bestand mag maximaal 400 MB zijn vanaf een http- of https-URL, of 100 MB als Data URI. Gebruik voor een Data URI het MIME type application/octet-stream. Een GLB groter dan 100 MB mag geen Draco-compressie gebruiken.
Dezelfde limiet van 40.000 gezichtsvlakken geldt als voor input_task_id. Een mesh met meer geeft 400 terug, dus voer eerst Remesh uit.

Resultaten

Het veld result van de respons bevat de ID van de nieuwe UV-unwrap-taak.

Foutmodi

Name
400 - Bad Request
Description
Het verzoek kan niet worden uitgevoerd. Het foutbericht geeft aan welk probleem er is gevonden. Bijvoorbeeld:
- Ontbrekende parameter: Noch input_task_id, noch model_url is meegestuurd.
- Ongeldige invoertaak: input_task_id is geen geslaagde API-taak met een GLB-resultaat.
- Maximaal aantal gezichtsvlakken overschreden: De mesh heeft meer gezichtsvlakken dan UV-unwrap toestaat. Voer eerst Remesh uit.
- Ongeldig modelformaat: Het bestand bij model_url heeft een niet-ondersteunde extensie.
- Onbereikbare URL: Meshy kan het bestand bij model_url niet downloaden.
- Modelbestand te groot: Het bestand bij model_url is groter dan 400 MB vanaf een http- of https-URL, of groter dan 100 MB als Data URI.
- Te veel gezichtsvlakken: Het bestand bij model_url is groter dan 100 MB en heeft meer dan 10.000.000 gezichtsvlakken. Verminder het aantal gezichtsvlakken en stuur het bestand opnieuw.
- Onleesbaar modelbestand: Het bestand bij model_url is groter dan 100 MB en Meshy kan de header niet lezen. Het is bijvoorbeeld een Draco-gecomprimeerde GLB.
- Modelheader te complex: Het bestand bij model_url 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.
Corrigeer het verzoek en stuur het opnieuw. Zie Fouten.
Name
401 - Unauthorized
Description
De API-sleutel ontbreekt of is ongeldig. Controleer de header Authorization.
Name
402 - Payment Required
Description
Bijvoorbeeld:
- Onvoldoende credits: Het account heeft onvoldoende credits voor deze taak, of het account heeft een credietlimiet bereikt. Een UV-unwrap-taak kost 5 credits. Controleer je creditsaldo en probeer het opnieuw.
- Gratis abonnement: Het maken van een taak vereist een betaald abonnement. Upgrade je abonnement in je abonnementsinstellingen en probeer het opnieuw.
Name
403 - Forbidden
Description
input_task_id is een bas-reliëfmodel, dat deze endpoint niet kan unwrappen. Het bericht is This model type does not support this operation. Stuur een ander model.
Name
404 - Not Found
Description
input_task_id komt niet overeen met een van je taken. Controleer de taak-ID en stuur het verzoek opnieuw.
Name
429 - Too Many Requests
Description
Je hebt je rate limit overschreden. Wacht en probeer het opnieuw. Zie Rate limits.

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

Een UV-unwrap-taak ophalen

Retourneert de huidige status van een UV-unwrap-taak op basis van de bijbehorende ID.

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 voor een voorbeeldrespons het voorbeeld van een UV-unwrap-taakobject.

Retourneert

Het UV-unwrap-taakobject.

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

Een UV-unwrap-taak verwijderen

Verwijdert een UV-unwrap-taak permanent, inclusief de bijbehorende uitvoer. Je kunt een verwijdering niet ongedaan maken.

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

Taakstatus

Het verwijderen van een PENDING-taak betaalt de credits terug die zijn gebruikt bij het aanmaken ervan.

Een IN_PROGRESS-taak kan niet worden verwijderd. Het verzoek geeft 409 Conflict terug en de taak blijft doorlopen. Meshy betaalt geen credits terug voor een taak die al is gestart, dus het verwijderen ervan zou je zowel de credits als het resultaat kosten. Wacht tot de taak SUCCEEDED, FAILED of CANCELED bereikt en verwijder deze dan.

Het verwijderen van een taak met een eindstatus (SUCCEEDED, FAILED of CANCELED) betaalt de credits niet terug.

GET/openapi/v1/uv-unwrap

Lijst van UV-unwrap-taken opvragen

Retourneert een gepagineerde lijst van uw UV-unwrap-taken, nieuwste eerst. Gebruik page_num en page_size om door de lijst te bladeren.

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

Streamt de updates van een UV-unwrap-taak als Server-Sent Events (SSE). Elke message-gebeurtenis bevat een UV Unwrap task object. De stream sluit zodra de taak de status SUCCEEDED, FAILED of CANCELED bereikt.

Gebruik deze endpoint in plaats van het pollen van GET /openapi/v1/uv-unwrap/:id om eerder te weten wanneer de taak is voltooid.

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

Een UV-unwrap-taakobject beschrijft één UV-unwrap van een 3D-model. Het bevat de status, de progress en het modelbestand wanneer de taak slaagt.

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
}

Name
id
Type
string
Description
De taak-ID. Behandel deze als een ondoorzichtige tekenreeks en vertrouw niet op de opmaak ervan.
Name
type
Type
string
Description
Het taaktype, altijd uv-unwrap.
Name
model_urls
Type
object
Description
Ondertekende downloadURL's voor het UV-witmodel. UV-unwrap retourneert altijd één glb-sleutel. Het model behoudt de invoergeometrie, heeft nieuwe UV-coördinaten en gebruikt een standaard grijs materiaal in plaats van een textuur.
Name
thumbnail_url
Type
string
Description
Ondertekende downloadURL voor een PNG-voorbeeldafbeelding van het UV-witmodel.
Name
progress
Type
integer
Description
Hoeveel van de taak is voltooid, als percentage van 0 tot 100.
Name
status
Type
string
Description
De taakstatus, een van PENDING, IN_PROGRESS, SUCCEEDED, FAILED of CANCELED.
Name
preceding_tasks
Type
integer
Description
Het aantal taken dat voor deze taak in de wachtrij staat. Aanwezig terwijl de taak PENDING is.
Name
created_at
Type
timestamp
Description
Tijdstip waarop de taak is aangemaakt, in Unix-milliseconden.
Name
started_at
Type
timestamp
Description
Tijdstip waarop de taak is gestart, in Unix-milliseconden. Dit is 0 totdat de taak start.
Name
finished_at
Type
timestamp
Description
Tijdstip waarop de taak is voltooid, in Unix-milliseconden. Dit is 0 totdat de taak voltooid is.
Name
expires_at
Type
timestamp
Description
Tijdstip waarop de ondertekende downloadURL's verlopen, in Unix-milliseconden.
Name
task_error
Type
object
Description
De foutdetails wanneer de taak mislukt. Zie Fouten.
Name
consumed_credits
Type
integer
Description
Het aantal credits dat de taak heeft gebruikt. Een geslaagde UV-unwrap-taak kost 5 credits. Dit is 0 voor een FAILED-taak, omdat Meshy de credits terugbetaalt wanneer een taak mislukt.