API Immagine in 3D

L'API Immagine in 3D è 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

Create an Image to 3D Task

Questo endpoint consente di creare una nuova attività di Immagine in 3D. Consulta The Image to 3D Task Object per vedere quali proprietà sono incluse nell'oggetto attività Immagine in 3D.

L'attività viene eseguita in background. Per la durata tipica, consulta Processing Times.

Parametri

Solo uno tra input_task_id o image_url è richiesto. Se vengono forniti entrambi, 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 usato 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 SUCCEEDED e produrre esattamente un'immagine.

Name
image_url
Type
string
Obbligatorio
Description
Fornisci un'immagine che Meshy utilizzerà per la creazione del modello. Attualmente supportiamo i formati .jpg, .jpeg, .png e .webp.
Dimensione massima del file: 20 MB.
Ci sono due modi per fornire l'immagine:
- URL accessibile pubblicamente: 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,<your base64-encoded image data>.

Name
model_type
Type
string
predefinito standard
Description
Specifica il tipo di generazione mesh 3D.
Valori disponibili:
- standard: generazione mesh 3D ad alto dettaglio standard.
- smart-topology: scegli un modello Smart Topology con ai_model (meshy-t2).
- lowpoly (deprecato, verrà ritirato il 30 ottobre 2026): genera una mesh low-poly ottimizzata per poligoni più puliti. Consigliamo di usare Meshy T2 al suo posto: smart-topology con meshy-t2.
Quando viene selezionato smart-topology, topology, should_remesh e save_pre_remeshed_model vengono ignorati.
lowpoly verrà ritirato il 30 ottobre 2026. Dopo tale data, le richieste con model_type: "lowpoly" restituiranno un errore. Consigliamo di passare a Meshy T2 (model_type: "smart-topology" con ai_model: "meshy-t2"). 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 usare. I valori disponibili dipendono da model_type.
Generazione standard (model_type: standard):
- meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
- meshy-7 (deprecato): usa meshy-7.1 al suo posto.
Generazione Smart Topology (model_type: smart-topology):
- meshy-t2 (predefinito): il modello Smart Topology — topology più pulita, parti separate in modo nativo, output in triangoli e un numero di facce impostabile con target_polycount.
Name
geometry_resolution
Type
string
predefinito standard
Description
Passaggio di generazione geometria. 2k esegue il passaggio Ultra a 2048³; 4k lo esegue a 4096³ per il dettaglio di superficie più fine.
Valori disponibili: standard, 2k, 4k
Richiede meshy-7.1 o latest.
Name
ultra_mode
Type
boolean
⚠ deprecato
predefinito false
Description
Usa geometry_resolution al suo posto. ultra_mode: true equivale a geometry_resolution: "2k".
Name
should_texture
Type
boolean
predefinito true
Description
Determina se vengono generate le texture. Impostandolo su false si 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 (metallic, roughness, normal) oltre al colore di base. Viene inclusa anche una mappa emissiva quando ai_model è meshy-6, tranne a texture_resolution: 8k. meshy-6-lite, meshy-7.1 e latest non producono una mappa emissiva.
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). Risoluzioni più alte catturano più dettagli di superficie.
4k e 8k non sono disponibili con ai_model meshy-6-lite. A 8k, non viene prodotta alcuna mappa emissiva.
Name
hd_texture
Type
boolean
⚠ deprecato
predefinito false
Description
Usa texture_resolution al suo posto — equivale a texture_resolution: "4k". Quando entrambi sono impostati, texture_resolution ha la precedenza.
Name
texture_prompt
Type
string
Description
Fornisci un prompt testuale per guidare il processo di texturizzazione. Massimo 800 caratteri.
Name
texture_image_url
Type
string
Description
Fornisci un'immagine 2d per guidare il processo di texturizzazione. Attualmente supportiamo i formati .jpg, .jpeg, .png e .webp.
Dimensione massima del file: 20 MB.
Ci sono due modi per fornire l'immagine:
- URL accessibile pubblicamente: 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,<your base64-encoded image data>
La texturizzazione tramite immagine potrebbe non funzionare in modo ottimale se sono presenti differenze geometriche sostanziali tra l'asset originale e l'immagine caricata. Solo uno tra texture_image_url o texture_prompt può essere usato per guidare il processo di texturizzazione. Se vengono forniti entrambi i parametri, per impostazione predefinita verrà usato texture_prompt per texturizzare il modello. La texturizzazione tramite testo o immagine costerà 10 crediti per attività.

Name
should_remesh
Type
boolean
predefinito false (Meshy 6 and Meshy 7 models), true (others)
Description
Controlla se abilitare la fase di remesh. Per il modello di qualità più alta, 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 dominanza di quad.
- triangle: genera una mesh triangolare decimata.
Name
decimation_mode
Type
integer
Description
Abilita la decimazione adattiva impostando un livello di conteggio poligoni. Se impostato, target_polycount viene ignorato.
Valori disponibili:
- 1: adattivo — conteggio poligoni ultra.
- 2: adattivo — conteggio poligoni alto.
- 3: adattivo — conteggio poligoni medio.
- 4: adattivo — conteggio poligoni basso.
Name
save_pre_remeshed_model
Type
boolean
predefinito false
Description
Quando impostato su true, Meshy salva anche un file GLB aggiuntivo prima del completamento della fase di remesh.

