API Retexture

Retexture API è una funzionalità che ti consente di integrare le capacità di Retexture basate sull'AI di Meshy nella tua applicazione. In questa sezione troverai tutte le informazioni necessarie per iniziare a usare questa API.

POST/openapi/v1/retexture

Crea un task Retexture

Questo endpoint consente di creare un nuovo task Retexture. Consulta L'oggetto task Retexture 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 rielaborare con Retexture. Questo task deve essere uno dei seguenti: Anteprima Testo in 3D, Perfezionamento Testo in 3D, Immagine in 3D o Remesh. Inoltre, deve avere lo stato SUCCEEDED.

Name
model_url
Type
string
Obbligatorio
Description
Fornisci un modello 3D da far texturizzare a Meshy. Formati supportati: .glb, .gltf, .obj, .fbx, .stl.
Esistono due modi per fornire il modello:
- URL accessibile pubblicamente: un URL accessibile da Internet pubblico.
- Data URI: un Data URI del modello codificato in base64. Usa il MIME type application/octet-stream. Esempio: data:application/octet-stream;base64,<your base64-encoded model data>.

È richiesto solo uno tra text_style_prompt o image_style_url. Se vengono forniti entrambi, image_style_url ha la priorità.

Name
text_style_prompt
Type
string
Obbligatorio
Description
Descrivi tramite testo lo stile di texture desiderato 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.
Esistono due modi per fornire l'immagine:
- URL accessibile pubblicamente: un URL accessibile da Internet pubblico
- Data URI: un Data URI dell'immagine codificato in base64. Esempio di Data URI: data:image/jpeg;base64,<your base64-encoded image data>
Il texturing da immagine potrebbe non funzionare in modo ottimale se ci sono differenze sostanziali di geometria tra l'asset originale e l'immagine caricata.

