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 Testo in 3D

Genera modelli 3D a partire da prompt testuali nella tua applicazione.

Testo in 3D funziona in due passaggi. Innanzitutto, crea un task di preview (mode: "preview") per generare una mesh 3D senza texture, in modo da poter verificare la forma. Successivamente, invia l'ID del task di preview completato con successo a un task di refine (mode: "refine") per applicare la texture alla mesh. Entrambi i passaggi utilizzano lo stesso endpoint.


POST/openapi/v2/text-to-3d

Creare un'attività di anteprima Text to 3D

Crea un'attività di anteprima Testo in 3D, che genera una mesh 3D senza texture (solo geometria) a partire da un prompt testuale. Questo è il primo passo del flusso di lavoro in due fasi. Dopo che l'anteprima ha avuto successo, invia il suo ID attività in un'attività refine per applicare la texture alla mesh. Vedi Creare un'attività refine Text to 3D. Per lo schema completo della risposta, vedi L'oggetto attività Text to 3D.

L'attività viene eseguita in background. Per quanto tempo richiede solitamente un'attività, vedi Tempi di elaborazione.

Request

POST
/openapi/v2/text-to-3d
# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

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

Parametri

  • Name
    mode
    Type
    string
    Obbligatorio
    Description

    La fase del flusso di lavoro in due fasi. Invia preview per creare un'attività di anteprima.

  • Name
    prompt
    Type
    string
    Obbligatorio
    Description

    Testo che descrive l'oggetto da generare, fino a 800 caratteri. Un testo più lungo restituisce 400.

  • Name
    model_type
    Type
    string
    predefinito standard
    Description

    Il tipo di mesh 3D da generare.

    Valori disponibili:

    • standard: una mesh 3D ad alto dettaglio
    • smart-topology: una mesh Smart Topology. Scegli il modello con ai_model (meshy-t2 o meshy-t2.5).

    Con smart-topology, Meshy ignora should_remesh 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):

    • meshy-6-lite
    • meshy-6
    • meshy-7.1
    • latest: Meshy 7.1
    • meshy-7 (deprecato): invia meshy-7.1 al suo posto. Viene ritirato il 31 dicembre 2026.

    Modelli Smart Topology (model_type: smart-topology):

    • meshy-t2: topology più pulita, parti separate nativamente, output in triangoli e un numero di facce che imposti con target_polycount
    • meshy-t2.5 (predefinito): dettaglio più nitido per asset di gioco, output in triangoli e un numero di facce che imposti con target_polycount

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

  • Name
    geometry_resolution
    Type
    string
    predefinito standard
    Description

    Il passaggio di generazione della geometria. Si applica solo alle attività di anteprima. Un refine con questo parametro restituisce 400.

    Valori disponibili:

    • standard
    • 2k: esegue il passaggio Ultra a 2048³
    • 4k: esegue il passaggio Ultra a 4096³, per un dettaglio di superficie più fine

    2k richiede meshy-7.1, latest, o il deprecato meshy-7. 4k richiede meshy-7.1 o latest. Altri modelli restituiscono 400.

  • 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_remesh
    Type
    boolean
    predefinito true (meshy-6-lite), false (other models)
    Description

    Se rieseguire il remesh del modello dopo la generazione. Per il modello 3D della massima qualità, invia false.

Si applica solo quando should_remesh = true
  • Name
    topology
    Type
    string
    predefinito triangle
    Description

    Il tipo di faccia del modello sottoposto a remesh.

    Valori disponibili:

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

    L'output di Smart Topology è solo triangolare. Inviare quad con ai_model 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
    target_polycount
    Type
    integer
    Description

    Il numero di facce a cui mirare. Il risultato può differire dal target, a seconda della geometria. Si applica in due casi distinti:

    • Remesh: con should_remesh: true su un modello standard. Meshy sottopone la mesh a remesh (decimazione) fino a circa questo numero. Se imposti decimation_mode, Meshy lo usa e ignora target_polycount.
    • Smart Topology: con model_type: smart-topology e ai_model meshy-t2 o meshy-t2.5. Meshy genera il modello direttamente con questo numero di facce. Non viene eseguito alcun remesh e non è necessario should_remesh.

    La tabella seguente mostra l'intervallo e il valore predefinito per ciascun caso:

    CasoIntervalloPredefinito
    Remesh100 a 30000030000
    meshy-t2100 a 150004000
    meshy-t2.5100 a 3000015000

    Un valore fuori dall'intervallo restituisce 400.

    Per un asset di gioco low-poly, usa un modello Smart Topology invece di eseguire il remesh di un modello standard. Vedi Modelli.

  • Name
    symmetry_mode
    Type
    string
    ⚠ deprecato
    predefinito auto
    Description

    Non includerlo. Questo parametro non influisce sull'output.

    Valori disponibili:

    • off: disabilita la simmetria
    • auto: applica la simmetria in base alla geometria di input
    • on: impone la simmetria durante la generazione
  • Name
    pose_mode
    Type
    string
    Description

    La posa per un modello di personaggio, a-pose o t-pose. Per non avere alcuna posa, non includere 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 posa T.

  • Name
    art_style
    Type
    string
    ⚠ deprecato
    predefinito realistic
    Description

    Non includerlo. Meshy lo ignora.

  • Name
    moderation
    Type
    boolean
    predefinito false
    Description

    Se verificare prompt per contenuti dannosi prima della generazione. Se Meshy rileva contenuti dannosi, la richiesta restituisce 400 e Meshy non crea l'attività.

  • Name
    target_formats
    Type
    string[]
    Description

    I formati di file da generare. Meshy genera e restituisce solo questi formati, il che può ridurre la durata dell'attività. Se lo ometti, Meshy genera tutti i formati tranne 3mf, che genera solo quando lo richiedi.

    Valori disponibili:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • Name
    alpha_thumbnail
    Type
    boolean
    predefinito false
    Description

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

  • Name
    auto_size
    Type
    boolean
    predefinito false
    Description

    Se stimare l'altezza reale dell'oggetto tramite visione artificiale 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.

