Image to 3D API

Image to 3D API è una funzionalità che ti consente di integrare le capacità di Immagine in 3D di Meshy nella tua applicazione. In questa sezione troverai tutte le informazioni necessarie per iniziare a utilizzare questa API.

POST/openapi/v1/image-to-3d

Crea un'attività di Immagine in 3D

Questo endpoint ti consente di creare una nuova attività di Immagine in 3D. Consulta L'oggetto Attività Immagine in 3D per vedere quali proprietà sono incluse nell'oggetto attività Immagine in 3D.

Parametri

Solo uno di input_task_id o image_url è obbligatorio. Se entrambi sono forniti, input_task_id ha la priorità.

Name
input_task_id
Type
string
Obbligatorio
Description
L'ID di un'attività di generazione immagine completata il cui output deve essere utilizzato come immagine di input. Questa attività deve essere una delle seguenti: Testo in Immagine o Immagine in Immagine. Inoltre, deve essere stata eseguita tramite l'API, avere uno stato di SUCCEEDED e produrre esattamente un'immagine.

Name
image_url
Type
string
Obbligatorio
Description
Fornisce un'immagine da utilizzare per Meshy nella creazione del modello. Attualmente supportiamo i formati .jpg, .jpeg, e .png.
Ci sono due modi per fornire l'immagine:
- URL accessibile pubblicamente: Un URL accessibile da Internet pubblico.
- Data URI: Un Data URI codificato in base64 dell'immagine. Esempio di un Data URI: data:image/jpeg;base64,<i tuoi dati dell'immagine codificati in base64>.

Name
model_type
Type
string
predefinito standard
Description
Specifica il tipo di generazione della mesh 3D.
Valori disponibili:
- standard: Generazione di una mesh 3D di dettaglio regolare.
- smart-topology: Scegli un modello Smart Topology con ai_model (meshy-t1 o meshy-t2).
- lowpoly (deprecato): Genera una mesh low-poly ottimizzata per poligoni più puliti. Si raccomanda di utilizzare smart-topology.
Quando viene selezionato smart-topology, topology, should_remesh, e save_pre_remeshed_model vengono ignorati.
Quando viene selezionato lowpoly, ai_model, topology, target_polycount, should_remesh, e save_pre_remeshed_model vengono ignorati.
Name
ai_model
Type
string
predefinito latest
Description
ID del modello da utilizzare. I valori disponibili dipendono da model_type.
Generazione standard (model_type: standard):
- meshy-5, meshy-6, meshy-7, ultimo (Meshy 7)
Generazione Smart Topology (model_type: smart-topology):
- meshy-t2 (predefinito, consigliato): il modello Smart Topology — topology più pulita, parti nativamente separate, output triangolare e un conteggio facciale che puoi impostare con target_polycount.
- meshy-t1: il vecchio modello low-poly; non supporta il settaggio di un conteggio facciale con target_polycount.
Name
ultra_mode
Type
boolean
predefinito false
Description
Abilita la generazione Ultra per una geometria ad alta fedeltà con dettagli di superficie più fini.
Supportato solo quando ai_model è meshy-7 (o ultimo).
Name
should_texture
Type
boolean
predefinito true
Description
Determina se le texture vengono generate. Impostandolo su false salta la fase di texturizzazione, fornendo una mesh senza texture.

Si applica solo quando should_texture = true

