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.

Parametri

È richiesto esattamente uno tra input_task_id o model_url. Se entrambi sono forniti, 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 fare l'Unwrap UV del risultato GLB (ad esempio un risultato di Immagine in 3D, Testo in 3D o Remesh). L'attività di origine deve avere uno stato di SUCCEEDED e aver prodotto un file GLB.
Se la mesh di origine supera il limite di conteggio facce 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 un Data URI. Solo .glb è supportato — l'API legge il binario glTF e non analizza altri formati. Per fare l'Unwrap UV di un modello in un altro formato (.fbx, .obj, .stl, .gltf), converti prima in .glb tramite la Convert API, quindi passa l'ID dell'attività risultante come input_task_id o il suo URL di output GLB qui.
Per i Data URI, usa il MIME type application/octet-stream.
Lo stesso limite di 40.000 facce si applica come per input_task_id: le mesh sovradimensionate sono rifiutate con un 400 — esegui prima Remesh.

Restituisce

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

Modalità di fallimento

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante: Devono essere forniti input_task_id o model_url.
- Attività di input non valida: L'input_task_id deve riferirsi 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: Il model_url punta a un file con un'estensione non supportata.
- URL irraggiungibile: Il model_url non può essere scaricato.
Name
401 - Unauthorized
Description
Autenticazione fallita. Si prega di controllare 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 funzione non è abilitata per il tuo account. Unwrap UV è limitato 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.

Richiesta

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

Risposta

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

Eliminare un'attività di Unwrap UV

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

Richiesta

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
}