Valori restituiti

Il campo result della risposta contiene l'ID della nuova attività Text to 3D.

Modalità di errore

  • Name
    400 - Bad Request
    Description

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

    • Parametro mancante: manca un parametro obbligatorio, come prompt o mode.
    • Prompt troppo lungo: prompt supera il limite di caratteri.
    • Modello non supportato per Ultra: geometry_resolution è 2k o 4k, con un ai_model che non può eseguirlo.

    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 abbastanza crediti per questa attività, oppure l'account ha raggiunto un limite di crediti. Controlla il tuo saldo crediti, quindi riprova.
    • Piano gratuito: la creazione di 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
    429 - Too Many Requests
    Description

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


POST/openapi/v2/text-to-3d

Crea un task di refine per Testo in 3D

Crea un task di refine per Testo in 3D, che applica la texture alla mesh di un task di preview completato. Invia l'ID di un task di preview riuscito come preview_task_id. Vedi Crea un task di preview per Testo in 3D. Questo è il secondo passaggio del flusso di lavoro in due fasi.

Il task viene eseguito in background. Per la durata tipica di un task, vedi Tempi di elaborazione.

Request

POST
/openapi/v2/text-to-3d
# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "ai_model": "meshy-n1"
}'

Response

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

Parametri

  • Name
    mode
    Type
    string
    Obbligatorio
    Description

    Il passaggio del flusso di lavoro in due fasi. Invia refine per creare un task di refine.

  • Name
    preview_task_id
    Type
    string
    Obbligatorio
    Description

    L'ID del task di preview a cui applicare la texture. Il task di preview deve avere stato SUCCEEDED.

  • Name
    enable_pbr
    Type
    boolean
    predefinito false
    Description

    Se generare anche mappe PBR (metallic, roughness e normal) insieme al colore base.

    Con ai_model meshy-6, Meshy genera anche una emission map, tranne a texture_resolution: 8k. meshy-6-lite, meshy-7 e latest non generano una emission map. Non lo fa nemmeno un refine di una preview meshy-t2 o meshy-t2.5 che non imposta ai_model. Con ai_model: meshy-n1, true restituisce 400.

  • Name
    texture_resolution
    Type
    string
    predefinito 2k
    Description

    La risoluzione della texture del colore base. Si applica solo ai task di refine. Una preview con questo parametro restituisce 400.

    Valori disponibili:

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

    Risoluzioni più alte catturano più dettagli di superficie. 4k e 8k richiedono ai_model meshy-6, meshy-7 o latest. Con meshy-n1, restituiscono 400. A 8k, Meshy non genera una emission map.

  • Name
    hd_texture
    Type
    boolean
    ⚠ deprecato
    predefinito false
    Description

    Invia texture_resolution invece. 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 creazione della texture, fino a 800 caratteri. Un testo più lungo restituisce 400. Invia texture_prompt o texture_image_url, non entrambi. Se invii entrambi, Meshy usa texture_prompt. Con ai_model: meshy-n1, inviarlo restituisce 400.

  • Name
    texture_image_url
    Type
    string
    Description

    Un'immagine 2D che guida la creazione della 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 massimo 20 MB, con almeno 32 pixel per lato e al massimo 178.956.970 pixel (larghezza × altezza).

    Con ai_model: meshy-n1, Meshy applica la texture usando questa immagine come vista frontale.

  • Name
    ai_model
    Type
    string
    predefinito inherited from the preview task
    Description

    Il modello IA che applica la texture alla mesh. La mesh proviene dalla preview, quindi in un refine ai_model sceglie solo il modello di texture.

    Valori disponibili:

    • meshy-7: Meshy 7
    • latest: il modello di texture più recente, ora Meshy 7
    • meshy-6: Meshy 6
    • meshy-6-lite: Meshy 6 Lite
    • meshy-n1: una texture del colore base 2K generata solo da un'immagine di riferimento. Nessun prompt testuale, nessuna mappa PBR, nessun 4K o 8K.

    I valori sopra indicati sono modelli di texture. Ometti il parametro per applicare la texture con il modello corrispondente alla preview. Invia un valore per sovrascriverlo.

    Con meshy-n1, Meshy applica la texture da texture_image_url. In sua assenza, Meshy usa l'immagine di riferimento memorizzata da una preview meshy-7.1 o latest. Qualsiasi altra preview restituisce 400 a meno che tu non invii texture_image_url. La preview può avere al massimo 7.999.999 triangoli. Una preview sottoposta a remesh in quad restituisce 400.

  • Name
    moderation
    Type
    boolean
    predefinito false
    Description

    Se analizzare texture_prompt e texture_image_url alla ricerca di contenuti dannosi prima della generazione. Se Meshy rileva contenuti dannosi, la richiesta restituisce 400 e Meshy non crea il task.

  • Name
    remove_lighting
    Type
    boolean
    predefinito true
    Description

    Se rimuovere luci e ombre dalla texture del colore base. Il risultato più pulito funziona meglio con illuminazione personalizzata.

    Ha effetto solo quando ai_model è meshy-6. meshy-7 e latest lo accettano ma lo ignorano, così come un refine di una preview meshy-t2 o meshy-t2.5 che non imposta ai_model. Inviarlo con meshy-6-lite restituisce 400. Con meshy-n1, true restituisce 400.

  • Name
    target_formats
    Type
    string[]
    Description

    I formati di file da generare. Meshy genera e restituisce solo questi formati, il che può ridurre la durata del task. Se lo ometti, Meshy genera tutti i formati tranne 3mf, che genera solo su richiesta.

    Valori disponibili:

    • glb
    • obj
    • fbx
    • stl
    • usdz
    • 3mf
  • Name
    alpha_thumbnail
    Type
    boolean
    predefinito false
    Description

    Se generare anche un'anteprima con sfondo trasparente (RGBA), restituita in alpha_thumbnail_url quando recuperi il task. thumbnail_url non cambia.

  • Name
    auto_size
    Type
    boolean
    predefinito false
    Description

    Se stimare l'altezza reale dell'oggetto tramite visione artificiale IA 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.

