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

Crea 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 passaggio del flusso di lavoro in due fasi. Dopo che l'anteprima è riuscita, invia il suo ID attività in un'attività refine per applicare la texture alla mesh. Vedi Crea 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 sapere quanto tempo richiede di solito 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 passaggi. 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
Modelli Smart Topology (model_type: smart-topology):
- meshy-t2: topology più pulita, parti nativamente separate, 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
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 rifare 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 predominanza di quadrilateri
- triangle: una mesh triangolare decimata
L'output di Smart Topology è solo in triangoli. 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 puntare. Il risultato può differire dall'obiettivo, a seconda della geometria. Si applica in due casi distinti:
- Remesh: con should_remesh: true su un modello standard. Meshy rifà il remesh (decima) della mesh 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 serve should_remesh.
La tabella seguente mostra l'intervallo e il valore predefinito per ogni 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 inviarlo. 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
predefinito ""
Description
La posa del 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
Invia pose_mode al suo posto. Se generare il modello in posa A o in posa T.
Name
art_style
Type
string
⚠ deprecato
predefinito realistic
Description
Non inviarlo. Meshy lo ignora.
Name
moderation
Type
boolean
predefinito false
Description
Se controllare 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 recuperi l'attività. thumbnail_url non cambia.
Name
auto_size
Type
boolean
predefinito false
Description
Se stimare l'altezza reale dell'oggetto con la 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.

Restituisce

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 rilevato. 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 crediti sufficienti 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
429 - Too Many Requests
Description
Hai superato il limite di frequenza. Attendi, quindi riprova. Vedi Limiti di frequenza.

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

Crea un'attività di refine Testo in 3D

Crea un'attività di refine Testo in 3D, che applica la texture alla mesh di un'attività di anteprima completata. Invia l'ID di un'attività di anteprima riuscita come preview_task_id. Vedi Crea un'attività di anteprima Testo in 3D. Questo è il secondo passaggio del flusso di lavoro in due fasi.

L'attività viene eseguita in background. Per la durata tipica di un'attività, 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
}'

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'attività di refine.
Name
preview_task_id
Type
string
Obbligatorio
Description
L'ID dell'attività di anteprima a cui applicare la texture. L'attività di anteprima deve avere lo 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 mappa di emissione, tranne che con texture_resolution: 8k. meshy-6-lite, meshy-7, meshy-7.1 e latest non generano una mappa di emissione. Non la genera nemmeno un refine di un'anteprima meshy-t2 o meshy-t2.5 che non imposta ai_model.
Name
texture_resolution
Type
string
predefinito 2k
Description
La risoluzione della texture del colore base. Si applica solo alle attività di refine. Un'anteprima con questo parametro restituisce 400.
Valori disponibili:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
Risoluzioni più elevate catturano più dettagli della superficie. 4k e 8k richiedono ai_model meshy-6, meshy-7.1 o latest. A 8k, Meshy non genera una mappa di emissione.
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 l'applicazione 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.
Name
texture_image_url
Type
string
Description
Un'immagine 2D che guida l'applicazione 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.
L'applicazione della texture da un'immagine potrebbe non funzionare bene quando la forma nell'immagine differisce molto dal modello.
Name
ai_model
Type
string
predefinito inherited from the preview task
Description
Il modello IA che applica la texture alla mesh.
Valori disponibili:
- meshy-6-lite
- meshy-6
- meshy-7.1
- latest: Meshy 7.1
- meshy-7 (deprecato): invia meshy-7.1 al suo posto
Omettilo per usare il modello dell'attività di anteprima, in modo che l'anteprima e il suo refine vengano eseguiti sullo stesso modello dall'inizio alla fine. Invia un valore per sovrascriverlo. Un latest esplicito viene risolto nello stesso modo dell'attività di anteprima, quindi un'anteprima latest e il suo refine latest usano sempre lo stesso modello di texture.
Name
moderation
Type
boolean
predefinito false
Description
Se analizzare texture_prompt e texture_image_url per contenuti dannosi prima della generazione. Se Meshy rileva contenuti dannosi, la richiesta restituisce 400 e Meshy non crea l'attività.
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 un'illuminazione personalizzata.
Ha effetto solo quando ai_model è meshy-6. meshy-7.1 e latest lo accettano ma lo ignorano, così come un refine di un'anteprima meshy-t2 o meshy-t2.5 che non imposta ai_model. Inviarlo con meshy-6-lite 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 dell'attività. Se lo ometti, Meshy genera tutti i formati tranne 3mf, che genera solo se richiesto.
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 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.

