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