API Immagine in 3D

Trasforma un'immagine in un modello 3D, con o senza texture, nei formati che preferisci. Invia l'immagine, oppure utilizza l'output di un task Testo in immagine o Immagine in immagine.

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

Crea un task Immagine in 3D

Crea un task Immagine in 3D. Il task viene eseguito in background. Per la durata tipica di un task, consulta Tempi di elaborazione.

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

Parametri

Name
input_task_id
Type
string
Obbligatorio
Description
Obbligatorio a meno che tu non invii image_url. L'ID di un task Testo in immagine o Immagine in immagine la cui immagine vuoi usare come input. Il task deve essere uno che hai creato con l'API, avere stato SUCCEEDED e aver prodotto esattamente un'immagine.

Name
image_url
Type
string
Obbligatorio
Description
Obbligatorio a meno che tu non invii input_task_id. L'immagine da trasformare in un modello 3D, come URL pubblico o come Data URI codificato in base64, ad esempio data:image/jpeg;base64,<i tuoi dati immagine codificati in base64>. Se invii entrambi, Meshy usa input_task_id.
L'immagine deve essere un file JPG, JPEG, PNG o WebP di al massimo 20 MB.

Name
model_type
Type
string
predefinito standard
Description
Il tipo di mesh 3D da generare.
Valori disponibili:
- standard: una mesh ad alto dettaglio
- smart-topology: una mesh da un modello Smart Topology, che scegli con ai_model (meshy-t2 o meshy-t2.5)
Con smart-topology, Meshy ignora should_remesh, save_pre_remeshed_model e decimation_mode, e accetta solo topology: triangle.
Name
ai_model
Type
string
predefinito latest
Description
Il modello AI che genera il modello 3D. I valori disponibili dipendono da model_type.
Modelli standard (model_type: standard):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (deprecato): usa meshy-7.1 al suo posto
I modelli Smart Topology (model_type: smart-topology) producono triangoli, con un numero di facce che puoi impostare con target_polycount:
- meshy-t2: topology più pulita e parti nativamente separate
- meshy-t2.5 (predefinito): dettaglio più nitido per asset di gioco
Name
geometry_resolution
Type
string
predefinito standard
Description
Il passaggio di generazione della geometria.
Valori disponibili:
- standard
- 2k: esegue il passaggio Ultra a 2048³
- 4k: esegue il passaggio Ultra a 4096³, per il massimo dettaglio superficiale
2k richiede meshy-7.1, latest o il deprecato meshy-7. 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
Se generare le texture. true restituisce un modello con texture, mentre false salta la texturizzazione e restituisce una mesh senza texture.

Si applica solo quando should_texture = true

Name
enable_pbr
Type
boolean
predefinito false
Description
Se generare anche le mappe PBR (metallic, roughness e normal) oltre al colore di base. true richiede should_texture: true, e restituisce 400 con should_texture: false.
Con meshy-6, Meshy genera anche una mappa di emissione, tranne a texture_resolution: 8k. Questi modelli non producono una mappa di emissione:
- meshy-6-lite
- meshy-7
- meshy-7.1
- meshy-t2
- meshy-t2.5
- latest
Name
texture_resolution
Type
string
predefinito 2k
Description
La dimensione della texture del colore di base. Una texture più grande cattura più dettaglio superficiale.
Valori disponibili:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k e 8k non sono disponibili con meshy-6-lite, e restituiscono 400 con esso. A 8k, Meshy non produce una mappa di emissione.
Name
hd_texture
Type
boolean
⚠ deprecato
predefinito false
Description
Usa texture_resolution al suo posto. hd_texture: true equivale a texture_resolution: "4k". Se invii entrambi, Meshy usa texture_resolution.
Name
texture_prompt
Type
string
Description
Testo che guida la texture, fino a 800 caratteri. Un testo più lungo restituisce 400.
Name
texture_image_url
Type
string
Description
Un'immagine che guida la texture, come URL pubblico o come Data URI codificato in base64, ad esempio data:image/jpeg;base64,<i tuoi dati immagine codificati in base64>. L'immagine deve essere un file JPG, JPEG, PNG o WebP di al massimo 20 MB.
Meshy guida la texture con uno solo tra texture_prompt e texture_image_url. Se invii entrambi, Meshy usa texture_prompt. Per il costo in crediti della texturizzazione, consulta Prezzi.
La texturizzazione da un'immagine potrebbe non funzionare bene quando la forma dell'immagine differisce molto dalla geometria del modello 3D.

Name
should_remesh
Type
boolean
predefinito true (meshy-6-lite), false (other models)
Description
Se eseguire la fase di remesh. Per il modello 3D di qualità più alta, impostalo su false.

Si applica solo quando should_remesh = true