Risultati restituiti

Il campo result della risposta contiene l'ID della nuova attività Testo 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:
- ID attività non valido: preview_task_id non è valido, oppure non corrisponde a una delle tue attività di anteprima.
- Attività non pronta: L'attività di anteprima non è ancora andata a buon fine.
- Modello non corrispondente: Il modello IA dell'attività di anteprima non è compatibile con il modello di refine richiesto.
- Modello non supportato per remove_lighting: remove_lighting è stato inviato con ai_model: "meshy-6-lite".
Correggi la richiesta, quindi 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:
- Crediti insufficienti: L'account non ha crediti sufficienti per questa attività, oppure 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
429 - Too Many Requests
Description
Hai superato il limite di frequenza. Attendi, quindi riprova. Vedi Limiti di frequenza.

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

Ottieni un'attività Testo in 3D

Restituisce un'attività Testo in 3D tramite il suo ID. Funziona sia per le attività di preview che per quelle 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": {

    "message": ""

  },

  "consumed_credits": 20
}

Parametri

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

Restituisce

L'oggetto attività Testo in 3D.

Esempi

La seguente tabella mostra un modello di esempio per ciascuna mode.

Mode	Modello di esempio
Preview
Refine

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

Elenco dei task Testo in 3D

Restituisce un elenco dei tuoi task 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": {

      "message": ""

    },

    "consumed_credits": 20
  }
]

Parametri

Name
page_num
Type
integer
predefinito 1
Description
Il numero di pagina da restituire.
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 Testo in 3D.

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

Esegui lo streaming di un'attività Testo in 3D

Trasmette in streaming gli aggiornamenti di un'attività 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": {

  "message": ""

},

"consumed_credits": 20
}

Parametri

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

Risultati restituiti

Un flusso di oggetti attività Testo in 3D come Server-Sent Events.

Ogni evento contiene l'oggetto attività completo, nello stesso formato restituito dall'endpoint Get. Mentre l'attività è PENDING o IN_PROGRESS, i suoi campi di risultato non hanno ancora un valore.

L'oggetto task di Testo in 3D

Un oggetto task di 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 ha successo. Testo in 3D ha due fasi, preview e refine. Un task di preview genera un modello 3D composto solo dalla mesh, mentre un task di refine genera un modello 3D con texture a partire dal risultato della 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": {

    "message": ""

  },

  "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 di preview o text-to-3d-refine per un task di refine.
Name
model_urls
Type
object
Description
URL di download per il modello 3D generato, uno per ogni formato di file. Un formato non generato dal task 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
  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 inviato per creare il task, invariato.
Name
texture_prompt
Type
string
Description
Il prompt testuale inviato per guidare la creazione delle texture nella fase di refine.
Name
ultra_mode
Type
boolean
⚠ deprecato
Description
Usa invece geometry_resolution.
Name
geometry_resolution
Type
string
Description
Il livello Ultra con cui è stato eseguito il task di 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 creazione delle texture.
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 quando hai creato il task con alpha_thumbnail: true e Meshy ha renderizzato l'anteprima trasparente.
Name
video_url
Type
string
⚠ deprecato
Description
Non fare affidamento su questo campo, perché una futura versione lo rimuoverà. URL di download per il video di anteprima.
Name
progress
Type
integer
Description
Quanto del task è completato, in percentuale. È 0 finché il task non inizia e 100 quando ha successo.
Name
started_at
Type
timestamp
Description
L'orario di inizio del task, in millisecondi Unix. È 0 finché il task non inizia.
Name
created_at
Type
timestamp
Description
L'orario di creazione del task, in millisecondi Unix.
Name
finished_at
Type
timestamp
Description
L'orario di fine del task, 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 base.
- Name
  metallic
  Type
  string
  Description
  La mappa metallica. Assente quando hai creato il task con enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  La normal map. Assente quando hai creato il task con enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  La mappa di rugosità. Assente quando 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 una 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. 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.