Retexture API è una funzione 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 ti consente di creare un nuovo task di Retexture. Consulta
L'oggetto Task di Retexture per vedere quali
proprietà sono incluse con l'oggetto task Retexture.
Parametri
Solo uno tra input_task_id o model_url è richiesto. Se entrambi sono forniti, input_task_id ha la priorità.
Name
input_task_id
Type
string
Obbligatorio
Description
L'ID del task completato Immagine in 3D o Testo in 3D da cui desideri eseguire il retexture.
Questo task deve essere uno dei seguenti: Anteprima Testo in 3D, Raffinazione Testo in 3D, Immagine in 3D o Remesh. Inoltre, deve avere uno stato di SUCCEEDED.
Name
model_url
Type
string
Obbligatorio
Description
Fornisci un modello 3D per cui Meshy esegua la texture. Formati supportati: .glb, .gltf, .obj, .fbx, .stl.
Ci sono due modi per fornire il modello:
URL pubblicamente accessibile: un URL accessibile da internet pubblica.
Data URI: un Data URI codificato in base64 del modello. Usa MIME type application/octet-stream. Esempio: data:application/octet-stream;base64,<tuo modello codificato in base64>.
Esattamente un input di stile è richiesto: text_style_prompt, image_style_url, o multiview_image_urls. multiview_image_urls non può essere combinato con uno degli altri due; se entrambi text_style_prompt e image_style_url sono forniti, image_style_url ha la priorità.
Name
text_style_prompt
Type
string
Obbligatorio
Description
Descrivi con il testo lo stile della texture desiderata dell'oggetto. Massimo 600 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 da internet pubblica
Data URI: un Data URI codificato in base64 dell'immagine. Esempio di Data URI: data:image/jpeg;base64,<tua immagine codificata in base64>
Il texturing delle immagini potrebbe non funzionare in modo ottimale se ci sono differenze sostanziali di geometria tra l'asset originale e l'immagine caricata.
Name
multiview_image_urls
Type
string[]
Obbligatorio
Description
Fornisci da 1 a 4 immagini che mostrino lo stesso oggetto da diverse angolazioni per guidare il texturing. La prima immagine è la vista principale (frontale); l'ordine delle viste rimanenti (sinistra, retro, destra) non importa.
Ogni elemento accetta gli stessi formati di image_style_url (un URL pubblicamente accessibile o un Data URI codificato in base64, .jpg/.jpeg/.png).
Richiede ai_model: "meshy-7" (o latest).
Name
ai_model
Type
string
predefinito latest
Description
ID del modello AI da utilizzare per il retexturing. Valori disponibili: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
predefinito false
Description
Mantieni il layout UV esistente del modello invece di generarne uno nuovo.
Se stai ritexturizzando un modello generato da Meshy (tramite input_task_id, o un model_url che punta a un output di Meshy), imposta questo parametro su true per riutilizzare il suo layout UV ottimizzato.
Se stai ritexturizzando un modello di terze parti che hai caricato, imposta true quando ha già dei buoni UV che desideri mantenere, o lascia false per permettere a Meshy di srotolare nuovi UV (meglio per modelli che mancano di una corretta mappatura UV).
Name
enable_pbr
Type
boolean
predefinito false
Description
Genera mappe PBR (metallico, roughness, normale) in aggiunta al colore di base. Una mappa di emissione è inclusa quando ai_model è meshy-6, tranne che con texture_resolution: 8k. meshy-7 e latest non producono una mappa di emissione.
Name
texture_resolution
Type
string
predefinito 2k
Description
Risoluzione della texture del colore di base. Una tra 2k (2048×2048), 4k (4096×4096), o 8k (8192×8192). Le risoluzioni più elevate catturano più dettagli di superficie.
4k e 8k richiedono ai_modelmeshy-6, meshy-7 o latest. A 8k, nessuna mappa di emissione viene prodotta.
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 i riflessi e le ombre dalla texture del colore di base, producendo un risultato più pulito che funziona meglio con impostazioni 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. Solo i formati richiesti verranno generati e restituiti, il che può ridurre il tempo di completamento del task. Quando omessi, tutti i formati supportati sono inclusi.
Valori disponibili: glb, obj, fbx, stl, usdz, 3mf
Quando omessi, tutti i formati eccetto 3mf sono generati. 3mf è incluso solo quando specificato esplicitamente.
Name
alpha_thumbnail
Type
boolean
predefinito false
Description
Quando impostato su true, il task rende inoltre una versione del preview con sfondo trasparente (RGBA) e la restituisce come alpha_thumbnail_url nella risposta GET. Il campo thumbnail_url esistente rimane invariato.
Restituisce
La proprietà result della risposta contiene l'id del task appena creato per il Retexture.
Modalità di Fallimento
Name
400 - Bad Request
Description
La richiesta non è accettabile. Cause comuni:
Mancanza del parametro: Devono essere forniti model_url o input_task_id.
Mancanza di stile: Devono essere forniti 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 ai_model: "meshy-7" (o latest).
Modello non disponibile: ai_model: "meshy-7" è in fase di distribuzione progressiva e non è ancora abilitato per il tuo account.
Task di input non valido: input_task_id deve fare riferimento a un task di successo da un modello supportato.
Formato modello non valido: model_url punta a un file con un'estensione non supportata.
URL irraggiungibile: model_url, image_style_url o un elemento di multiview_image_urls non può essere scaricato.
Name
401 - Unauthorized
Description
L'autenticazione è fallita. Si prega di controllare la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questo task.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.
Richiesta
POST
/openapi/v1/retexture
# Retexture con prompt testualecurlhttps://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 con stile immagine e 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 consente di recuperare un task di Retexture dato un id del task valido.
Consulta L'oggetto Task di Retexture per vedere quali
proprietà sono incluse con l'oggetto task Retexture.
Parametri
Name
id
Type
path
Description
Identificativo univoco per il task di Retexture da recuperare.
{"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 }]
// Esempio di evento di erroreevent: errordata: {"status_code": 404,"message": "Task non trovato"}// Esempi di eventi messaggio che illustrano il progresso del task.// Per task PENDING o IN_PROGRESS, il flusso di risposta non includerà tutti i campi.event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","progress": 0,"status": "PENDING"}event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","progress": 50,"status": "IN_PROGRESS"}event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","type": "retexture","progress": 100,"status": "SUCCEEDED","created_at": 1692771650657,"started_at": 1692771667037,"finished_at": 1692771669037,"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=***" },"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 testuali o di immagine.
Il modello ha le seguenti proprietà:
Proprietà
Name
id
Type
string
Description
Identificativo univoco per il task. Mentre utilizziamo un UUID k-sortable per gli ID dei task come dettaglio di implementazione, non dovresti fare alcuna assunzione sul formato dell'ID.
Name
type
Type
string
Description
Tipo del task di Retexture. Il valore è retexture.
Name
model_urls
Type
object
Description
URL scaricabile del file 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 agli export in formato OBJ quando presenti delle texture.
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 testuale che è stato utilizzato per creare il task di texturing.
Name
image_style_url
Type
string
Description
Questo è l'input dell'immagine che è stato utilizzato per creare il task di texturing.
Name
multiview_image_urls
Type
string[]
Description
URL scaricabili delle immagini di riferimento multivista che sono state utilizzate per creare il task di texturing. 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 resa 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, questo 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 in Meshy API.
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 tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Un array di oggetti URL delle texture che sono generati dal task. Normalmente questo contiene solo un oggetto URL della texture. Ogni URL della texture ha le seguenti proprietà:
Name
base_color
Type
string
Description
URL scaricabile dell'immagine della mappa del colore di 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 roughness.
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 non riusciti. Vedi Errori per il riferimento completo dell'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 sono rimborsati in caso di errore).
Esempio di Modello 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}