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

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 tillhandahålls, 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 Bild till 3D, Text till 3D eller Remesh-resultat). Källuppgiften måste ha statusen SUCCEEDED och ha producerat en GLB-fil.

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

  • Name
    model_url
    Type
    string
    Obligatorisk
    Description

    Tillhandahåll en 3D-modell direkt via en offentligt tillgänglig URL eller data URI. Endast .glb stöds — API:et läser glTF-binär 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 Convert API, och skicka sedan det resulterande uppgifts-ID:t som input_task_id eller dess GLB-utdata-URL här.

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

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

Returnerar

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

Felmod

  • Name
    400 - Bad Request
    Description

    Begäran var oacceptabel. Vanliga orsaker:

    • Saknad parameter: Antingen input_task_id eller model_url måste tillhandahållas.
    • Ogiltig indatauppgift: input_task_id måste hänvisa till en lyckad uppgift med ett GLB-resultat.
    • Överskridet antal ytor: Källnätet har fler ytor än UV-uppvecklingstaket. Kör Remesh först.
    • Ogiltigt modelformat: model_url pekar på en fil med en icke-stödd filändelse.
    • Oåtkomlig URL: model_url kunde inte laddas ner.
  • Name
    401 - Unauthorized
    Description

    Autentisering misslyckades. Kontrollera din API-nyckel.

  • Name
    402 - Payment Required
    Description

    Otillräckliga 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 begränsad av en Statsig-flagga under utrullning — kontakta Meshy-support 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-uppveckling-uppgift

Ta bort en UV-uppveckling-uppgift permanent. Uppgiften och dess resultat blir oåtkomliga.

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
}