Valori restituiti

Il campo result della risposta contiene l'ID del nuovo task Testo 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:

    • Invalid task ID: preview_task_id non è valido, o non corrisponde a nessuno dei tuoi task di preview.
    • Task not ready: Il task di preview non è ancora riuscito.
    • Model mismatch: Il modello IA del task di preview non è compatibile con il modello di refine richiesto.
    • Unsupported model for remove_lighting: remove_lighting è stato inviato con ai_model: "meshy-6-lite".
    • No reference image for Meshy N1: ai_model: meshy-n1 è stato inviato senza texture_image_url, e la preview non ha un'immagine di riferimento utilizzabile da Meshy N1. Invia texture_image_url.
    • Quad preview for Meshy N1: ai_model: meshy-n1 è stato inviato per una preview sottoposta a remesh in quad. Esegui il refine con un altro ai_model.
    • Too many triangles for Meshy N1: Con ai_model: meshy-n1, la preview ha più di 7.999.999 triangoli. Esegui il refine con un altro ai_model.
    • Unsupported option for Meshy N1: ai_model: meshy-n1 è stato inviato con una di queste opzioni:
      • texture_prompt
      • enable_pbr: true
      • texture_resolution pari a 4k o 8k
      • hd_texture: true senza texture_resolution
      • remove_lighting: true

    Correggi la richiesta, poi inviala di nuovo. Vedi Errori.

  • Name
    401 - Unauthorized
    Description

    La chiave API è mancante o non valida. Controlla l'intestazione Authorization.

  • Name
    402 - Payment Required
    Description

    Ad esempio:

    • Insufficient credits: L'account non ha crediti sufficienti per questo task, oppure l'account ha raggiunto un limite di crediti. Controlla il tuo saldo crediti, poi riprova.
    • Free plan: Creare un task richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, poi riprova.
  • Name
    403 - Forbidden
    Description

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

  • Name
    429 - Too Many Requests
    Description

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


GET/openapi/v2/text-to-3d/:id

Recupera un task Testo in 3D

Restituisce un task Testo in 3D tramite il suo ID. Funziona sia per i task di preview che per quelli di refine.

