Retexture API è una funzionalità che ti consente di integrare le capacità di retexturing AI di Meshy nella tua applicazione. In questa sezione, troverai tutte le informazioni
necessarie per iniziare a utilizzare questa API.
Questo endpoint consente di creare un nuovo task di Retexture. Fai riferimento a
The Retexture Task Object per vedere quali
proprietà sono incluse nell'oggetto task Retexture.
Parametri
È richiesto solo 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 del task Immagine in 3D o Testo in 3D completato che desideri sottoporre a retexture.
Questo task deve essere uno dei seguenti: Text to 3D Preview, Text to 3D Refine, Image to 3D o Remesh. Inoltre, deve avere uno stato SUCCEEDED.
Name
model_url
Type
string
Obbligatorio
Description
Fornisci un modello 3D che Meshy possa texturizzare. Formati supportati: .glb, .gltf, .obj, .fbx, .stl.
Ci sono due modi per fornire il modello:
URL pubblicamente accessibile: un URL accessibile dalla rete internet pubblica.
Data URI: un Data URI del modello codificato in base64. Usa il MIME type application/octet-stream. Esempio: data:application/octet-stream;base64,<i tuoi dati del modello codificati in base64>.
È richiesto esattamente un input di stile: text_style_prompt, image_style_url, oppure multiview_image_urls. multiview_image_urls non può essere combinato con nessuno degli altri due; se vengono forniti sia text_style_prompt sia image_style_url, image_style_url ha la priorità.
Name
text_style_prompt
Type
string
Obbligatorio
Description
Descrivi lo stile di texture desiderato per l'oggetto usando del testo. Massimo 800 caratteri.
Name
image_style_url
Type
string
Obbligatorio
Description
Fornisci un'immagine 2D per guidare il processo di texturing. Attualmente supportiamo i formati .jpg, .jpeg e .png.
Ci sono due modi per fornire l'immagine:
URL pubblicamente accessibile: un URL accessibile dalla rete internet pubblica
Data URI: un Data URI dell'immagine codificato in base64. Esempio di Data URI: data:image/jpeg;base64,<i tuoi dati dell'immagine codificati in base64>
Il texturing basato su immagine potrebbe non funzionare in modo ottimale se ci sono differenze geometriche sostanziali tra l'asset originale e l'immagine caricata.
Name
multiview_image_urls
Type
string[]
Obbligatorio
Description
Fornisci da 1 a 4 immagini che mostrano lo stesso oggetto da viste diverse per guidare il texturing. La prima immagine è la vista primaria (frontale); l'ordine delle viste rimanenti (sinistra, retro, destra) non ha importanza.
Ogni elemento accetta gli stessi formati di image_style_url (un URL pubblicamente accessibile o un Data URI base64, .jpg/.jpeg/.png).
Richiede un ai_model: "meshy-7" esplicito.
Name
ai_model
Type
string
predefinito latest
Description
ID del modello IA da usare per il retexture. Valori disponibili: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
predefinito false
Description
Mantiene il layout UV esistente del modello invece di generarne uno nuovo.
Se stai eseguendo il retexture di un modello generato da Meshy (tramite input_task_id, o un model_url che punta a un output di Meshy), imposta questo valore su true per riutilizzare il suo layout UV ottimizzato.
Se stai eseguendo il retexture di un modello di terze parti che hai caricato, imposta true quando ha già delle buone UV che vuoi mantenere, oppure lascialo false per lasciare che Meshy generi nuove UV (opzione migliore per modelli privi di una corretta mappatura UV).
Name
enable_pbr
Type
boolean
predefinito false
Description
Genera mappe PBR (metallic, roughness, normal) oltre al colore di base. Una emission map è inclusa anche quando ai_model è meshy-6, tranne a texture_resolution: 8k. meshy-7 e latest non producono una emission map.
Name
texture_resolution
Type
string
predefinito 2k
Description
Risoluzione della texture del colore di base. Uno tra 2k (2048×2048), 4k (4096×4096) o 8k (8192×8192). Risoluzioni più elevate catturano maggiori dettagli superficiali.
4k e 8k richiedono ai_modelmeshy-6, meshy-7 o latest. A 8k, non viene prodotta alcuna emission map.
Name
hd_texture
Type
boolean
⚠ deprecato
predefinito false
Description
Usa texture_resolution al suo posto — equivalente a texture_resolution: "4k". Quando entrambi sono impostati, texture_resolution ha la precedenza.
Name
remove_lighting
Type
boolean
predefinito true
Description
Rimuove le luci e le ombre dalla texture del colore di base, producendo un risultato più pulito che funziona meglio con configurazioni di illuminazione personalizzate.
Supportato solo quando ai_model è meshy-6.
Name
target_formats
Type
string[]
Description
Specifica quali formati di file 3D includere nell'output. Verranno generati e restituiti solo i formati richiesti, il che può ridurre i tempi di completamento del task. Se omesso, sono inclusi tutti i formati supportati.
Valori disponibili: glb, obj, fbx, stl, usdz, 3mf
Se omesso, vengono generati tutti i formati tranne 3mf. 3mf viene incluso solo se specificato esplicitamente.
Name
alpha_thumbnail
Type
boolean
predefinito false
Description
Quando impostato su true, il task esegue inoltre il rendering di una versione con sfondo trasparente (RGBA) dell'anteprima e la restituisce come alpha_thumbnail_url nella risposta GET. Il campo thumbnail_url esistente rimane invariato.
Valori restituiti
La proprietà result della risposta contiene l'id del task del task di Retexture appena creato.
Modalità di fallimento
Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
Parametro mancante: deve essere fornito model_url oppure input_task_id.
Stile mancante: deve essere fornito uno tra text_style_prompt, image_style_url o multiview_image_urls.
Input di stile in conflitto: multiview_image_urls non può essere combinato con text_style_prompt o image_style_url.
Modello non supportato per multi-vista: multiview_image_urls richiede un ai_model: "meshy-7" esplicito.
Modello non disponibile: ai_model: "meshy-7" è in fase di rilascio progressivo e non è ancora abilitato per il tuo account.
Task di input non valido: input_task_id deve fare riferimento a un task completato con successo di un modello supportato.
Formato del modello non valido: model_url punta a un file con un'estensione non supportata.
URL non raggiungibile: non è stato possibile scaricare model_url, image_style_url o un elemento di multiview_image_urls.
Name
401 - Unauthorized
Description
Autenticazione fallita. Controlla la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questo task.
Name
429 - Too Many Requests
Description
Hai superato il limite di frequenza.
Request
POST
/openapi/v1/retexture
# Retexture with text promptcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "text_style_prompt": "red fangs, Samurai outfit that fused with japanese batik style", "enable_original_uv": true, "enable_pbr": true }'# Retexture with image style and PBRcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg", "ai_model": "latest", "enable_pbr": true, "enable_original_uv": true }'
Questo endpoint ti permette di recuperare un task di Retexture dato un id valido del task.
Consulta L'oggetto Task di Retexture per vedere quali
proprietà sono incluse con l'oggetto task di Retexture.
Parametri
Name
id
Type
path
Description
Identificatore univoco per il task di Retexture da recuperare.
Restituisce
La risposta contiene l'oggetto task di Retexture. Controlla
la sezione L'oggetto Task di Retexture per i dettagli.
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","obj":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***","mtl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***","stl":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","texture_image_url":"","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"task_error": {"message":"" },"consumed_credits":10}
[ {"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10 }]
L'oggetto Task di Retexture è un'unità di lavoro che Meshy utilizza per generare una texture 3D da input di testo o immagine.
Il modello ha le seguenti proprietà:
Proprietà
Name
id
Type
string
Description
Identificatore univoco per il task. Anche se utilizziamo un UUID k-sortable per gli id dei task come dettaglio di implementazione, non dovresti fare alcuna supposizione sul formato dell'id.
Name
type
Type
string
Description
Tipo di task di Retexture. Il valore è retexture.
Name
model_urls
Type
object
Description
URL scaricabile del file del modello 3D texturizzato generato da Meshy.
Name
glb
Type
string
Description
URL scaricabile del file GLB.
Name
fbx
Type
string
Description
URL scaricabile del file FBX.
Name
obj
Type
string
Description
URL scaricabile del file OBJ.
Name
usdz
Type
string
Description
URL scaricabile del file USDZ.
Name
mtl
Type
string
Description
URL scaricabile del file MTL, restituito insieme alle esportazioni OBJ quando le texture sono presenti.
Name
stl
Type
string
Description
URL scaricabile del file STL.
Name
3mf
Type
string
Description
URL scaricabile del file 3MF. Presente solo quando 3mf è stato richiesto tramite target_formats.
Name
text_style_prompt
Type
string
Description
Questo è il prompt di testo che è stato utilizzato per creare il task di texturizzazione.
Name
image_style_url
Type
string
Description
Questo è l'input immagine che è stato utilizzato per creare il task di texturizzazione.
Name
multiview_image_urls
Type
string[]
Description
URL scaricabili delle immagini di riferimento multi-vista che sono state utilizzate per creare il task di texturizzazione. Presente solo quando il task è stato creato con multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL scaricabile dell'immagine miniatura del file del modello.
Name
alpha_thumbnail_url
Type
string
Description
URL scaricabile di una versione con sfondo trasparente (RGBA) di thumbnail_url. Presente solo quando il task è stato creato con alpha_thumbnail: true e l'anteprima trasparente è stata renderizzata con successo; altrimenti questo campo è omesso.
Name
progress
Type
integer
Description
Progresso del task. Se il task non è ancora iniziato, questa proprietà sarà 0. Una volta che il task è riuscito, diventerà 100.
Name
started_at
Type
timestamp
Description
Timestamp di quando il task è stato avviato, in millisecondi. Se il task non è ancora iniziato, questa proprietà sarà 0.
Un timestamp rappresenta il numero di millisecondi trascorsi dal 1 gennaio 1970 UTC, seguendo
lo standard RFC 3339.
Ad esempio, venerdì 1 settembre 2023 12:00:00 PM GMT è rappresentato come 1693569600000. Questo si applica
a tutti i timestamp nell'API di Meshy.
Name
created_at
Type
timestamp
Description
Timestamp di quando il task è stato creato, in millisecondi.
Name
expires_at
Type
timestamp
Description
Timestamp di quando il risultato del task scade, in millisecondi.
Name
finished_at
Type
timestamp
Description
Timestamp di quando il task è stato completato, in millisecondi. Se il task non è ancora completato, questa proprietà sarà 0.
Name
status
Type
string
Description
Stato del task. I valori possibili sono uno di PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Un array di oggetti URL di texture che sono generati dal task. Normalmente questo contiene solo un oggetto URL di texture. Ogni URL di texture ha le seguenti proprietà:
Name
base_color
Type
string
Description
URL scaricabile dell'immagine della mappa del colore base.
Name
metallic
Type
string
Description
URL scaricabile dell'immagine della mappa metallica.
Se il task è creato con enable_pbr: false, questa proprietà sarà omessa.
Name
normal
Type
string
Description
URL scaricabile dell'immagine della normal map.
Se il task è creato con enable_pbr: false, questa proprietà sarà omessa.
Name
roughness
Type
string
Description
URL scaricabile dell'immagine della mappa di rugosità.
Se il task è creato con enable_pbr: false, questa proprietà sarà omessa.
Name
emission
Type
string
Description
URL scaricabile dell'immagine della mappa di emissione.
Se il task è creato con enable_pbr: false, o ai_model è meshy-5, questa proprietà sarà omessa.
Name
preceding_tasks
Type
integer
Description
Il conteggio dei task precedenti.
Questa proprietà è presente solo quando lo stato del task è PENDING.
Name
task_error
Type
object
Description
Dettagli degli errori per i task falliti. Vedi Errori per il riferimento completo all'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questo task. Presente quando lo stato del task è PENDING, IN_PROGRESS, o SUCCEEDED. Restituisce 0 per i task FAILED (i crediti vengono rimborsati in caso di fallimento).
Esempio di Modello di Task di Retexture
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","model_urls": {"glb":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***","fbx":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***","usdz":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***" },"text_style_prompt":"red fangs, Samurai outfit that fused with japanese batik style","image_style_url":"https://assets.meshy.ai/***/image/example_image.jpg?Expires=***","thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","progress":100,"started_at":1692771667037,"created_at":1692771650657,"expires_at":1692771679037,"finished_at":1692771669037,"status":"SUCCEEDED","texture_urls": [ {"base_color":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***","metallic":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX","normal":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX","roughness":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX","emission":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX" } ],"preceding_tasks":0,"task_error": {"message":"" },"consumed_credits":10}