Name
target_polycount
Type
integer
Description
Numero target di poligoni (facce) nell'output. 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 viene sottoposta a remesh (decimata) a circa questo conteggio. Intervallo da 100 a 300.000, predefinito 30.000. Se decimation_mode è impostato, ha la priorità e target_polycount viene ignorato.
- Smart Topology — con model_type: smart-topology e ai_model: meshy-t2. Il modello viene generato direttamente con questo conteggio di facce; non viene eseguito alcun remesh e should_remesh non è richiesto. Intervallo da 100 a 15.000, predefinito 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 e applica automaticamente la 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 posa A.
- t-pose: genera il modello in posa T.
- "" (stringa vuota): nessuna posa specifica applicata.
Name
is_a_t_pose
Type
boolean
⚠ deprecato
predefinito false
Description
Usa pose_mode al suo posto. Indica se generare il modello in posa A/T.
Name
surface_mode
Type
string
⚠ deprecato
Description
Non influisce più sull'output. Selezionava una generazione del modello che da allora è stata ritirata; usa ai_model al suo posto.
I valori accettati sono organic e hard; qualsiasi altro valore restituisce 400.
Name
image_enhancement
Type
boolean
predefinito true
Description
Ottimizza l'immagine di input per ottenere risultati migliori. Imposta su false per preservare l'aspetto esatto dell'immagine di input senza alcuna elaborazione dello stile.
Supportato solo quando ai_model è meshy-6, meshy-7.1 o latest.
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 con configurazioni di illuminazione personalizzate.
Supportato solo quando ai_model è meshy-6.
Name
moderation
Type
boolean
predefinito false
Description
Quando impostato su true, il contenuto in input verrà automaticamente analizzato per rilevare eventuali contenuti potenzialmente dannosi. Se viene rilevato un contenuto dannoso, l'attività non procederà alla generazione.
Il contenuto proveniente dagli 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. Verranno generati e restituiti solo i formati richiesti, il che può ridurre il tempo di completamento dell'attività. Se omesso, vengono 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
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 di conseguenza il modello. L'origine sarà impostata su bottom per impostazione predefinita, a meno che origin_at non sia esplicitamente impostato.
Name
alpha_thumbnail
Type
boolean
predefinito false
Description
Quando impostato su true, l'attività genera inoltre una versione con sfondo trasparente (RGBA) dell'anteprima e la restituisce come alpha_thumbnail_url nella risposta GET. Il campo esistente thumbnail_url rimane invariato.
Name
multi_view_thumbnails
Type
boolean
predefinito false
Description
Quando impostato su true, l'attività genera inoltre quattro miniature con viste cardinali (frontale, destra, posteriore, sinistra) e le restituisce in thumbnail_urls nella risposta GET. Il campo esistente thumbnail_url rimane invariato e continua a puntare alla vista frontale, quindi i client esistenti non ne risentono.
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.

Restituisce

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

Modalità di fallimento

Name
400 - Bad Request
Description
La richiesta non era accettabile. Cause comuni:
- Parametro mancante: deve essere fornito image_url oppure input_task_id.
- Attività di input non valida: input_task_id deve fare riferimento a un'attività Testo in immagine o Immagine in immagine con stato SUCCEEDED che produca esattamente un'immagine.
- Formato immagine non valido: l'image_url fornito non è in un formato supportato (.jpg, .jpeg, .png, .webp).
- URL non raggiungibile: non è stato possibile scaricare image_url (404 o timeout).
- Immagine troppo grande: l'immagine image_url o texture_image_url supera i 20 MB.
- Data URI non valido: la stringa base64 è malformata.
- Combinazione di parametri non valida: enable_pbr è supportato solo quando should_texture è true.
- Modello non supportato per low poly: ai_model: "meshy-6-lite" non supporta model_type: "lowpoly".
- Modello non supportato per Ultra: geometry_resolution richiede meshy-7.1 o latest.
Name
401 - Unauthorized
Description
Autenticazione non riuscita. 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 limite di frequenza.

Request

POST

/openapi/v1/image-to-3d

# Simple request with required params
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": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
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": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "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 task Immagine in 3D

Questo endpoint consente di recuperare un task Immagine in 3D dato un id di task valido. Consulta The Image to 3D Task Object per vedere quali proprietà sono incluse nell'oggetto task Immagine in 3D.

Parametri

Name
id
Type
path
Description
Identificatore univoco del task Immagine in 3D da recuperare.

Restituisce

La risposta contiene l'oggetto task Immagine in 3D. Consulta la sezione The Image to 3D Task Object 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à Immagine in 3D, inclusi tutti i modelli e i dati associati. Questa azione è irreversibile.

