lowpoly verrà ritirato il 30 ott 2026. meshy-7 come modello di generazione 3D verrà ritirato il 31 dic 2026; come modello di texture resta disponibile. Cambia modello prima di queste date per evitare errori nelle richieste. Vedi tutte le deprecazioni

API Multi-immagine in 3D

Genera un modello 3D a partire da una fino a quattro immagini dello stesso oggetto, scattate da angolazioni diverse.


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

Crea un'attività Multi-immagine in 3D

Crea un'attività Multi-immagine in 3D. L'attività viene eseguita in background. Per la durata tipica di un'attività, vedi Tempi di elaborazione. Per i campi di un'attività, vedi L'oggetto attività Multi-immagine in 3D.

Request

POST
/openapi/v1/multi-image-to-3d
# Simple request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ]
  }'

# With Ultra 2K geometry, PBR texturing, and GLB format
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your publicly accessible image url or base64-encoded data URI>",
      "<your second publicly accessible image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "geometry_resolution": "2k",
    "should_texture": true,
    "enable_pbr": true,
    "target_formats": ["glb"]
  }'

# Textured with Meshy N1 from the input images, the first as the front view
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_urls": [
      "<your front view image url or base64-encoded data URI>",
      "<your back view image url or base64-encoded data URI>"
    ],
    "ai_model": "meshy-7.1",
    "texture_model": "meshy-n1"
  }'

Response

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

Parametri

  • Name
    input_task_id
    Type
    string
    Obbligatorio
    Description

    Obbligatorio a meno che tu non invii image_urls. L'ID di un'attività Testo in immagine o Immagine in immagine, inclusa una multi-vista. Meshy usa le sue da una a quattro immagini come input. L'attività deve essere una creata da te con l'API e avere lo stato SUCCEEDED.

  • Name
    image_urls
    Type
    array
    Obbligatorio
    Description

    Obbligatorio a meno che tu non invii input_task_id. Da una a quattro immagini, ciascuna come URL pubblico o Data URI, ad esempio data:image/jpeg;base64,<i tuoi dati immagine codificati in base64>. Se invii entrambi, Meshy usa input_task_id.

    Ogni immagine deve essere un file .jpg, .jpeg, .png o .webp di al massimo 20 MB, con almeno 32 pixel per lato e al massimo 178.956.970 pixel (larghezza × altezza). Più di quattro immagini restituisce 400.

    Per i migliori risultati, le immagini dovrebbero mostrare lo stesso oggetto da angolazioni diverse. Con meshy-7.1 o latest, Meshy usa la prima immagine come vista frontale, e l'ordine delle altre non ha importanza.

  • Name
    ai_model
    Type
    string
    predefinito latest
    Description

    Il modello AI che genera il modello 3D.

    Valori disponibili:

    • latest: Meshy 7.1
    • meshy-7.1
    • meshy-6
    • meshy-6-lite
    • meshy-7: deprecato, invia meshy-7.1 al suo posto. Va in pensione il 31 dicembre 2026.

    Vedi Modelli per sapere quale modello si adatta al tuo progetto, ad esempio un oggetto reale o una stampa 3D.

  • Name
    geometry_resolution
    Type
    string
    predefinito standard
    Description

    Quanto dettaglio geometrico generare.

    Valori disponibili:

    • standard
    • 2k: esegue il passaggio Ultra a 2048³. Richiede meshy-7.1, latest, o il deprecato meshy-7.
  • Name
    ultra_mode
    Type
    boolean
    ⚠ deprecato
    predefinito false
    Description

    Invia 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 il passaggio di texturizzazione e restituisce una mesh senza texture.