Name
topology
Type
string
predefinito triangle
Description
Il tipo di faccia del modello remeshato.
Valori disponibili:
- quad: una mesh a dominanza di quadrilateri
- triangle: una mesh triangolare decimata
L'output di Smart Topology è solo triangolare, quindi quad con meshy-t2 o meshy-t2.5 restituisce 400.
Name
decimation_mode
Type
integer
Description
Numero di facce adattivo, per livello. Quando lo imposti, Meshy ignora target_polycount.
Valori disponibili:
- 1: ultra
- 2: alto
- 3: medio
- 4: basso
Name
save_pre_remeshed_model
Type
boolean
predefinito false
Description
Se memorizzare anche un GLB del modello prima della fase di remesh. Meshy lo restituisce in model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
Il numero di facce a cui mirare. Il risultato può differire dall'obiettivo, a seconda della geometria del modello.
Si applica in due casi distinti:
- Remesh: quando should_remesh è true su un modello standard, Meshy decima la mesh fino a circa questo numero. Se imposti decimation_mode, Meshy lo usa e ignora target_polycount.
- Smart Topology: quando model_type è smart-topology e ai_model è meshy-t2 o meshy-t2.5, Meshy genera il modello con questo numero di facce. Non viene eseguito alcun remesh, e non hai bisogno di should_remesh.
L'intervallo e il valore predefinito dipendono dal caso:
Caso Intervallo Predefinito
Remesh 100 a 300000 30000
meshy-t2 100 a 15000 4000
meshy-t2.5 100 a 30000 15000
Un valore fuori dall'intervallo restituisce 400.