Request

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

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": null,

  "consumed_credits": 20
}

Parametri

  • Name
    id
    Type
    path
    Description

    L'ID del task dalla risposta di creazione.

Restituisce

L'oggetto task Testo in 3D.

Esempi

La tabella seguente mostra un modello di esempio per ciascuna modalità.

ModalitàModello di esempio
PreviewPreview model
RefineRefined model

DELETE/openapi/v2/text-to-3d/:id

Elimina un'attività Testo in 3D

Elimina definitivamente un'attività Testo in 3D, inclusi i suoi modelli e dati. Non è possibile annullare un'eliminazione.

Request

DELETE
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-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à

L'eliminazione di 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.

L'eliminazione di un'attività in uno stato finale (SUCCEEDED, FAILED o CANCELED) non ne rimborsa i crediti.

Valori restituiti

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


GET/openapi/v2/text-to-3d

Elenca i task di Testo in 3D

Restituisce un elenco dei tuoi task di Testo in 3D.

Request

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

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": null,

    "consumed_credits": 20
  }
]

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'ordine di ordinamento.

    Valori disponibili:

    • +created_at: dal meno recente
    • -created_at: dal più recente

Restituisce

Un elenco paginato di oggetti task di Testo in 3D.


GET/openapi/v2/text-to-3d/:id/stream

Esegui lo streaming di un task Testo in 3D

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

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v2/text-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",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
  "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"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": null,

"consumed_credits": 20
}

Parametri

  • Name
    id
    Type
    path
    Description

    L'ID del task restituito dalla risposta di creazione.

Restituisce

Uno stream di oggetti task Testo in 3D sotto forma di Server-Sent Events.

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


L'oggetto task Testo in 3D

Un oggetto task Testo in 3D descrive un task che genera un modello 3D a partire da un prompt testuale. Contiene lo stato, il progress e i file del modello quando il task riesce. Testo in 3D ha due fasi, preview e refine. Un task preview genera un modello 3D composto solo da mesh, mentre un task refine genera un modello 3D con texture a partire dal risultato del preview.

Proprietà

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
    "fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": null,

  "consumed_credits": 20
}
  • 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, text-to-3d-preview per un task preview o text-to-3d-refine per un task refine.

  • 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, anziché avere una stringa vuota.

    • Name
      glb
      Type
      string
      Description

      Il file GLB.

    • Name
      fbx
      Type
      string
      Description

      Il file FBX.

    • Name
      usdz
      Type
      string
      Description

      Il file USDZ.

    • Name
      obj
      Type
      string
      Description

      Il file OBJ.

    • Name
      mtl
      Type
      string
      Description

      Il file MTL.

    • Name
      stl
      Type
      string
      Description

      Il file STL.

    • Name
      3mf
      Type
      string
      Description

      Il file 3MF. Presente solo quando target_formats include 3mf.

  • Name
    prompt
    Type
    string
    Description

    Il prompt che hai inviato per creare il task, invariato.

  • Name
    texture_prompt
    Type
    string
    Description

    Il prompt testuale che hai inviato per guidare la texturizzazione nella fase refine.

  • Name
    ultra_mode
    Type
    boolean
    ⚠ deprecato
    Description

    Fai riferimento invece a geometry_resolution.

  • Name
    geometry_resolution
    Type
    string
    Description

    Il livello Ultra con cui è stato eseguito il task preview, 2k o 4k. Il campo è assente per standard.

  • Name
    texture_image_url
    Type
    string
    Description

    URL di download per l'immagine inviata per guidare la texturizzazione.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL di download per un'immagine di anteprima (miniatura) del modello 3D.

  • 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
    progress
    Type
    integer
    Description

    Quanta parte del task è stata completata, in percentuale. È 0 finché il task non inizia ed 100 quando riesce.

  • 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
    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, come array di oggetti. Di solito contiene un oggetto. Ogni oggetto ha questi campi:

    • Name
      base_color
      Type
      string
      Description

      La mappa del colore di base.

    • Name
      metallic
      Type
      string
      Description

      La mappa metallica. Assente se hai creato il task con enable_pbr: false.

    • Name
      normal
      Type
      string
      Description

      La normal map. Assente se hai creato il task con enable_pbr: false.

    • Name
      roughness
      Type
      string
      Description

      La mappa di rugosità. Assente se hai creato il task con enable_pbr: false.

    • Name
      emission
      Type
      string
      Description

      La mappa di emissione. Assente in uno di questi casi:

      • Hai creato il task con enable_pbr: false.
      • ai_model è meshy-6-lite, meshy-7, meshy-7.1 o latest.
      • texture_resolution è 8k.
      • Il task esegue il refine di un preview meshy-t2 o meshy-t2.5 senza impostare ai_model.
  • 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. 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.