Si applica solo quando should_texture = true
  • Name
    texture_model
    Type
    string
    predefinito depends on ai_model
    Description

    Il modello AI che applica la texture al modello 3D da più viste, nella stessa attività. Ometterlo per usare il modello di texture predefinito per il tuo ai_model. Non modifica il costo in crediti.

    Valori disponibili:

    • meshy-7: Meshy 7, con mappe PBR e texture fino a 8K
    • meshy-n1: Meshy N1, una texture base color 2K solo da immagini di riferimento

    Ogni ai_model accetta entrambi. Una richiesta con texture con meshy-6 o meshy-6-lite restituisce 400, così come un'opzione non supportata dal modello di texture scelto. Con should_texture: false, Meshy ignora texture_model, ma un valore sconosciuto restituisce comunque 400.

    Con meshy-n1, Meshy applica la texture da texture_image_urls o texture_image_url, oppure dalle immagini di input quando non invii nessuno dei due. La prima immagine è la vista frontale. Un modello generato con oltre 7.999.999 triangoli fa fallire l'attività, e Meshy rimborsa i crediti.

    Vedi Modelli per sapere cosa fa ogni modello di texture e quale scegliere.

  • Name
    enable_pbr
    Type
    boolean
    predefinito false
    Description

    Se generare anche le mappe metallic, roughness e normal, oltre al base color. Il modello di texture Meshy 6 genera anche una mappa emission, tranne a texture_resolution: 8k. Con texture_model: meshy-n1, true restituisce 400.

  • Name
    texture_resolution
    Type
    string
    predefinito 2k
    Description

    La dimensione della texture base color. Una dimensione maggiore cattura più dettaglio superficiale.

    Valori disponibili:

    • 2k: 2048×2048
    • 4k: 4096×4096
    • 8k: 8192×8192

    4k e 8k richiedono il modello di texture Meshy 7 o Meshy 6, e restituiscono 400 con gli altri. A 8k, Meshy non genera una mappa emission.

  • Name
    hd_texture
    Type
    boolean
    ⚠ deprecato
    predefinito false
    Description

    Invia 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. Con texture_model: meshy-n1, inviarlo restituisce 400.

  • Name
    texture_image_url
    Type
    string
    Description

    Un'immagine 2D che guida la texture, come URL pubblico o Data URI, 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, con almeno 32 pixel per lato e al massimo 178.956.970 pixel (larghezza × altezza).

    Se invii sia texture_image_url che texture_prompt, Meshy usa texture_prompt. Con texture_model: meshy-n1, Meshy applica la texture da questa immagine come vista frontale.

  • Name
    texture_image_urls
    Type
    string[]
    Description

    Da una a quattro immagini dell'oggetto da viste diverse che guidano la texture. Meshy usa la prima immagine come vista frontale. L'ordine delle altre viste (sinistra, retro, destra) non ha importanza.

    Ogni immagine segue le stesse regole di texture_image_url. È un URL pubblico o un Data URI, in formato .jpg, .jpeg, .png o .webp, di al massimo 20 MB, con almeno 32 pixel per lato e al massimo 178.956.970 pixel (larghezza × altezza).

    Queste immagini guidano solo la texture e non dipendono da image_urls. I due elenchi possono contenere immagini diverse e numeri diversi di immagini.

    texture_image_urls richiede il modello di texture Meshy 7 o Meshy N1. Inviala insieme a uno di questi:

    • ai_model pari a meshy-7.1, latest, o il deprecato meshy-7
    • texture_model pari a meshy-7 o meshy-n1

    Non puoi inviarla insieme a texture_image_url o texture_prompt.

  • Name
    should_remesh
    Type
    boolean
    predefinito true (meshy-6-lite), false (other models)
    Description

    Se rifare il remesh del modello dopo la generazione. 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 dopo il remesh.

    Valori disponibili:

    • quad: una mesh a dominanza di quadrilateri
    • triangle: una mesh a triangoli decimata

    Con texture_model: meshy-n1, quad restituisce 400 quando il modello viene sottoposto a remesh, cosa che meshy-6-lite fa per impostazione predefinita.

  • Name
    target_polycount
    Type
    integer
    predefinito 30000
    Description

    Il numero di facce a cui puntare, da 100 a 300000. Il risultato può differire dal target, a seconda della geometria del modello. Un valore fuori dall'intervallo 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 salvare anche il GLB precedente al remesh, restituito in model_urls.pre_remeshed_glb.

  • Name
    symmetry_mode
    Type
    string
    ⚠ deprecato
    predefinito auto
    Description

    Ometterlo. Non influisce sull'output.

    Valori disponibili:

    • off: nessuna simmetria
    • auto: simmetria basata sulla geometria di input
    • on: simmetria forzata
  • Name
    pose_mode
    Type
    string
    Description

    La posa per un modello di personaggio, a-pose o t-pose. Per non avere alcuna posa, ometti pose_mode e is_a_t_pose.

  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ deprecato
    predefinito false
    Description

    Invia pose_mode al suo posto. Se generare il modello in posa A o T.

  • Name
    image_enhancement
    Type
    boolean
    predefinito true
    Description

    Se ottimizzare le immagini di input prima della generazione. false mantiene l'aspetto esatto delle immagini di input, senza alcuna elaborazione dello stile. Supportato solo con meshy-6, meshy-7.1 o latest. Inviarlo con meshy-6-lite restituisce 400.

  • Name
    remove_lighting
    Type
    boolean
    predefinito true
    Description

    Se rimuovere luci e ombre dalla texture base color. Il risultato più pulito funziona meglio con la tua illuminazione. Lo usa solo il modello di texture Meshy 6, e a texture_resolution: 8k rimuove sempre l'illuminazione. Con texture_model: meshy-n1, true restituisce 400. Con ai_model: meshy-6-lite e il suo modello di texture predefinito, inviarlo restituisce 400.

  • Name
    moderation
    Type
    boolean
    predefinito false
    Description

    Se analizzare gli input alla ricerca di contenuti dannosi. Meshy analizza ogni immagine di input, texture_image_url o ciascuna immagine in texture_image_urls, e il testo in texture_prompt. Se Meshy trova contenuti dannosi, la richiesta restituisce 400 e Meshy non crea un'attività.

  • Name
    target_formats
    Type
    string[]
    Description

    I formati di file 3D da generare. Meshy genera e restituisce solo i formati elencati, il che può ridurre la durata dell'attività.

    Valori disponibili:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf

    Se lo ometti, Meshy genera tutti i formati tranne 3mf. Meshy genera 3mf solo quando lo elenchi.

  • 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.

