UV-unwrap-API

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

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

Beperkingen. Auto UV ondersteunt momenteel meshes tot 40.000 vlakken — grotere modellen worden geweigerd met een 400; voer eerst Remesh uit om het polygonaantal te verlagen. Quad- en n-gon-meshes worden tijdens het genereren van UV's getrianguleerd, dus de uitvoer is altijd een driehoeksmesh.

POST/openapi/v1/uv-unwrap

Een UV-unwrap-taak maken

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

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-uitvoer 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 geproduceerd.

    Als de bron-mesh de limiet voor het aantal vlakken 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 openbaar toegankelijke URL of Data URI. Alleen .glb wordt ondersteund — de API leest glTF binary en verwerkt geen andere indelingen. Om een model in een andere indeling (.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 door als input_task_id of de GLB-uitvoer-URL ervan hier.

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

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

Retourneert

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

Foutmodi

  • Name
    400 - Bad Request
    Description

    Het verzoek was ongeldig. Veelvoorkomende oorzaken:

    • Ontbrekende parameter: Ofwel input_task_id ofwel model_url moet worden opgegeven.
    • Ongeldige invoertaak: De input_task_id moet verwijzen naar een geslaagde taak met een GLB-resultaat.
    • Aantal vlakken overschreden: De bron-mesh heeft meer vlakken dan de UV-unwrap-limiet. Voer eerst Remesh uit.
    • Ongeldige modelindeling: De model_url verwijst 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 aanroep.

  • Name
    404 - Not Found
    Description

    De 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

Een UV-unwrap-taak ophalen

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

Een UV-unwrap-taak verwijderen

Verwijder een UV-unwrap-taak permanent. De taak en de uitvoer 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

UV-unwrap-taken weergeven

Retourneert een gepagineerde lijst van de UV-unwrap-taken van de aanroeper, 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 task-progress als Server-Sent Events. Elke message-gebeurtenis bevat een UV-unwrap-taakobject; de stream sluit zodra de taak SUCCEEDED, FAILED of CANCELED bereikt.

Gebruik dit in plaats van polling met 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 één enkele glb-vermelding — de uitvoer behoudt de invoergeometrie, vervangt deze door nieuwe UV-coördinaten en gebruikt een standaard grijs materiaal in plaats van enige textuur.

  • Name
    thumbnail_url
    Type
    string
    Description

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

  • Name
    progress
    Type
    integer
    Description

    Taakprogress, 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 dat vóór deze in de wachtrij staat. Aanwezig wanneer de status PENDING is.

  • Name
    created_at
    Type
    timestamp
    Description

    Tijdstempel van het aanmaken van de taak, in milliseconden.

  • Name
    started_at
    Type
    timestamp
    Description

    Tijdstempel van wanneer de verwerking begon, in milliseconden. 0 totdat deze is gestart.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tijdstempel van voltooiing, in milliseconden. 0 totdat deze is 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 brengt 5 credits in rekening bij succes.

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
}