API Unwrap UV

L'API Unwrap UV genera automaticamente un unwrap UV di alta qualità per un modello 3D esistente. Usala come passaggio preliminare prima della texturizzazione — o ogni volta che hai bisogno di un layout UV pulito e senza sovrapposizioni per strumenti a valle (Blender, Substance Painter, Unreal).

L'output è un "modello bianco UV" — stessa forma dell'input ma con coordinate UV completamente nuove e nessuna vera texture (è incluso un materiale segnaposto grigio 2×2 per mantenere valido lo slot del materiale glTF; gli strumenti standard lo trattano come non texturizzato).

Limitazioni. Auto UV attualmente supporta mesh fino a 40.000 facce — i modelli più grandi vengono rifiutati con un 400; esegui prima Remesh per ridurre il conteggio poligoni. Le mesh quad e n-gon vengono triangolate durante la generazione UV, quindi l'output è sempre una mesh triangolare.

POST/openapi/v1/uv-unwrap

Crea un'attività di Unwrap UV

Questo endpoint crea una nuova attività di Unwrap UV.

Parametri

È richiesto esattamente uno tra input_task_id o model_url. Se vengono forniti entrambi, input_task_id ha la priorità.

  • Name
    input_task_id
    Type
    string
    Obbligatorio
    Description

    L'ID di un'attività Meshy API completata di cui desideri eseguire l'Unwrap UV dell'output GLB (ad esempio un risultato Immagine in 3D, Testo in 3D o Remesh). L'attività di origine deve avere uno stato SUCCEEDED e aver prodotto un file GLB.

    Se la mesh di origine supera il limite massimo di 40.000 facce, la richiesta verrà rifiutata con un 400 e dovresti eseguire prima Remesh per ridurre il conteggio poligoni.

  • Name
    model_url
    Type
    string
    Obbligatorio
    Description

    Fornisci un modello 3D direttamente tramite un URL accessibile pubblicamente o una Data URI. È supportato solo .glb — l'API legge il binario glTF e non analizza altri formati. Per eseguire l'Unwrap UV di un modello in un altro formato (.fbx, .obj, .stl, .gltf), convertilo prima in .glb tramite la API Converti, quindi passa l'ID dell'attività risultante come input_task_id o qui il suo URL di output GLB.

    Per le Data URI, usa il MIME type application/octet-stream.

    Si applica lo stesso limite massimo di 40.000 facce previsto per input_task_id: le mesh sovradimensionate vengono rifiutate con un 400 — esegui prima Remesh.

Restituisce

La proprietà result della risposta contiene l'id dell'attività di Unwrap UV appena creata.

Modalità di errore

  • Name
    400 - Bad Request
    Description

    La richiesta non era accettabile. Cause comuni:

    • Parametro mancante: Deve essere fornito input_task_id o model_url.
    • Attività di input non valida: input_task_id deve fare riferimento a un'attività riuscita con un risultato GLB.
    • Conteggio facce superato: La mesh di origine ha più facce del limite di Unwrap UV. Esegui prima Remesh.
    • Formato modello non valido: model_url punta a un file con un'estensione non supportata.
    • URL non raggiungibile: Non è stato possibile scaricare model_url.
  • Name
    401 - Unauthorized
    Description

    Autenticazione non riuscita. Controlla la tua chiave API.

  • Name
    402 - Payment Required
    Description

    Crediti insufficienti per eseguire questa attività. Unwrap UV costa 5 crediti per chiamata.

  • Name
    404 - Not Found
    Description

    La funzionalità non è abilitata per il tuo account. Unwrap UV è controllato da un flag Statsig durante il rollout — contatta il supporto Meshy se hai bisogno di accesso.

  • Name
    429 - Too Many Requests
    Description

    Hai superato il tuo limite di frequenza.

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

Recupera un'attività di Unwrap UV

Questo endpoint recupera lo stato attuale di un'attività di Unwrap UV per ID.

Restituisce

Restituisce un oggetto Attività di Unwrap UV.

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

Vedi l'oggetto attività di esempio qui sotto.

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

Elimina un'attività di Unwrap UV

Elimina definitivamente un'attività di Unwrap UV. L'attività e i suoi output diventano inaccessibili.

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

Elenca attività di Unwrap UV

Restituisce un elenco paginato delle attività di Unwrap UV del chiamante, prima le più recenti. Paginazione standard tramite page_num e 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

Eseguire lo streaming di un'attività di Unwrap UV

Sottoscrivi il progress dell'attività come Server-Sent Events. Ogni evento message contiene un oggetto attività di Unwrap UV; lo stream si chiude quando l'attività raggiunge SUCCEEDED, FAILED o CANCELED.

Usa questo invece del polling di GET /openapi/v1/uv-unwrap/:id per una latenza inferiore al completamento.

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

L'oggetto Task UV Unwrap

  • Name
    id
    Type
    string
    Description

    Identificatore univoco del task.

  • Name
    type
    Type
    string
    Description

    Sempre uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

    URL di download prefirmati per il modello bianco UV generato. UV Unwrap restituisce sempre una singola voce glb: l'output preserva la geometria di input, sostituisce con nuove coordinate UV e usa un materiale grigio predefinito al posto di qualsiasi texture.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL prefirmato a un'anteprima PNG del modello bianco UV.

  • Name
    progress
    Type
    integer
    Description

    progress del task, da 0 a 100.

  • Name
    status
    Type
    string
    Description

    Uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Numero di task in coda prima di questo. Presente mentre lo stato è PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    timestamp di creazione del task, in millisecondi.

  • Name
    started_at
    Type
    timestamp
    Description

    timestamp di quando è iniziata l'elaborazione, in millisecondi. 0 finché non è iniziata.

  • Name
    finished_at
    Type
    timestamp
    Description

    timestamp di completamento, in millisecondi. 0 finché non è terminato.

  • Name
    expires_at
    Type
    timestamp
    Description

    timestamp dopo il quale gli URL di download firmati scadono, in millisecondi.

  • Name
    task_error
    Type
    object
    Description

    Dettagli dell'errore per i task non riusciti. Consulta Errori per il riferimento completo all'oggetto task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    crediti consumati da questo task. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di errore). UV Unwrap addebita 5 crediti in caso di successo.

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
}