Si applica solo quando auto_size = true
  • Name
    origin_at
    Type
    string
    predefinito bottom
    Description

    Dove posizionare l'origine del modello, bottom o center.

  • Name
    alpha_thumbnail
    Type
    boolean
    predefinito false
    Description

    Se rendere anche un'anteprima con sfondo trasparente (RGBA), restituita in alpha_thumbnail_url quando ottieni l'attività. thumbnail_url non cambia.

  • Name
    multi_view_thumbnails
    Type
    boolean
    predefinito false
    Description

    Se rendere anche le anteprime frontale, destra, posteriore e sinistra, restituite in thumbnail_urls quando ottieni l'attività. thumbnail_url non cambia e mostra ancora la vista frontale. Questo aggiunge circa 5 secondi all'attività.

Valori restituiti

Il campo result della risposta contiene l'ID della nuova attività Multi-immagine in 3D.

Modalità di errore

  • Name
    400 - Bad Request
    Description

    La richiesta non può essere eseguita. Il messaggio di errore indica quale problema è stato rilevato. Ad esempio:

    • Parametro mancante: non è stato inviato né image_urls né input_task_id.
    • Attività di input non valida: input_task_id non è un'attività Testo in immagine o Immagine in immagine con stato SUCCEEDED, né una multi-vista.
    • Numero di immagini non valido: image_urls o texture_image_urls non contiene da 1 a 4 immagini.
    • Formato immagine non valido: un'immagine in image_urls non è in un formato supportato.
    • Input di texture in conflitto: texture_image_urls è stato inviato insieme a texture_image_url, a texture_prompt, o a should_texture: false.
    • Modello non supportato per texture multi-vista: texture_image_urls è stato inviato con ai_model pari a meshy-6 o meshy-6-lite, a meno che texture_model non sia meshy-7 o meshy-n1.
    • URL non raggiungibile: Meshy non riesce a scaricare un'immagine in image_urls o texture_image_urls.
    • Immagine troppo grande: un'immagine in image_urls, texture_image_url o texture_image_urls supera 20 MB.
    • Dimensione immagine non valida: un'immagine in image_urls, texture_image_url o texture_image_urls ha un lato più corto di 32 pixel, oppure più di 178.956.970 pixel (larghezza × altezza).
    • Risoluzione non supportata per input multi-immagine: geometry_resolution è "4k", che questo endpoint non supporta. Usa 2k o standard.
    • Modello non supportato per le opzioni immagine: image_enhancement è stato inviato con ai_model: "meshy-6-lite", oppure remove_lighting è stato inviato con ai_model: "meshy-6-lite" e il suo modello di texture predefinito.
    • Modello di texture non valido: texture_model non è un nome di modello di texture valido.
    • Modello di texture non disponibile: una richiesta con texture ha inviato texture_model pari a meshy-6 o meshy-6-lite. Multi-immagine in 3D accetta solo i modelli di texture che applicano la texture da più viste. Invia meshy-7 o meshy-n1, oppure ometti texture_model.
    • Opzione non supportata per il modello di texture: la richiesta chiede al modello di texture un'opzione che non supporta, ad esempio enable_pbr: true con meshy-n1 o una texture 4k con meshy-6-lite. Vedi Modelli.

    Correggi la richiesta, quindi inviala di nuovo. Vedi 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 crediti sufficienti per questa attività, oppure l'account ha raggiunto un limite di crediti. Controlla il tuo saldo crediti, quindi riprova.
    • Piano gratuito: creare un'attività richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, quindi riprova.
  • Name
    403 - Forbidden
    Description

    La moderazione dei contenuti ha bloccato il prompt o un'immagine di input. Modifica l'input, quindi riprova.

  • Name
    404 - Not Found
    Description

    input_task_id non corrisponde a nessuna delle tue attività. Controlla l'ID dell'attività, quindi invia di nuovo la richiesta.

  • Name
    429 - Too Many Requests
    Description

    Hai superato il limite di frequenza. Attendi, quindi riprova. Vedi Limiti di frequenza.


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