Name
enable_pbr
Type
boolean
predefinito false
Description
Genera Mappe PBR (metallico, rugosità, normale) oltre al colore base. Una mappa di emissione è anche inclusa quando ai_model è meshy-6, tranne che a texture_resolution: 8k. meshy-7 e ultimo non producono una mappa di emissione.
Name
texture_resolution
Type
string
predefinito 2k
Description
Risoluzione texture colore base. Una di 2k (2048×2048), 4k (4096×4096), o 8k (8192×8192). Risoluzioni più alte catturano più dettagli di superficie.
4k e 8k non sono disponibili con ai_model: meshy-5. A 8k, nessuna mappa di emissione è prodotta.
Name
hd_texture
Type
boolean
⚠ deprecato
predefinito false
Description
Utilizza texture_resolution invece — equivalente a texture_resolution: "4k". Quando entrambi sono impostati, texture_resolution ha la precedenza.
Name
texture_prompt
Type
string
Description
Fornisce un prompt di testo per guidare il processo di texturizzazione. Massimo 600 caratteri.
Name
texture_image_url
Type
string
Description
Fornisce un'immagine 2D per guidare il processo di texturizzazione. Attualmente supportiamo i formati .jpg, .jpeg, e .png.
Ci sono due modi per fornire l'immagine:
- URL accessibile pubblicamente: Un URL accessibile da Internet pubblico
- Data URI: Un Data URI codificato in base64 dell'immagine. Esempio di un Data URI: data:image/jpeg;base64,<i tuoi dati dell'immagine codificati in base64>
La texturizzazione delle immagini potrebbe non funzionare in modo ottimale se ci sono differenze sostanziali di geometria tra l'asset originale e l'immagine caricata. Solo uno di texture_image_url o texture_prompt può essere utilizzato per guidare il processo di texturizzazione. Se entrambi i parametri sono forniti, allora texture_prompt è utilizzato per texturizzare il modello per impostazione predefinita. La texturizzazione tramite testo o immagine costerà 10 crediti per attività.

Name
should_remesh
Type
boolean
predefinito false (meshy-6, meshy-7), true (others)
Description
Controlla se abilitare la fase di remesh. Per il modello di massima qualità, consigliamo di impostare should_remesh su false.

Si applica solo quando should_remesh = true

Name
topology
Type
string
predefinito triangle
Description
Specifica la topology del modello generato.
Valori disponibili:
- quad: Genera una mesh a predominanza di quad.
- triangle: Genera una mesh triangolare decimata.
Name
decimation_mode
Type
integer
Description
Abilita la decimazione adattiva impostando un livello di conteggio poligonale. Quando impostato, target_polycount viene ignorato.
Valori disponibili:
- 1: Adattivo — conteggio ultra poligonale.
- 2: Adattivo — conteggio poligonale alto.
- 3: Adattivo — conteggio poligonale medio.
- 4: Adattivo — conteggio poligonale basso.
Name
save_pre_remeshed_model
Type
boolean
predefinito false
Description
Quando impostato su true, Meshy memorizza anche un file GLB extra prima che la fase di remesh sia completata.

Name
target_polycount
Type
integer
Description
Numero di poligoni di destinazione (facce) nel risultato. Il conteggio effettivo può discostarsi dal target a seconda della geometria.
target_polycount ha effetto in due casi indipendenti:
- Remesh — con should_remesh: true su un modello standard. La mesh è remeshed (decimata) approssimativamente a questo conteggio. Gamma da 100 a 300.000, predefinita 30.000. Se decimation_mode è impostato, ha la priorità e target_polycount è ignorato.
- Smart Topology — con model_type: smart-topology e ai_model: meshy-t2. Il modello è generato direttamente a questo conteggio facciale; nessuna remesh viene eseguita dopodiché should_remesh non è richiesto. Gamma da 100 a 15.000, predefinita 4.000.