Caso	Intervallo	Predefinito
Remesh	`100` a `300000`	`30000`
`meshy-t2`	`100` a `15000`	`4000`
`meshy-t2.5`	`100` a `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ deprecato
predefinito auto
Description
Non includerlo, perché non influisce sull'output. I suoi valori controllavano la simmetria durante la generazione:
- off: nessuna simmetria
- auto: simmetria scelta in base alla geometria di input
- on: simmetria forzata
Name
pose_mode
Type
string
predefinito ""
Description
La posa per il modello generato.
Valori disponibili:
- a-pose: una posa A
- t-pose: una posa T
- "" (stringa vuota): nessuna posa specifica
Name
is_a_t_pose
Type
boolean
⚠ deprecato
predefinito false
Description
Usa pose_mode al suo posto. Se generare il modello in una posa A o T.
Name
surface_mode
Type
string
⚠ deprecato
Description
Usa ai_model al suo posto. Non influisce sull'output, perché la generazione del modello che selezionava è stata ritirata.
I valori accettati sono organic e hard. Qualsiasi altro valore restituisce 400.
Name
image_enhancement
Type
boolean
predefinito true
Description
Se ottimizzare l'immagine di input prima della generazione. false mantiene l'aspetto esatto dell'immagine di input, senza alcuna elaborazione di stile.
Funziona solo con meshy-6, meshy-7.1 o latest. Con meshy-6-lite o model_type: smart-topology, restituisce 400.
Name
remove_lighting
Type
boolean
predefinito true
Description
Se rimuovere luci e ombre dalla texture del colore di base. Il risultato è più pulito e funziona meglio con la tua illuminazione.
Ha effetto solo con meshy-6. meshy-7.1 e latest lo accettano e lo ignorano. Con meshy-6-lite o model_type: smart-topology, restituisce 400.
Name
moderation
Type
boolean
predefinito false
Description
Se analizzare questi input alla ricerca di contenuti dannosi prima della generazione:
- image_url
- texture_image_url
- texture_prompt
Se Meshy rileva contenuti dannosi, la richiesta restituisce 400 e Meshy non crea un task.
Name
target_formats
Type
string[]
Description
I formati di file da generare. Meshy genera e restituisce solo i formati che elenchi, il che può abbreviare il task. Se lo ometti, Meshy genera tutti i formati tranne 3mf, che ottieni solo se lo elenchi.
Valori disponibili:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
predefinito false
Description
Se stimare l'altezza reale dell'oggetto con la visione AI e ridimensionare il modello di conseguenza. Meshy posiziona l'origine in basso a meno che tu non imposti origin_at.
Name
alpha_thumbnail
Type
boolean
predefinito false
Description
Se renderizzare anche un'anteprima con sfondo trasparente (RGBA), restituita in alpha_thumbnail_url quando recuperi il task. thumbnail_url non cambia.
Name
multi_view_thumbnails
Type
boolean
predefinito false
Description
Se renderizzare anche le anteprime frontale, destra, posteriore e sinistra, restituite in thumbnail_urls quando recuperi il task. thumbnail_url non cambia e mostra ancora la vista frontale. Questo aggiunge circa 5 secondi al task.

Si applica solo quando auto_size = true

Name
origin_at
Type
string
predefinito bottom
Description
Dove posizionare l'origine del modello, bottom o center.

Valori restituiti

Il campo result della risposta contiene l'ID del nuovo task Immagine in 3D.

Modalità di errore

Name
400 - Bad Request
Description
La richiesta non può essere eseguita. Il messaggio di errore indica quale problema ha riscontrato. Ad esempio:
- Parametro mancante: non è stato inviato né image_url né input_task_id.
- Task di input non valido: input_task_id non è un task Testo in immagine o Immagine in immagine con stato SUCCEEDED che ha prodotto esattamente un'immagine.
- Formato immagine non valido: l'immagine image_url non è un file JPG, JPEG, PNG o WebP.
- URL irraggiungibile: Meshy non riesce a scaricare l'immagine image_url, perché l'URL restituisce 404 o va in 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 è true, e should_texture è false.
- Modello non supportato per Ultra: geometry_resolution è 2k o 4k, con un ai_model che non può eseguirlo.
- Modello non supportato per le opzioni immagine: image_enhancement o remove_lighting sono stati inviati con ai_model: "meshy-6-lite" o model_type: "smart-topology".
Correggi la richiesta, quindi inviala di nuovo. Consulta Errori.
Name
401 - Unauthorized
Description
La chiave API è mancante o non valida. Controlla l'header Authorization.
Name
402 - Payment Required
Description
Ad esempio:
- Crediti insufficienti: l'account non ha abbastanza crediti per questo task, oppure l'account ha raggiunto un limite di crediti. Controlla il tuo saldo crediti, quindi riprova.
- Piano gratuito: creare un task richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, quindi riprova.
Name
404 - Not Found
Description
input_task_id non corrisponde a nessuno dei tuoi task. Controlla l'ID del task, quindi invia di nuovo la richiesta.
Name
429 - Too Many Requests
Description
Hai superato il tuo limite di frequenza. Attendi, quindi riprova. Consulta Limiti di frequenza.

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

Get an Image to 3D task

Restituisce un'attività Immagine in 3D tramite il suo ID.

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
}

Parametri

Name
id
Type
path
Description
L'ID dell'attività proveniente dalla risposta di creazione.

Valori restituiti

L'oggetto attività Immagine in 3D.

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

Elimina un task Immagine in 3D

Elimina definitivamente un task Immagine in 3D, inclusi i suoi modelli e i relativi dati. Non puoi annullare un'eliminazione.

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 keeps 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."
}

Parametri del percorso

Name
id
Type
path
Description
L'ID del task da eliminare.

Stato del task

Eliminare un task PENDING rimborsa i crediti utilizzati al momento della sua creazione.

Un task IN_PROGRESS non può essere eliminato. La richiesta restituisce 409 Conflict, e il task continua a essere eseguito. Meshy non rimborsa un task già avviato, quindi eliminarlo ti farebbe perdere sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED, o CANCELED, quindi eliminalo.

Eliminare un task in uno stato finale (SUCCEEDED, FAILED, o CANCELED) non rimborsa i suoi crediti.

Restituisce

200 OK quando il task viene eliminato, oppure 409 Conflict quando il task è IN_PROGRESS.

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

Elenco dei task Immagine in 3D

Restituisce un elenco dei tuoi task 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
  }
]

Parametri

Name
page_num
Type
integer
predefinito 1
Description
Il numero di pagina da restituire. Le pagine iniziano da 1.
Name
page_size
Type
integer
predefinito 10
Description
Il numero di task per pagina, fino a 100.
Name
sort_by
Type
string
Description
L'ordine di ordinamento.
Valori disponibili:
- +created_at: dal più vecchio
- -created_at: dal più recente

Restituisce

Un elenco paginato di oggetti task Immagine in 3D.

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

Esegui lo streaming di un task Immagine in 3D

Esegue lo streaming degli aggiornamenti di un task Immagine in 3D come Server-Sent Events (SSE).

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.
// These examples are shortened. Each event holds the full task object.
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
}

Parametri

Name
id
Type
path
Description
L'ID del task dalla risposta di creazione.

Restituisce

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

Ogni evento contiene l'intero oggetto task, nello stesso formato restituito dall'endpoint Get. Mentre il task è PENDING o IN_PROGRESS, i suoi campi dei risultati non hanno ancora valori.

L'oggetto task Immagine in 3D

Un oggetto task Immagine in 3D descrive una generazione di un modello 3D a partire da un'immagine. Contiene lo stato, il progress e i file del modello quando il task ha successo.

Proprietà

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
}

Name
id
Type
string
Description
L'ID del task. Trattalo come una stringa opaca e non fare affidamento sul suo formato.
Name
type
Type
string
Description
Il tipo di task, sempre image-to-3d.
Name
model_urls
Type
object
Description
URL di download per il modello 3D generato, uno per ogni formato di file. Un formato che il task non ha generato non ha una chiave, invece di avere una stringa vuota.
- Name
  glb
  Type
  string
  Description
  Il file GLB.
- Name
  fbx
  Type
  string
  Description
  Il file FBX.
- Name
  obj
  Type
  string
  Description
  Il file OBJ.
- Name
  usdz
  Type
  string
  Description
  Il file USDZ.
- Name
  mtl
  Type
  string
  Description
  Il file MTL, restituito insieme a un file OBJ quando il modello ha delle texture.
- Name
  stl
  Type
  string
  Description
  Il file STL.
- Name
  3mf
  Type
  string
  Description
  Il file 3MF. Presente solo quando target_formats include 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  Il file GLB precedente al remesh. Presente solo se hai creato il task con sia should_remesh: true che save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL di download per un'immagine di anteprima del modello 3D. Quando thumbnail_urls è presente, è la stessa immagine di thumbnail_urls.front. Meshy la mantiene per compatibilità con le versioni precedenti.
Name
alpha_thumbnail_url
Type
string
Description
URL di download per una versione di thumbnail_url con sfondo trasparente (RGBA). Presente solo se hai creato il task con alpha_thumbnail: true e Meshy ha renderizzato l'anteprima trasparente.
Name
thumbnail_urls
Type
object
Description
URL di download per le anteprime del modello 3D da quattro lati. Ogni valore è un URL firmato a un'immagine PNG 512×512, renderizzata con gli stessi materiali e la stessa illuminazione di thumbnail_url. Usali per visualizzare in anteprima il modello da diverse angolazioni, ad esempio in una pipeline batch, senza scaricare il GLB.
Presente solo se hai creato il task con multi_view_thumbnails: true e il task ha raggiunto lo stato SUCCEEDED. I task creati senza multi_view_thumbnails: true non includono questo campo.
- Name
  front
  Type
  string
  Description
  La vista frontale, a 0° attorno all'asse verticale. Corrisponde a thumbnail_url.
- Name
  right
  Type
  string
  Description
  La vista destra, a 90°.
- Name
  back
  Type
  string
  Description
  La vista posteriore, a 180°.
- Name
  left
  Type
  string
  Description
  La vista sinistra, a 270°.
Name
texture_prompt
Type
string
Description
Il prompt testuale che ha guidato la texture.
Name
texture_image_url
Type
string
Description
URL di download per l'immagine che ha guidato la texture.
Name
ultra_mode
Type
boolean
⚠ deprecato
Description
Consulta invece geometry_resolution.
Name
geometry_resolution
Type
string
Description
Il livello Ultra in cui il task è stato eseguito, 2k o 4k. Un task standard non include questo campo.
Name
progress
Type
integer
Description
Quanta parte del task è stata completata, in percentuale. È 0 finché il task non inizia e 100 quando ha successo.
Name
started_at
Type
timestamp
Description
L'orario in cui il task è iniziato, in millisecondi Unix. È 0 finché il task non inizia.
Name
created_at
Type
timestamp
Description
L'orario in cui il task è stato creato, in millisecondi Unix.
Name
expires_at
Type
timestamp
Description
L'orario in cui il risultato del task scade, in millisecondi Unix.
Name
finished_at
Type
timestamp
Description
L'orario in cui il task è terminato, in millisecondi Unix. È 0 finché il task non termina.
Name
status
Type
string
Description
Lo stato del task, uno tra PENDING, IN_PROGRESS, SUCCEEDED, FAILED o CANCELED.
Name
texture_urls
Type
array
Description
Le texture map generate dal task, come un array di oggetti. Di solito contiene un solo oggetto, con questi campi:
- Name
  base_color
  Type
  string
  Description
  URL di download per la mappa del colore base.
- Name
  metallic
  Type
  string
  Description
  URL di download per la mappa metallica. Il campo è assente se hai creato il task con enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  URL di download per la normal map. Il campo è assente se hai creato il task con enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  URL di download per la mappa della ruvidità. Il campo è assente se hai creato il task con enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  URL di download per la mappa di emissione. Il campo è assente se hai creato il task con enable_pbr: false o texture_resolution: 8k, oppure quando ai_model è uno di questi modelli:
  
  meshy-6-lite
  
  meshy-7
  
  meshy-7.1
  
  meshy-t2
  
  meshy-t2.5
  
  latest
Name
preceding_tasks
Type
integer
Description
Il numero di task che precedono questo nella coda. Il valore è significativo solo mentre il task è PENDING.
Name
task_error
Type
object
Description
I dettagli dell'errore quando il task fallisce. Vedi Errori.
Name
consumed_credits
Type
integer
Description
Il numero di crediti utilizzati dal task. Presente quando lo stato è PENDING, IN_PROGRESS o SUCCEEDED. È 0 per un task FAILED, perché Meshy rimborsa i crediti quando un task fallisce.