Ottenere un task Multi-immagine in 3D

Restituisce un task Multi-immagine in 3D in base al suo ID.

Request

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Parametri

  • Name
    id
    Type
    path
    Description

    L'ID del task ottenuto dalla risposta di creazione.

Valori restituiti

L'oggetto task Multi-immagine in 3D.


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

Elimina un'attività Multi-immagine in 3D

Elimina definitivamente un'attività Multi-immagine in 3D, inclusi i suoi modelli e dati. Non puoi annullare un'eliminazione.

Request

DELETE
/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/multi-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 dell'attività da eliminare.

Stato dell'attività

Eliminare un'attività PENDING rimborsa i crediti utilizzati al momento della sua creazione.

Un'attività IN_PROGRESS non può essere eliminata. La richiesta restituisce 409 Conflict, e l'attività continua a essere eseguita. Meshy non rimborsa un'attività già avviata, quindi eliminarla ti farebbe perdere sia i crediti che il risultato. Attendi che raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.

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

Restituisce

200 OK quando l'attività viene eliminata, oppure 409 Conflict quando l'attività è IN_PROGRESS.


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

Elenca i task di Multi-immagine in 3D

Restituisce un elenco dei tuoi task di Multi-immagine in 3D.

Request

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "multi-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"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 30
  }
]

