API för UV-uppveckling

API:t för UV-uppveckling genererar automatiskt en UV-uppveckling av hög kvalitet för en befintlig 3D-modell. Använd det som ett nödvändigt steg före texturering — eller när du behöver en ren, icke-överlappande UV-layout för efterföljande verktyg (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 trianguleras under UV-genereringen, så utdata är alltid ett triangelnät.

POST/openapi/v1/uv-unwrap

Skapa en UV-uppvecklingsuppgift

Denna endpoint skapar en ny UV-uppvecklingsuppgift.

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-uppveckla (till exempel ett resultat från Bild till 3D, Text till 3D eller Remesh). Källuppgiften måste ha statusen SUCCEEDED och ha skapat en GLB-fil.

    Om källans nät överskrider gränsen för antal ytor på 40 000 ytor kommer begäran att avvisas med en 400 och du bör köra Remesh först för att sänka polygonantalet.

  • Name
    model_url
    Type
    string
    Obligatorisk
    Description

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

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

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

Returnerar

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

Fellägen

  • 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 hänvisa till en lyckad uppgift med ett GLB-resultat.
    • Antal ytor överskridet: Källans nät har fler ytor än gränsen för UV-uppveckling. Kör Remesh först.
    • Ogiltigt modellformat: model_url pekar på en fil med ett tillägg som inte stöds.
    • Oåtkomlig URL: model_url kunde inte laddas ned.
  • Name
    401 - Unauthorized
    Description

    Autentisering misslyckades. Kontrollera din API-nyckel.

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

    Funktionen är inte aktiverad för ditt konto. UV-uppveckling är spärrad 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-uppvecklingsuppgift

Denna endpoint hämtar aktuellt tillstånd för en UV-uppvecklingsuppgift efter ID.

Returnerar

Returnerar ett UV-uppvecklingsuppgiftsobjekt.

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 exempeluppgiftsobjektet nedan.

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

Ta bort en UV-uppvecklingsuppgift

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

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

Prenumerera på uppgiftens progress som Server-Sent Events. Varje message-händelse innehåller ett UV-uppvecklingsuppgiftsobjekt; 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-uppvecklingens uppgiftsobjekt

  • 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 indatans geometri, byter till nya UV-koordinater och använder ett standardgrått material i stället för eventuell 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 som står i kö före denna. Finns när status är PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Tidsstämpel för när uppgiften skapades, i millisekunder.

  • Name
    started_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • 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

    Feldetaljer för misslyckade uppgifter. Se Fel för den fullständiga objektreferensen för task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Credits som förbrukats av denna uppgift. Returnerar 0 för FAILED-uppgifter (credits återbetalas vid fel). UV-uppveckling debiterar 5 credits vid lyckat resultat.

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
}