lowpoly avvecklas den 30 okt. 2026. Byt modell före dessa datum för att undvika fel i förfrågningar.

UV-uppveckling API

UV-uppveckling API genererar automatiskt en högkvalitativ UV-uppveckling för en befintlig 3D-modell. Använd det som ett förutsättningssteg innan texturering — eller när du behöver en ren, icke-överlappande UV-layout för nedströmsverktyg (Blender, Substance Painter, Unreal).

Utdata är en "UV-vitmodell" — samma form som indata men med helt nya UV-koordinater och ingen riktig textur (ett 2×2 grått platshållarmaterial ingår för att hålla glTF-materialplatsen giltig; standardverktyg behandlar detta som otexturerat).

Begränsningar. Auto UV stöder för närvarande nät med upp till 40 000 ytor — större modeller avvisas med en 400; kör Remesh först för att minska polygonantalet. Quad- och n-gon-nät är triangulerade under UV-generering, så utdata är alltid ett triangelnät.

POST/openapi/v1/uv-unwrap

Create an UV Unwrap Task

Denna endpoint skapar en ny UV Unwrap-uppgift.

Uppgiften körs i bakgrunden. För information om hur lång tid det vanligtvis tar, se Processing Times.

Parametrar

Exakt en av input_task_id eller model_url krävs. Om båda anges har input_task_id prioritet.

  • Name
    input_task_id
    Type
    string
    Obligatorisk
    Description

    ID:t för en slutförd Meshy API-uppgift vars GLB-utdata du vill UV-unwrappa (till exempel ett resultat från Bild till 3D, Text till 3D eller Remesh). Källuppgiften måste ha statusen SUCCEEDED och ha genererat en GLB-fil.

    Om källnätet överskrider taket på 40 000 ytor (faces) kommer begäran att avvisas med 400, och du bör köra Remesh först för att minska polygonantalet.

  • Name
    model_url
    Type
    string
    Obligatorisk
    Description

    Ange en 3D-modell direkt via en publikt tillgänglig URL eller Data URI. Endast .glb stöds — API:et läser glTF binary och tolkar inte andra format. För att UV-unwrappa en modell i ett annat format (.fbx, .obj, .stl, .gltf), konvertera den till .glb först via Convert API, skicka sedan den resulterande uppgifts-ID:n som input_task_id eller dess GLB-utdata-URL här.

    För Data URIs, använd MIME type application/octet-stream.

    Maximal filstorlek: 400 MB för en http- eller https-URL, 100 MB för en data:-URI. En GLB över 100 MB får inte använda Draco-komprimering.

    Samma tak på 40 000 ytor gäller som för input_task_id: överdimensionerade nät avvisas med 400 — kör Remesh först.

Returvärden

Egenskapen result i svaret innehåller id för den nyligen skapade UV Unwrap-uppgiften.

Felscenarier

  • Name
    400 - Bad Request
    Description

    Begäran var inte acceptabel. Vanliga orsaker:

    • Saknad parameter: Antingen input_task_id eller model_url måste anges.
    • Ogiltig indatauppgift: input_task_id måste referera till en lyckad uppgift med ett GLB-resultat.
    • Antal ytor överskridet: Källnätet har fler ytor än UV Unwrap-taket. Kör Remesh först.
    • Ogiltigt modellformat: model_url pekar på en fil med ett filtillägg som inte stöds.
    • Oåtkomlig URL: model_url kunde inte laddas ner.
    • Modellfilen är för stor: model_url-filen överskrider 400 MB (http- eller https-URL) eller 100 MB (data:-URI).
    • För många ytor: model_url-filen är över 100 MB och har fler än 10 000 000 ytor. Minska antalet ytor och skicka sedan filen igen.
    • Oläsbar modellfil: model_url-filen är över 100 MB och dess header kan inte läsas, till exempel en Draco-komprimerad GLB.
    • Modellens header är för komplex: model_url-filen är över 100 MB och dess header har för många nät, noder eller poster att kontrollera. Minska antalet objekt i filen och skicka sedan den igen.
  • Name
    401 - Unauthorized
    Description

    Autentiseringen misslyckades. Kontrollera din API-nyckel.

  • Name
    402 - Payment Required
    Description

    Otillräckligt med credits för att utföra denna uppgift. UV Unwrap kostar 5 credits per anrop.

  • Name
    404 - Not Found
    Description

    Funktionen är inte aktiverad för ditt konto. UV Unwrap är begränsad av en Statsig-flagga under utrullningen — kontakta Meshy-supporten om du behöver åtkomst.

  • Name
    429 - Too Many Requests
    Description

    Du har överskridit din hastighetsgräns.

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