Parametri

  • Name
    page_num
    Type
    integer
    predefinito 1
    Description

    Il numero di pagina da restituire, fino a 255. Un valore maggiore restituisce 400.

  • Name
    page_size
    Type
    integer
    predefinito 10
    Description

    Il numero di task per pagina, fino a 100.

  • Name
    sort_by
    Type
    string
    Description

    L'ordinamento.

    Valori disponibili:

    • +created_at: dal più vecchio al più recente
    • -created_at: dal più recente al più vecchio

Restituisce

Un elenco paginato di oggetti task Multi-immagine in 3D.


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

Esegui lo streaming di un task Multi-immagine in 3D

Trasmette in streaming gli aggiornamenti di un task Multi-immagine in 3D come Server-Sent Events (SSE).

Request

GET
/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/multi-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": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 30
}

Parametri

  • Name
    id
    Type
    path
    Description

    L'ID del task dalla risposta di creazione.

Valori restituiti

Uno stream di oggetti task Multi-immagine in 3D come Server-Sent Events.

Ogni evento contiene l'oggetto task completo, nella stessa forma restituita dall'endpoint Get. Mentre il task è PENDING o IN_PROGRESS, i suoi campi di risultato non hanno ancora valori.


L'oggetto task Multi-immagine in 3D

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

Proprietà

Example Multi-Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "multi-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"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "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 multi-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, piuttosto che 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 al 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 quando 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. È identico a thumbnail_urls.front quando quel campo è presente.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL di download per una versione di thumbnail_url con sfondo trasparente (RGBA). Presente solo quando 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. Ognuno è un URL firmato a un'immagine PNG 512×512, renderizzata con gli stessi materiali e la stessa illuminazione di thumbnail_url. Puoi usarli per visualizzare in anteprima il modello da più angolazioni senza scaricare il GLB.

    Presente solo quando hai creato il task con multi_view_thumbnails: true e il task ha raggiunto lo stato SUCCEEDED. Un task creato senza multi_view_thumbnails: true non ha 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_urls
    Type
    string[]
    Description

    URL di download per le immagini di riferimento della texture con cui hai creato il task, nell'ordine in cui le hai inviate. Presente solo quando hai creato il task con texture_image_urls.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ deprecato
    Description

    Leggi invece geometry_resolution.

  • Name
    geometry_resolution
    Type
    string
    Description

    Il livello Ultra con cui è stato eseguito il task, ossia 2k. Un task standard non ha questo campo.

  • Name
    progress
    Type
    integer
    Description

    Quanto del task è stato completato, in percentuale. È 0 finché il task non inizia e 100 quando ha successo.

  • Name
    started_at
    Type
    timestamp
    Description

    Momento in cui il task è iniziato, in millisecondi Unix. È 0 finché il task non inizia.

  • Name
    created_at
    Type
    timestamp
    Description

    Momento in cui il task è stato creato, in millisecondi Unix.

  • Name
    expires_at
    Type
    timestamp
    Description

    Momento in cui i risultati del task scadono, in millisecondi Unix.

  • Name
    finished_at
    Type
    timestamp
    Description

    Momento 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

    URL di download per le mappe di texture generate dal task, come un array di oggetti. Di solito contiene un solo oggetto. Ogni oggetto ha questi campi:

    • Name
      base_color
      Type
      string
      Description

      La mappa del colore base.

    • Name
      metallic
      Type
      string
      Description

      La mappa metallica. Non inclusa quando hai creato il task con enable_pbr: false.

    • Name
      normal
      Type
      string
      Description

      La normal map. Non inclusa quando hai creato il task con enable_pbr: false.

    • Name
      roughness
      Type
      string
      Description

      La mappa di rugosità. Non inclusa quando hai creato il task con enable_pbr: false.

    • Name
      emission
      Type
      string
      Description

      La mappa di emissione. Inclusa solo quando hai creato il task con tutti i seguenti elementi:

      • ai_model: meshy-6, con il suo modello di texture predefinito
      • enable_pbr: true
      • un texture_resolution di 2k o 4k
  • 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. È null a meno che lo stato non sia FAILED. Consulta 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.