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