Parametri del percorso

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

Stato dell'attività

Un'attività ancora in stato PENDING viene eliminata e i crediti consumati al momento della creazione vengono rimborsati.

Un'attività già IN_PROGRESS non può essere eliminata: la richiesta viene rifiutata con 409 Conflict e l'attività continua a essere eseguita. I crediti per un'attività che il worker ha già avviato non sono rimborsabili, quindi eliminarla a metà esecuzione ti farebbe perdere sia i crediti sia il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.

Un'attività in uno stato terminale (SUCCEEDED, FAILED o CANCELED) viene eliminata senza rimborso.

Restituisce

Restituisce 200 OK in caso di successo, oppure 409 Conflict quando l'attività è IN_PROGRESS.

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

// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}

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

Elenca le attività Immagine in 3D

Questo endpoint 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 ha come valore predefinito 1.
Name
page_size
Type
integer
Description
Limite della dimensione della pagina. Il valore predefinito è 10 elementi. Il massimo consentito è 100 elementi.
Name
sort_by
Type
string
Description
Campo in base al quale ordinare. Valori disponibili:
- +created_at: Ordina per data di creazione in ordine crescente.
- -created_at: Ordina per data di creazione in ordine decrescente.

Restituisce

Restituisce un elenco paginato di 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

Stream di un task Immagine in 3D

Questo endpoint trasmette in streaming gli aggiornamenti in tempo reale di un task Immagine in 3D utilizzando Server-Sent Events (SSE).

Parametri

Name
id
Type
path
Description
Identificatore univoco del task Immagine in 3D da trasmettere in streaming.

Restituisce

Restituisce un flusso di oggetti task Immagine in 3D come Server-Sent Events.

Per i task 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

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

The Image to 3D Task Object

L'oggetto Image to 3D Task è un'unità di lavoro che Meshy tiene traccia per generare un modello 3D da un input di tipo image. L'oggetto ha le seguenti proprietà:

Proprietà

Name
id
Type
string
Description
Identificatore univoco del task. Sebbene per gli id dei task utilizziamo un UUID k-sortable come dettaglio implementativo, non dovresti fare alcuna assunzione sul formato dell'id.
Name
type
Type
string
Description
Tipo del task Immagine in 3D. Il valore è image-to-3d.
Name
model_urls
Type
object
Description
URL scaricabile del file del modello 3D texturizzato generato da Meshy. La proprietà per un formato verrà omessa se il formato non viene generato, invece di restituire una stringa vuota.
- 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
  pre_remeshed_glb
  Type
  string
  Description
  URL scaricabile dell'output GLB originale prima del remesh.
  Disponibile solo quando il task è stato creato con entrambi should_remesh: true e save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL scaricabile della miniatura del file del modello. Equivalente a thumbnail_urls.front quando presente, mantenuto per retrocompatibilità.
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 viene omesso.
Name
thumbnail_urls
Type
object
Description
URL scaricabili per quattro miniature con vista dai punti cardinali del modello 3D generato. Ogni valore è un URL firmato di un PNG 512×512 renderizzato con gli stessi materiali e la stessa illuminazione di thumbnail_url. Utile per visualizzare in anteprima il modello da più angolazioni in pipeline batch senza scaricare il GLB.
Presente solo quando il task è stato creato con multi_view_thumbnails: true e ha raggiunto lo stato SUCCEEDED. I task più vecchi e i task creati senza l'opt-in non includeranno questo campo.
- Name
  front
  Type
  string
  Description
  Vista frontale, rotazione a 0° attorno 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 testuale utilizzato per guidare il processo di texturizzazione.
Name
texture_image_url
Type
string
Description
URL scaricabile dell'immagine di texture utilizzata per guidare il processo di texturizzazione.
Name
ultra_mode
Type
boolean
⚠ deprecato
Description
Deprecato; leggere invece geometry_resolution.
Name
geometry_resolution
Type
string
Description
Il livello Ultra con cui è stato eseguito il task (2k o 4k); omesso per standard.
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 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 terminato, 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 di texture generati dal task. Normalmente contiene un solo 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à verrà omessa.
- Name
  normal
  Type
  string
  Description
  URL scaricabile dell'immagine della normal map.
  Se il task è creato con enable_pbr: false, questa proprietà verrà omessa.
- Name
  roughness
  Type
  string
  Description
  URL scaricabile dell'immagine della mappa di rugosità.
  Se il task è creato con enable_pbr: false, questa proprietà verrà omessa.
- Name
  emission
  Type
  string
  Description
  URL scaricabile dell'immagine della mappa di emissione.
  Se il task è creato con enable_pbr: false, oppure ai_model è meshy-6-lite, meshy-7.1, o latest, questa proprietà verrà omessa.
Name
preceding_tasks
Type
integer
Description
Il conteggio dei task precedenti.
Il valore di questo campo è significativo solo se lo stato del task è PENDING.
Name
task_error
Type
object
Description
Dettagli dell'errore per i task non riusciti. Consulta 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).

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
}