Name
ai_model
Type
string
predefinito latest
Description
ID del modello IA da usare per il retexturing. Valori disponibili: meshy-5, meshy-6, latest (Meshy 6).
Name
enable_original_uv
Type
boolean
predefinito false
Description
Mantiene il layout UV esistente del modello invece di generarne uno nuovo.
- Se stai rielaborando con Retexture un modello generato da Meshy (tramite input_task_id o un model_url che punta a un output di Meshy), impostalo su true per riutilizzare il suo layout UV ottimizzato.
- Se stai rielaborando con Retexture un modello di terze parti che hai caricato, imposta true quando dispone già di buone UV che desideri mantenere, oppure lascialo false per consentire a Meshy di creare nuove UV (ideale 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 base. È inclusa anche una mappa di emissione quando ai_model è meshy-6 o latest.
Name
hd_texture
Type
boolean
predefinito false
Description
Genera la texture del colore base a risoluzione 4K (4096×4096) per un dettaglio maggiore.
Supportato solo quando ai_model è meshy-6 o latest. Le mappe PBR sono sempre generate a 2K.
Name
remove_lighting
Type
boolean
predefinito true
Description
Rimuove riflessi e ombre dalla texture del colore base, producendo un risultato più pulito che funziona meglio con configurazioni di illuminazione personalizzate.
Supportato solo quando ai_model è meshy-6 o latest.
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 il tempo di completamento del task. Se omesso, vengono inclusi tutti i formati supportati.
Valori disponibili: glb, obj, fbx, stl, usdz, 3mf
Se omesso, vengono generati tutti i formati eccetto 3mf. 3mf è incluso solo quando specificato esplicitamente.
Name
alpha_thumbnail
Type
boolean
predefinito false
Description
Quando impostato su true, il task renderizza inoltre 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.

Restituisce

La proprietà result della risposta contiene l'id del task Retexture appena creato.

Modalità di errore

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 text_style_prompt oppure image_style_url.
- Task di input non valido: input_task_id deve fare riferimento a un task completato con successo da 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 o image_style_url.
Name
401 - Unauthorized
Description
Autenticazione non riuscita. 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 tuo limite di frequenza.

Request

POST

/openapi/v1/retexture

# Retexture with text prompt
curl https://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 PBR
curl https://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
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

GET/openapi/v1/retexture/:id

Recupera un'attività Retexture

Questo endpoint consente di recuperare un'attività Retexture dato un id valido. Fai riferimento a L'oggetto attività Retexture per vedere quali proprietà sono incluse nell'oggetto attività Retexture.

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività Retexture da recuperare.

Restituisce

La risposta contiene l'oggetto attività Retexture. Consulta la sezione L'oggetto attività Retexture per i dettagli.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

DELETE/openapi/v1/retexture/:id

Elimina un'attività Retexture

Questo endpoint elimina in modo permanente un'attività Retexture, inclusi tutti i modelli e i dati associati. Questa azione è irreversibile.

Parametri del percorso

Name
id
Type
path
Description
L'ID dell'attività Retexture da eliminare.

Restituisce

Restituisce 200 OK in caso di successo.

Request

DELETE

/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.

GET/openapi/v1/retexture

Elenca attività Retexture

Questo endpoint consente di recuperare un elenco di attività Retexture.

Parametri

Name
page_num
Type
integer
predefinito 1
Description
Numero di pagina per la paginazione.
Name
page_size
Type
integer
predefinito 10
Description
Limite della dimensione della pagina. Il massimo consentito è 50 elementi.
Name
sort_by
Type
string
Description
Campo in base al quale ordinare.
Valori disponibili:
- +created_at: Ordina per ora di creazione in ordine crescente.
- -created_at: Ordina per ora di creazione in ordine decrescente.

Restituisce

Restituisce un elenco paginato degli oggetti attività Retexture.

Request

GET

/openapi/v1/retexture

curl https://api.meshy.ai/openapi/v1/retexture?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

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

GET/openapi/v1/retexture/:id/stream

Esegui lo stream di un'attività Retexture

Questo endpoint trasmette aggiornamenti in tempo reale per un'attività Retexture utilizzando Server-Sent Events (SSE).

Parametri

Name
id
Type
path
Description
Identificatore univoco dell'attività Retexture di cui eseguire lo stream.

Restituisce

Restituisce uno stream di oggetti attività Retexture come Server-Sent Events.

Per le attività PENDING o IN_PROGRESS, lo stream di risposta includerà solo i campi progress e status necessari.

Request

GET

/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
  "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 Retexture

L'oggetto Task Retexture è un'unità di lavoro che Meshy utilizza per generare una texture 3D da input testuali o da immagini. Il modello ha le seguenti proprietà:

Proprietà

Name
id
Type
string
Description
Identificatore univoco dell'attività. Sebbene usiamo un UUID k-sortable per gli ID delle attività come dettaglio di implementazione, non dovresti fare alcuna supposizione sul formato dell'id.
Name
type
Type
string
Description
Tipo dell'attività 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 sono presenti 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 di testo utilizzato per creare l'attività di texturing.
Name
image_style_url
Type
string
Description
Questo è l'input immagine utilizzato per creare l'attività di texturing.
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 l'attività è stata creata con alpha_thumbnail: true e l'anteprima trasparente è stata renderizzata correttamente; in caso contrario questo campo viene omesso.
Name
progress
Type
integer
Description
Progress dell'attività. Se l'attività non è ancora avviata, questa proprietà sarà 0. Una volta che l'attività è riuscita, diventerà 100.
Name
started_at
Type
timestamp
Description
Timestamp di quando l'attività è stata avviata, in millisecondi. Se l'attività non è ancora avviata, 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 l'attività è stata creata, in millisecondi.
Name
expires_at
Type
timestamp
Description
Timestamp di quando il risultato dell'attività scade, in millisecondi.
Name
finished_at
Type
timestamp
Description
Timestamp di quando l'attività è stata completata, in millisecondi. Se l'attività non è ancora completata, questa proprietà sarà 0.
Name
status
Type
string
Description
Stato dell'attività. I valori possibili sono uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Un array di oggetti URL di texture generati dall'attività. Normalmente 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 metallic.
  Se l'attività viene creata con enable_pbr: false, questa proprietà verrà omessa.
- Name
  normal
  Type
  string
  Description
  URL scaricabile dell'immagine normal map.
  Se l'attività viene creata con enable_pbr: false, questa proprietà verrà omessa.
- Name
  roughness
  Type
  string
  Description
  URL scaricabile dell'immagine della mappa roughness.
  Se l'attività viene creata con enable_pbr: false, questa proprietà verrà omessa.
- Name
  emission
  Type
  string
  Description
  URL scaricabile dell'immagine della mappa emission.
  Se l'attività viene creata con enable_pbr: false, oppure ai_model è meshy-5, questa proprietà verrà omessa.
Name
preceding_tasks
Type
integer
Description
Il numero di attività precedenti.
Questa proprietà è presente solo quando lo stato dell'attività è PENDING.
Name
task_error
Type
object
Description
Dettagli dell'errore per le attività non riuscite. Consulta Errori per il riferimento completo all'oggetto task_error.
Name
consumed_credits
Type
integer
Description
Il numero di crediti consumati da questa attività. Presente quando lo stato dell'attività è PENDING, IN_PROGRESS o SUCCEEDED. Restituisce 0 per le attività FAILED (i crediti vengono rimborsati in caso di errore).

Example Retexture Task Model

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