Hämta en UV-uppveckling Uppgift

Denna endpoint hämtar det aktuella tillståndet för en UV-uppveckling uppgift via ID.

Returnerar

Returnerar ett UV-uppveckling Uppgiftsobjekt.

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

Se det exempel på uppgiftsobjekt nedan.

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

Ta bort en UV-uppvecklingsuppgift

Ta bort en UV-uppvecklingsuppgift permanent. Uppgiften och dess utdata blir otillgängliga.

En uppgift som fortfarande är PENDING tas bort och de credits som förbrukades vid skapandet återbetalas.

En uppgift som redan är IN_PROGRESS kan inte tas bort: begäran avvisas med 409 Conflict och uppgiften fortsätter att köras. Credits för en uppgift som arbetaren redan har påbörjat kan inte återbetalas, så att ta bort den mitt under körningen skulle kosta dig både credits och resultatet. Vänta tills den når SUCCEEDED, FAILED eller CANCELED, ta sedan bort den.

En uppgift i ett sluttillstånd (SUCCEEDED, FAILED eller CANCELED) tas bort utan återbetalning.

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

Lista UV-uppvecklingsuppgifter

Returnerar en paginerad lista över anroparens UV-uppvecklingsuppgifter, nyaste först. Standardpaginering via page_num och 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

Strömma en UV-uppveckling-uppgift

Prenumerera på uppgiftens progress som server-sända händelser. Varje message-händelse bär ett UV-uppveckling-uppgiftsobjekt; strömmen stängs när uppgiften når SUCCEEDED, FAILED eller CANCELED.

Använd detta istället för att polla GET /openapi/v1/uv-unwrap/:id för lägre latens vid slutförande.

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

UV-uppvecklingsuppgiftsobjektet

  • Name
    id
    Type
    string
    Description

    Unik identifierare för uppgiften.

  • Name
    type
    Type
    string
    Description

    Alltid uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    Försignerade nedladdnings-URL:er för den genererade UV-vitmodellen. UV-uppveckling returnerar alltid en enda glb-post — utdata bevarar ingångsgeometrin, byter ut nya UV-koordinater och använder ett standardgrått material istället för någon textur.

  • Name
    thumbnail_url
    Type
    string
    Description

    Försignerad URL till en PNG-förhandsvisning av UV-vitmodellen.

  • Name
    progress
    Type
    integer
    Description

    Uppgiftens progress, från 0 till 100.

  • Name
    status
    Type
    string
    Description

    En av PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Antal uppgifter i kö före denna. Förekommer medan status är PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Tidsstämpel för uppgiftens skapande, i millisekunder.

  • Name
    started_at
    Type
    timestamp
    Description

    Tidsstämpel för när bearbetningen började, i millisekunder. 0 tills den startar.

  • Name
    finished_at
    Type
    timestamp
    Description

    Tidsstämpel för slutförande, i millisekunder. 0 tills den är klar.

  • Name
    expires_at
    Type
    timestamp
    Description

    Tidsstämpel efter vilken de signerade nedladdnings-URL:erna upphör att gälla, i millisekunder.

  • Name
    task_error
    Type
    object
    Description

    Felformationer för misslyckade uppgifter. Se Fel för fullständig referens till task_error-objektet.

  • Name
    consumed_credits
    Type
    integer
    Description

    Credits förbrukade av denna uppgift. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel). UV-uppveckling debiterar 5 credits vid framgång.

Exempel på UV-uppvecklingsuppgiftsobjekt

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