API Unwrap UV

Genera un Unwrap UV per un modello 3D esistente. Eseguilo prima di applicare la texture al modello, oppure quando uno strumento come Blender, Substance Painter o Unreal necessita di un layout UV pulito e senza sovrapposizioni.

L'output è un modello bianco UV. Ha la stessa forma dell'input, nuove coordinate UV e nessuna texture reale. Include un materiale segnaposto grigio 2×2 in modo che lo slot materiale glTF rimanga valido, e gli strumenti standard lo trattano come privo di texture.

Unwrap UV supporta mesh fino a 40.000 facce. Un modello più grande restituisce 400. Per ridurre il numero di facce, esegui prima Remesh.

Meshy triangola le mesh con quadrilateri e n-gon durante la generazione UV, quindi l'output è sempre una mesh triangolare.

POST/openapi/v1/uv-unwrap

Crea un task di Unwrap UV

Crea un task di Unwrap UV.

Il task viene eseguito in background. Per la durata tipica di un task, vedi Tempi di elaborazione.

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

Parametri

Name
input_task_id
Type
string
Obbligatorio
Description
Obbligatorio a meno che non invii model_url. L'ID di un task di Meshy API il cui output GLB vuoi sottoporre a unwrap, ad esempio un task di Immagine in 3D, Testo in 3D o Remesh. Il task deve avere stato SUCCEEDED e aver prodotto un file GLB.
La mesh può avere al massimo 40.000 facce. Una mesh con più facce restituisce 400. Per ridurre il numero di facce, esegui prima Remesh.

Name
model_url
Type
string
Obbligatorio
Description
Obbligatorio a meno che non invii input_task_id. Il modello da sottoporre a unwrap, come URL pubblico o data URI. Se invii entrambi, Meshy usa input_task_id.
Il modello deve essere un file .glb. Per sottoporre a unwrap un altro formato, convertilo prima in GLB con la Convert API.
Il file può avere al massimo 400 MB se proviene da un URL http o https, oppure 100 MB come data URI. Per un data URI, usa il MIME type application/octet-stream. Un GLB oltre i 100 MB non deve usare la compressione Draco.
Si applica lo stesso limite di 40.000 facce valido per input_task_id. Una mesh con più facce restituisce 400, quindi esegui prima Remesh.

Valori restituiti

Il campo result della risposta contiene l'ID del nuovo task di Unwrap UV.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Il messaggio di errore indica quale problema è stato rilevato. Ad esempio:
- Parametro mancante: Non è stato inviato né input_task_id né model_url.
- Task di input non valido: input_task_id non è un task API completato con successo con un risultato GLB.
- Numero di facce superato: La mesh ha più facce di quante ne permetta Unwrap UV. Esegui prima Remesh.
- Formato del modello non valido: Il file model_url ha un'estensione non supportata.
- URL non raggiungibile: Meshy non riesce a scaricare il file model_url.
- File del modello troppo grande: Il file model_url supera i 400 MB se proviene da un URL http o https, oppure supera i 100 MB come data URI.
- Troppe facce: Il file model_url supera i 100 MB e ha più di 10.000.000 di facce. Riduci il numero di facce, quindi invia nuovamente il file.
- File del modello illeggibile: Il file model_url supera i 100 MB e Meshy non riesce a leggerne l'header. Ad esempio, è un file GLB compresso con Draco.
- Header del modello troppo complesso: Il file model_url supera i 100 MB e il suo header ha troppe mesh, nodi o record da controllare. Riduci il numero di oggetti nel file, quindi invialo di nuovo.
Correggi la richiesta, quindi inviala di nuovo. Vedi Errori.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'header Authorization.
Name
402 - Payment Required
Description
Ad esempio:
- Crediti insufficienti: L'account non ha crediti sufficienti per questo task, oppure ha raggiunto un limite di credito. Un task di Unwrap UV costa 5 crediti. Controlla il tuo saldo crediti, quindi riprova.
- Piano gratuito: Creare un task richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, quindi riprova.
Name
403 - Forbidden
Description
input_task_id è un modello a bassorilievo, che questo endpoint non può sottoporre a unwrap. Il messaggio è This model type does not support this operation. Invia un modello diverso.
Name
404 - Not Found
Description
input_task_id non corrisponde a nessuno dei tuoi task. Controlla l'ID del task, quindi invia di nuovo la richiesta.
Name
429 - Too Many Requests
Description
Hai superato il limite di frequenza. Attendi, poi riprova. Vedi Limiti di frequenza.

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