Name
symmetry_mode
Type
string
⚠ deprecato
predefinito auto
Description
Deprecato. Questo parametro non influisce più sull'output.
Il campo symmetry_mode controlla il comportamento della simmetria durante il processo di generazione del modello.
I valori validi sono:
- off: Disabilita la simmetria.
- auto: Determina automaticamente e applica simmetria in base alla geometria di input.
- on: Impone la simmetria durante la generazione.
Name
pose_mode
Type
string
predefinito ""
Description
Specifica la modalità di posa per il modello generato.
Valori disponibili:
- a-pose: Genera il modello in una posa A.
- t-pose: Genera il modello in una posa T.
- "" (stringa vuota): Nessuna posa specifica applicata.
Name
is_a_t_pose
Type
boolean
⚠ deprecato
predefinito false
Description
Utilizza pose_mode invece. Se generare il modello in una posa A/T.
Name
image_enhancement
Type
boolean
predefinito true
Description
Ottimizza l'immagine di input per risultati migliori. Impostare su false per preservare l'aspetto esatto dell'immagine di input senza alcun tipo di elaborazione dello stile.
Supportato solo quando ai_model è meshy-6, meshy-7, o ultimo.
Name
remove_lighting
Type
boolean
predefinito true
Description
Rimuove luci e ombre dalla texture del colore di base, producendo un risultato più pulito che funziona meglio sotto configurazioni di illuminazione personalizzate.
Supportato solo quando ai_model è meshy-6.
Name
moderation
Type
boolean
predefinito false
Description
Quando impostato su true, il contenuto di input verrà automaticamente analizzato per rilevare contenuti potenzialmente dannosi. Se vengono rilevati contenuti dannosi, l'attività non procederà alla generazione.
Il contenuto degli input image_url, texture_image_url, e texture_prompt verrà analizzato.
Name
target_formats
Type
string[]
Description
Specifica quali formati di file 3D includere nell'output. Solo i formati richiesti saranno generati e restituiti, il che può ridurre il tempo di completamento dell'attività. Quando omesso, tutti i formati supportati sono inclusi.
Valori disponibili: glb, obj, fbx, stl, usdz, 3mf
Quando omesso, tutti i formati tranne 3mf sono generati. 3mf è incluso solo quando specificato esplicitamente.
Name
auto_size
Type
boolean
predefinito false
Description
Quando impostato su true, il servizio utilizza la visione artificiale per stimare automaticamente l'altezza reale dell'oggetto e ridimensionare il modello di conseguenza. L'origine predefinita sarà bottom a meno che origin_at non sia impostato in modo esplicito.
Name
alpha_thumbnail
Type
boolean
predefinito false
Description
Quando impostato su true, l'attività rende inoltre una versione con sfondo trasparente (RGBA) dell'anteprima e la restituisce come alpha_thumbnail_url nella risposta GET. Il campo thumbnail_url esistente è invariato.
Name
multi_view_thumbnails
Type
boolean
predefinito false
Description
Quando impostato su true, l'attività rende inoltre quattro miniature delle viste cardinali (frontale, destra, posteriore, sinistra) e le restituisce sotto thumbnail_urls nella risposta GET. Il campo esistente thumbnail_url è invariato e continua a puntare alla vista frontale, quindi i clienti esistenti non sono influenzati.
Aggiunge circa 3 secondi alla latenza dell'attività.

Si applica solo quando auto_size = true

Name
origin_at
Type
string
predefinito bottom
Description
Posizione dell'origine quando auto_size è abilitato.
Valori disponibili: bottom, center.

Ritorni

La proprietà result della risposta contiene l'id dell'attività Immagine in 3D appena creata.

Modalità di fallimento

Name
400 - Bad Request
Description
La richiesta non è stata accettabile. Cause comuni:
- Parametro mancante: Devono essere forniti image_url o input_task_id.
- Compito di input non valido: L'input_task_id deve fare riferimento a un'attività Testo in Immagine o Immagine in Immagine SUCCEEDED che produce esattamente un'immagine.
- Formato immagine non valido: L'image_url fornito non è un formato supportato (.jpg, .jpeg, .png).
- URL non raggiungibile: L'image_url non può essere scaricato (404 o timeout).
- Data URI non valido: La stringa base64 è malformata.
- Combinazione di parametri non valida: enable_pbr è supportato solo quando should_texture è true.
Name
401 - Unauthorized
Description
Autenticazione fallita. Per favore controlla la tua chiave API.
Name
402 - Payment Required
Description
Crediti insufficienti per eseguire questa attività.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza.

Request

POST

/openapi/v1/image-to-3d

# Richiesta semplice con parametri richiesti
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<il tuo URL immagine pubblicamente accessibile o URI dati codificato in base64>"
  }'

