lowpoly verrà ritirato il 30 ott 2026. Cambia modello prima di queste date per evitare errori nelle richieste.

API di Unwrap UV

L'API di Unwrap UV genera automaticamente un unwrap UV di alta qualità per un modello 3D esistente. Usalo come passaggio preliminare prima di applicare texture — 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 nuove coordinate UV e nessuna vera texture (un materiale segnaposto grigio 2×2 è incluso per mantenere valido lo slot materiale glTF; gli strumenti standard trattano questo come non texturizzato).

Limitazioni. Auto UV attualmente supporta mesh fino a 40.000 facce — modelli più grandi vengono rifiutati con un 400; esegui prima Remesh per ridurre il conteggio poligoni. Le mesh quad e n-gon sono 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.

L'attività viene eseguita in background. Per informazioni sulla durata tipica, consulta Tempi di elaborazione.

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 il cui output GLB si desidera sottoporre a Unwrap UV (ad esempio un risultato di 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à respinta con un 400 ed è necessario eseguire prima il Remesh per ridurre il conteggio poligoni.

  • Name
    model_url
    Type
    string
    Obbligatorio
    Description

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

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

    Dimensione massima del file: 100 MB.

    Si applica lo stesso limite di 40.000 facce previsto per input_task_id: le mesh di dimensioni eccessive vengono respinte con un 400 — esegui prima il Remesh.

Valori restituiti

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

Modalità di errore

  • Name
    400 - Bad Request
    Description

    La richiesta non è stata accettata. Cause comuni:

    • Parametro mancante: deve essere fornito input_task_id oppure model_url.
    • Attività di input non valida: input_task_id deve fare riferimento a un'attività completata con successo e con un risultato GLB.
    • Conteggio poligoni superato: la mesh di origine ha più facce del limite massimo previsto per l'Unwrap UV. Esegui prima il Remesh.
    • Formato del modello non valido: model_url punta a un file con un'estensione non supportata.
    • URL non raggiungibile: non è stato possibile scaricare il file indicato in model_url.
    • File del modello troppo grande: il file indicato in model_url supera i 100 MB.
  • Name
    401 - Unauthorized
    Description

    Autenticazione fallita. Verifica la tua chiave API.

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

    La funzionalità non è abilitata per il tuo account. L'Unwrap UV è soggetto a un flag Statsig durante il rollout — contatta il supporto Meshy se hai bisogno di accedervi.

  • Name
    429 - Too Many Requests
    Description

    Hai superato il 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 tramite 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'esempio di oggetto attività 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.

Un'attività ancora PENDING viene eliminata e i crediti consumati al momento della creazione vengono rimborsati.

Un'attività già IN_PROGRESS non può essere eliminata: la richiesta viene rifiutata con 409 Conflict e l'attività continua a essere eseguita. I crediti per un'attività già avviata dal worker non sono rimborsabili, quindi eliminarla a metà esecuzione ti farebbe perdere sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.

Un'attività in uno stato terminale (SUCCEEDED, FAILED o CANCELED) viene eliminata senza rimborso.

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

Elenco delle attività di Unwrap UV

Restituisce un elenco paginato delle attività di Unwrap UV del chiamante, dalla più recente. Paginazione standard tramite page_num e page_size.

Richiesta

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

Trasmetti un'attività di Unwrap UV

Iscriviti al progress dell'attività come eventi inviati dal server. Ogni evento message trasporta un oggetto Attività di Unwrap UV; il flusso si chiude una volta che l'attività raggiunge SUCCEEDED, FAILED, o CANCELED.

Usa questo invece di interrogare 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 Attività di Unwrap UV

  • Name
    id
    Type
    string
    Description

    Identificatore univoco per l'attività.

  • Name
    type
    Type
    string
    Description

    Sempre uv-unwrap.

  • Name
    model_urls
    Type
    object
    Description

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

  • Name
    thumbnail_url
    Type
    string
    Description

    URL pre-firmato per un'anteprima PNG del modello bianco UV.

  • Name
    progress
    Type
    integer
    Description

    Avanzamento dell'attività, da 0 a 100.

  • Name
    status
    Type
    string
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

    Numero di attività in coda prima di questa. Presente mentre lo stato è PENDING.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp della creazione dell'attività, in millisecondi.

  • Name
    started_at
    Type
    timestamp
    Description

    Timestamp di quando è iniziato il processo, in millisecondi. 0 fino all'inizio.

  • Name
    finished_at
    Type
    timestamp
    Description

    Timestamp di completamento, in millisecondi. 0 fino al completamento.

  • 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 degli errori per le attività fallite. Vedi Errori per il riferimento completo all'oggetto task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Crediti consumati da questa attività. Restituisce 0 per le attività FAILED (i crediti vengono rimborsati in caso di fallimento). Unwrap UV addebita 5 crediti in caso di successo.

Esempio di Oggetto Attività di Unwrap UV

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