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.
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
# 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
previewper 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 dettagliosmart-topology: una mesh Smart Topology. Scegli il modello conai_model(meshy-t2omeshy-t2.5).
Con
smart-topology, Meshy ignorashould_remeshedecimation_mode, e accetta solotopology: 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-litemeshy-6meshy-7.1latest: Meshy 7.1meshy-7(deprecato): inviameshy-7.1al 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 contarget_polycountmeshy-t2.5(predefinito): dettaglio più nitido per asset di gioco, output in triangoli e un numero di facce che imposti contarget_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:
standard2k: esegue il passaggio Ultra a 2048³4k: esegue il passaggio Ultra a 4096³, per un dettaglio di superficie più fine
2krichiedemeshy-7.1,latest, o il deprecatomeshy-7.4krichiedemeshy-7.1olatest. Altri modelli restituiscono400.
- Name
- ultra_mode
- Type
- boolean
- ⚠ deprecato
- predefinito false
- Description
Invia
geometry_resolutional suo posto.ultra_mode: trueequivale ageometry_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.
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 quadrilateritriangle: una mesh triangolare decimata
L'output di Smart Topology è solo triangolare. Inviare
quadconai_modelmeshy-t2omeshy-t2.5restituisce400.
- Name
- decimation_mode
- Type
- integer
- Description
Numero di facce adattivo, per livello. Quando lo imposti, Meshy ignora
target_polycount.Valori disponibili:
1: ultra2: alto3: medio4: 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: truesu un modellostandard. Meshy sottopone la mesh a remesh (decimazione) fino a circa questo numero. Se impostidecimation_mode, Meshy lo usa e ignoratarget_polycount. - Smart Topology: con
model_type: smart-topologyeai_modelmeshy-t2omeshy-t2.5. Meshy genera il modello direttamente con questo numero di facce. Non viene eseguito alcun remesh e non è necessarioshould_remesh.
La tabella seguente mostra l'intervallo e il valore predefinito per ciascun caso:
Caso Intervallo Predefinito Remesh 100a30000030000meshy-t2100a150004000meshy-t2.5100a3000015000Un 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.
- Remesh: con
- Name
- symmetry_mode
- Type
- string
- ⚠ deprecato
- predefinito auto
- Description
Non includerlo. Questo parametro non influisce sull'output.
Valori disponibili:
off: disabilita la simmetriaauto: applica la simmetria in base alla geometria di inputon: impone la simmetria durante la generazione
- Name
- pose_mode
- Type
- string
- Description
La posa per un modello di personaggio,
a-poseot-pose. Per non avere alcuna posa, non includerepose_modeeis_a_t_pose.
- Name
- is_a_t_pose
- Type
- boolean
- ⚠ deprecato
- predefinito false
- Description
Invia
pose_modeal 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
promptper contenuti dannosi prima della generazione. Se Meshy rileva contenuti dannosi, la richiesta restituisce400e 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:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- predefinito false
- Description
Se generare anche un'anteprima con sfondo trasparente (RGBA), restituita in
alpha_thumbnail_urlquando ottieni l'attività.thumbnail_urlnon 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.
auto_size = true- Name
- origin_at
- Type
- string
- predefinito bottom
- Description
Dove posizionare l'origine del modello,
bottomocenter.
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
promptomode. - Prompt troppo lungo:
promptsupera il limite di caratteri. - Modello non supportato per Ultra:
geometry_resolutionè2ko4k, con unai_modelche non può eseguirlo.
Correggi la richiesta, quindi inviala di nuovo. Vedi Errori.
- Parametro mancante: manca un parametro obbligatorio, come
- 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.
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
# 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
refineper 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_modelmeshy-6, Meshy genera anche una emission map, tranne atexture_resolution: 8k.meshy-6-lite,meshy-7elatestnon generano una emission map. Non lo fa nemmeno un refine di una previewmeshy-t2omeshy-t2.5che non impostaai_model. Conai_model: meshy-n1,truerestituisce400.
- 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×20484k: 4096×40968k: 8192×8192
Risoluzioni più alte catturano più dettagli di superficie.
4ke8krichiedonoai_modelmeshy-6,meshy-7olatest. Conmeshy-n1, restituiscono400. A8k, Meshy non genera una emission map.
- Name
- hd_texture
- Type
- boolean
- ⚠ deprecato
- predefinito false
- Description
Invia
texture_resolutioninvece.hd_texture: trueequivale atexture_resolution: "4k". Se invii entrambi, Meshy usatexture_resolution.
- Name
- texture_prompt
- Type
- string
- Description
Testo che guida la creazione della texture, fino a 800 caratteri. Un testo più lungo restituisce
400. Inviatexture_promptotexture_image_url, non entrambi. Se invii entrambi, Meshy usatexture_prompt. Conai_model: meshy-n1, inviarlo restituisce400.
- 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,.pngo.webpdi 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.Applicare la 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. La mesh proviene dalla preview, quindi in un refine
ai_modelsceglie solo il modello di texture.Valori disponibili:
meshy-7: Meshy 7latest: il modello di texture più recente, ora Meshy 7meshy-6: Meshy 6meshy-6-lite: Meshy 6 Litemeshy-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 datexture_image_url. In sua assenza, Meshy usa l'immagine di riferimento memorizzata da una previewmeshy-7.1olatest. Qualsiasi altra preview restituisce400a meno che tu non inviitexture_image_url. La preview può avere al massimo 7.999.999 triangoli. Una preview sottoposta a remesh in quad restituisce400.
- Name
- moderation
- Type
- boolean
- predefinito false
- Description
Se analizzare
texture_promptetexture_image_urlalla ricerca di contenuti dannosi prima della generazione. Se Meshy rileva contenuti dannosi, la richiesta restituisce400e 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-7elatestlo accettano ma lo ignorano, così come un refine di una previewmeshy-t2omeshy-t2.5che non impostaai_model. Inviarlo conmeshy-6-literestituisce400. Conmeshy-n1,truerestituisce400.
- 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:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- predefinito false
- Description
Se generare anche un'anteprima con sfondo trasparente (RGBA), restituita in
alpha_thumbnail_urlquando recuperi il task.thumbnail_urlnon 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.
auto_size = true- Name
- origin_at
- Type
- string
- predefinito bottom
- Description
Dove posizionare l'origine del modello,
bottomocenter.
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_idnon è 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 conai_model: "meshy-6-lite". - No reference image for Meshy N1:
ai_model: meshy-n1è stato inviato senzatexture_image_url, e la preview non ha un'immagine di riferimento utilizzabile da Meshy N1. Inviatexture_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 altroai_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 altroai_model. - Unsupported option for Meshy N1:
ai_model: meshy-n1è stato inviato con una di queste opzioni:texture_promptenable_pbr: truetexture_resolutionpari a4ko8khd_texture: truesenzatexture_resolutionremove_lighting: true
Correggi la richiesta, poi inviala di nuovo. Vedi Errori.
- Invalid task ID:
- 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.
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
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
Esempi
La tabella seguente mostra un modello di esempio per ciascuna modalità.
| Modalità | Modello di esempio |
|---|---|
| Preview | ![]() |
| Refine | ![]() |
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
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.
Elenca i task di Testo in 3D
Restituisce un elenco dei tuoi task di Testo in 3D.
Request
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 restituisce400.
- 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.
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
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-previewper un task preview otext-to-3d-refineper 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_formatsinclude3mf.
- Name
- prompt
- Type
- string
- Description
Il
promptche 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,
2ko4k. Il campo è assente perstandard.
- 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_urlcon sfondo trasparente (RGBA). Presente solo se hai creato il task conalpha_thumbnail: truee Meshy ha renderizzato l'anteprima trasparente.
- Name
- progress
- Type
- integer
- Description
Quanta parte del task è stata completata, in percentuale. È
0finché il task non inizia ed100quando riesce.
- Name
- started_at
- Type
- timestamp
- Description
Momento in cui il task è iniziato, in millisecondi Unix. È
0finché 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. È
0finché il task non termina.
- Name
- status
- Type
- string
- Description
Lo stato del task, uno tra
PENDING,IN_PROGRESS,SUCCEEDED,FAILEDoCANCELED.
- 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.1olatest.texture_resolutionè8k.- Il task esegue il refine di un preview
meshy-t2omeshy-t2.5senza impostareai_model.
- Hai creato il task con
- 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. È
nulla meno che lo stato non siaFAILED. Vedi Errori.
- Name
- consumed_credits
- Type
- integer
- Description
Il numero di crediti utilizzati dal task. Presente quando lo stato è
PENDING,IN_PROGRESSoSUCCEEDED. È0per un taskFAILED, perché Meshy rimborsa i crediti quando un task fallisce.