# Con remesh, PBR, e posa A
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<il tuo URL immagine pubblicamente accessibile o URI dati codificato in base64>",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

Response

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

GET/openapi/v1/image-to-3d/:id

Recupera un'attività di Immagine in 3D

Questo endpoint ti consente di recuperare un'attività di Immagine in 3D dato un valido id dell'attività. Consulta L'oggetto Attività Immagine in 3D per vedere quali proprietà sono incluse nell'oggetto attività Immagine in 3D.

Parametri

Name
id
Type
path
Description
Identificatore unico per l'attività di Immagine in 3D da recuperare.

Ritorni

La risposta contiene l'oggetto attività Immagine in 3D. Controlla la sezione L'oggetto Attività Immagine in 3D per i dettagli.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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": 30
}

DELETE/openapi/v1/image-to-3d/:id

Elimina un'attività Immagine in 3D

Questo endpoint elimina definitivamente un'attività di Immagine in 3D, inclusi tutti i modelli e i dati associati. Questa azione è irreversibile.

Parametri di percorso

Name
id
Type
path
Description
L'ID dell'attività di Immagine in 3D da eliminare.

Ritorni

Restituisce 200 OK in caso di successo.

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Restituisce 200 Ok in caso di successo.

GET/openapi/v1/image-to-3d

Elenca attività Immagine in 3D

Questo endpoint ti consente di recuperare un elenco di attività Immagine in 3D.

Parametri

Attributi opzionali

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

Ritorni

Restituisce un elenco paginato di Gli Oggetti Attività Immagine in 3D.

Request

GET

/openapi/v1/image-to-3d

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "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=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "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": 30
  }
]

GET/openapi/v1/image-to-3d/:id/stream

Esegui uno streaming di un'attività Immagine in 3D

Questo endpoint esegue lo streaming di aggiornamenti in tempo reale per un'attività Immagine in 3D utilizzando Server-Sent Events (SSE).

Parametri

Name
id
Type
path
Description
Identificatore unico per l'attività di Immagine in 3D da eseguire in streaming.

Ritorni

Restituisce un flusso di Gli Oggetti Attività Immagine in 3D come Server-Sent Events.

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

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

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

Response Stream

// Esempio di errore evento
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Esempi evento messaggio illustrano il progresso dell'attività.
// Per attività PENDING o IN_PROGRESS, il flusso di risposta non includerà tutti i campi.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
  "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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": 30
}

L'oggetto Attività Immagine in 3D

L'oggetto Attività Immagine in 3D è un'unità di lavoro che Meshy tiene traccia per generare un modello 3D da un input immagine. L'oggetto ha le seguenti proprietà:

Proprietà

Name
id
Type
string
Description
Identificatore univoco per l'attività. Mentre utilizziamo un UUID ordinabile per attività come dettaglio di implementazione, non dovresti fare alcuna supposizione sul formato dell'id.
Name
type
Type
string
Description
Tipo dell'attività Immagine in 3D. Il valore è image-to-3d.
Name
model_urls
Type
object
Description
URL scaricabile al file del modello 3D texturizzato generato da Meshy. La proprietà per un formato sarà omessa se il formato non è generato anziché restituire una stringa vuota.
- Name
  glb
  Type
  string
  Description
  URL scaricabile per il file GLB.
- Name
  fbx
  Type
  string
  Description
  URL scaricabile per il file FBX.
- Name
  obj
  Type
  string
  Description
  URL scaricabile per il file OBJ.
- Name
  usdz
  Type
  string
  Description
  URL scaricabile per il file USDZ.
- Name
  mtl
  Type
  string
  Description
  URL scaricabile per il file MTL, restituito insieme alle esportazioni OBJ quando sono presenti texture.
- Name
  stl
  Type
  string
  Description
  URL scaricabile per il file STL.