Recupera un task di Unwrap UV

Restituisce lo stato attuale di un task di Unwrap UV in base al suo ID.

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

Per un esempio di risposta, consulta l'esempio di oggetto task di Unwrap UV.

Restituisce

L'oggetto task di Unwrap UV.

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

Elimina un task di Unwrap UV

Elimina permanentemente un task di Unwrap UV, inclusi i suoi output. Non puoi annullare un'eliminazione.

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

Stato del task

Eliminare un task PENDING rimborsa i crediti utilizzati al momento della sua creazione.

Un task IN_PROGRESS non può essere eliminato. La richiesta restituisce 409 Conflict, e il task continua a essere eseguito. Meshy non rimborsa un task che è già iniziato, quindi eliminarlo ti costerebbe sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminalo.

Eliminare un task in uno stato finale (SUCCEEDED, FAILED o CANCELED) non rimborsa i suoi crediti.

GET/openapi/v1/uv-unwrap

Elenco delle attività di Unwrap UV

Restituisce un elenco paginato delle tue attività di Unwrap UV, dalla più recente alla meno recente. Per scorrere l'elenco, usa 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

Stream di un task di Unwrap UV

Trasmette in streaming gli aggiornamenti di un task di Unwrap UV come Server-Sent Events (SSE). Ogni evento message contiene un oggetto task Unwrap UV. Lo stream si chiude quando il task raggiunge lo stato SUCCEEDED, FAILED o CANCELED.

Per sapere prima che il task sia terminato, utilizza questo endpoint invece di eseguire il polling di GET /openapi/v1/uv-unwrap/:id.

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 Unwrap UV

Un oggetto task Unwrap UV descrive un unwrap UV di un modello 3D. Contiene lo stato, il progress e il file del modello quando il task ha 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
}

Name
id
Type
string
Description
L'ID del task. Trattalo come una stringa opaca e non fare affidamento sul suo formato.
Name
type
Type
string
Description
Il tipo di task, sempre uv-unwrap.
Name
model_urls
Type
object
Description
URL di download firmati per il modello bianco UV. Unwrap UV restituisce sempre una singola chiave glb. Il modello mantiene la geometria di input, ha coordinate UV nuove e utilizza un materiale grigio predefinito invece di una texture.
Name
thumbnail_url
Type
string
Description
URL di download firmato per un'immagine di anteprima PNG del modello bianco UV.
Name
progress
Type
integer
Description
Quanto del task è stato completato, come percentuale da 0 a 100.
Name
status
Type
string
Description
Lo stato del task, uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
preceding_tasks
Type
integer
Description
Il numero di task che precedono questo nella coda. Presente mentre il task è PENDING.
Name
created_at
Type
timestamp
Description
Ora di creazione del task, in millisecondi Unix.
Name
started_at
Type
timestamp
Description
Ora di avvio del task, in millisecondi Unix. È 0 finché il task non inizia.
Name
finished_at
Type
timestamp
Description
Ora di completamento del task, in millisecondi Unix. È 0 finché il task non finisce.
Name
expires_at
Type
timestamp
Description
Ora di scadenza degli URL di download firmati, in millisecondi Unix.
Name
task_error
Type
object
Description
I dettagli dell'errore quando il task fallisce. Vedi Errori.
Name
consumed_credits
Type
integer
Description
Il numero di crediti utilizzati dal task. Un task Unwrap UV riuscito costa 5 crediti. È 0 per un task FAILED, perché Meshy rimborsa i crediti quando un task fallisce.