- Name
  3mf
  Type
  string
  Description
  URL scaricabile per il file 3MF. Presente solo quando 3mf è stato richiesto tramite target_formats.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  URL scaricabile per l'output originale GLB prima del remesh.
  Disponibile solo quando l'attività è stata creata con entrambi should_remesh: true e save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL scaricabile per l'immagine di miniatura del file del modello. Equivalente a thumbnail_urls.front quando presente, mantenuta per compatibilità retroattiva.
Name
alpha_thumbnail_url
Type
string
Description
URL scaricabile per 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 con successo; altrimenti questo campo è omesso.
Name
thumbnail_urls
Type
object
Description
URL scaricabili per quattro miniature delle viste cardinali del modello 3D generato. Ogni valore è un URL firmato per un PNG 512×512 renderizzato con gli stessi materiali e illuminazione di thumbnail_url. Utile per visualizzare il modello da più angolazioni in pipeline batch senza scaricare il GLB.
Presente solo quando l'attività è stata creata con multi_view_thumbnails: true ed è arrivata a SUCCEEDED. Le attività più vecchie e le attività create senza l'opzione non includeranno questo campo.
- Name
  front
  Type
  string
  Description
  Vista frontale, rotazione a 0° intorno all'asse verticale (corrisponde a thumbnail_url).
- Name
  right
  Type
  string
  Description
  Vista destra, rotazione a 90°.
- Name
  back
  Type
  string
  Description
  Vista posteriore, rotazione a 180°.
- Name
  left
  Type
  string
  Description
  Vista sinistra, rotazione a 270°.
Name
texture_prompt
Type
string
Description
Il prompt di testo che è stato utilizzato per guidare il processo di texturizzazione.
Name
texture_image_url
Type
string
Description
URL scaricabile per l'immagine di texture che è stata utilizzata per guidare il processo di texturizzazione.
Name
ultra_mode
Type
boolean
Description
Rispecchia il valore di ultra_mode con cui l'attività è stata creata. Presente solo per le attività meshy-7 (o ultimo) che impostano esplicitamente ultra_mode; omesso altrimenti.
Name
progress
Type
integer
Description
Progresso dell'attività. Se l'attività non è ancora iniziata, questa proprietà sarà 0. Una volta che l'attività è riuscita, diventerà 100.
Name
started_at
Type
timestamp
Description
Timestamp di quando l'attività è stata iniziata, in millisecondi. Se l'attività non è ancora iniziata, 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 GMT è rappresentato come 1693569600000. Questo si applica a tutti i timestamp nell'API di Meshy.
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 finita, questa proprietà sarà 0.
Name
status
Type
string
Description
Stato dell'attività. 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 generati dall'attività. Normalmente questo contiene solo uno oggetto URL di texture. Ogni URL di texture ha le seguenti proprietà:
- Name
  base_color
  Type
  string
  Description
  URL scaricabile per l'immagine della mappa del colore base.
- Name
  metallic
  Type
  string
  Description
  URL scaricabile per l'immagine della mappa del metallico.
  Se l'attività è creata con enable_pbr: false, questa proprietà sarà omessa.
- Name
  normal
  Type
  string
  Description
  URL scaricabile per l'immagine della mappa normale.
  Se l'attività è creata con enable_pbr: false, questa proprietà sarà omessa.
- Name
  roughness
  Type
  string
  Description
  URL scaricabile per l'immagine della mappa della rugosità.
  Se l'attività è creata con enable_pbr: false, questa proprietà sarà omessa.
- Name
  emission
  Type
  string
  Description
  URL scaricabile per l'immagine della mappa dell'emissione.
  Se l'attività è creata con enable_pbr: false, o ai_model è meshy-5, meshy-7, o ultimo, questa proprietà sarà omessa.
Name
preceding_tasks
Type
integer
Description
Il conteggio delle attività precedenti.
Il valore di questo campo ha un significato solo se lo stato dell'attività è PENDING.
Name
task_error
Type
object
Description
Dettagli degli errori per attività fallite. Vedi 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 Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {
    "message": ""
  },
  "consumed_credits": 30
}