API Multi-immagine in 3D
Genera un modello 3D a partire da una fino a quattro immagini dello stesso oggetto, scattate da angolazioni diverse.
Crea un'attività Multi-immagine in 3D
Crea un'attività Multi-immagine in 3D. L'attività viene eseguita in background. Per la durata tipica di un'attività, vedi Tempi di elaborazione. Per i campi di un'attività, vedi L'oggetto attività Multi-immagine in 3D.
Request
# Simple request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_urls": [
"<your publicly accessible image url or base64-encoded data URI>",
"<your second publicly accessible image url or base64-encoded data URI>"
]
}'
# With Ultra 2K geometry, PBR texturing, and GLB format
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_urls": [
"<your publicly accessible image url or base64-encoded data URI>",
"<your second publicly accessible image url or base64-encoded data URI>"
],
"ai_model": "meshy-7.1",
"geometry_resolution": "2k",
"should_texture": true,
"enable_pbr": true,
"target_formats": ["glb"]
}'
# Textured with Meshy N1 from the input images, the first as the front view
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_urls": [
"<your front view image url or base64-encoded data URI>",
"<your back view image url or base64-encoded data URI>"
],
"ai_model": "meshy-7.1",
"texture_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Parametri
- Name
- input_task_id
- Type
- string
- Obbligatorio
- Description
Obbligatorio a meno che tu non invii
image_urls. L'ID di un'attività Testo in immagine o Immagine in immagine, inclusa una multi-vista. Meshy usa le sue da una a quattro immagini come input. L'attività deve essere una creata da te con l'API e avere lo statoSUCCEEDED.
- Name
- image_urls
- Type
- array
- Obbligatorio
- Description
Obbligatorio a meno che tu non invii
input_task_id. Da una a quattro immagini, ciascuna come URL pubblico o Data URI, ad esempiodata:image/jpeg;base64,<i tuoi dati immagine codificati in base64>. Se invii entrambi, Meshy usainput_task_id.Ogni immagine deve essere un file
.jpg,.jpeg,.pngo.webpdi al massimo 20 MB, con almeno 32 pixel per lato e al massimo 178.956.970 pixel (larghezza × altezza). Più di quattro immagini restituisce400.Per i migliori risultati, le immagini dovrebbero mostrare lo stesso oggetto da angolazioni diverse. Con
meshy-7.1olatest, Meshy usa la prima immagine come vista frontale, e l'ordine delle altre non ha importanza.
- Name
- ai_model
- Type
- string
- predefinito latest
- Description
Il modello AI che genera il modello 3D.
Valori disponibili:
latest: Meshy 7.1meshy-7.1meshy-6meshy-6-litemeshy-7: deprecato, inviameshy-7.1al suo posto. Va in pensione il 31 dicembre 2026.
Vedi Modelli per sapere quale modello si adatta al tuo progetto, ad esempio un oggetto reale o una stampa 3D.
- Name
- geometry_resolution
- Type
- string
- predefinito standard
- Description
Quanto dettaglio geometrico generare.
Valori disponibili:
standard2k: esegue il passaggio Ultra a 2048³. Richiedemeshy-7.1,latest, o il deprecatomeshy-7.
- Name
- ultra_mode
- Type
- boolean
- ⚠ deprecato
- predefinito false
- Description
Invia
geometry_resolutional suo posto.ultra_mode: trueequivale ageometry_resolution: "2k".
- Name
- should_texture
- Type
- boolean
- predefinito true
- Description
Se generare le texture.
truerestituisce un modello con texture, mentrefalsesalta il passaggio di texturizzazione e restituisce una mesh senza texture.
should_texture = true- Name
- texture_model
- Type
- string
- predefinito depends on ai_model
- Description
Il modello AI che applica la texture al modello 3D da più viste, nella stessa attività. Ometterlo per usare il modello di texture predefinito per il tuo
ai_model. Non modifica il costo in crediti.Valori disponibili:
meshy-7: Meshy 7, con mappe PBR e texture fino a 8Kmeshy-n1: Meshy N1, una texture base color 2K solo da immagini di riferimento
Ogni
ai_modelaccetta entrambi. Una richiesta con texture conmeshy-6omeshy-6-literestituisce400, così come un'opzione non supportata dal modello di texture scelto. Conshould_texture: false, Meshy ignoratexture_model, ma un valore sconosciuto restituisce comunque400.Con
meshy-n1, Meshy applica la texture datexture_image_urlsotexture_image_url, oppure dalle immagini di input quando non invii nessuno dei due. La prima immagine è la vista frontale. Un modello generato con oltre 7.999.999 triangoli fa fallire l'attività, e Meshy rimborsa i crediti.Vedi Modelli per sapere cosa fa ogni modello di texture e quale scegliere.
- Name
- enable_pbr
- Type
- boolean
- predefinito false
- Description
Se generare anche le mappe metallic, roughness e normal, oltre al base color. Il modello di texture Meshy 6 genera anche una mappa emission, tranne a
texture_resolution: 8k. Contexture_model: meshy-n1,truerestituisce400.
- Name
- texture_resolution
- Type
- string
- predefinito 2k
- Description
La dimensione della texture base color. Una dimensione maggiore cattura più dettaglio superficiale.
Valori disponibili:
2k: 2048×20484k: 4096×40968k: 8192×8192
4ke8krichiedono il modello di texture Meshy 7 o Meshy 6, e restituiscono400con gli altri. A8k, Meshy non genera una mappa emission.
- Name
- hd_texture
- Type
- boolean
- ⚠ deprecato
- predefinito false
- Description
Invia
texture_resolutional suo posto.hd_texture: trueequivale atexture_resolution: "4k". Se invii entrambi, Meshy usatexture_resolution.
- Name
- texture_prompt
- Type
- string
- Description
Testo che guida la texture, fino a 800 caratteri. Un testo più lungo restituisce
400. Contexture_model: meshy-n1, inviarlo restituisce400.
- Name
- texture_image_url
- Type
- string
- Description
Un'immagine 2D che guida la texture, come URL pubblico o Data URI, ad esempio
data:image/jpeg;base64,<i tuoi dati immagine codificati in base64>. L'immagine deve essere un file.jpg,.jpeg,.pngo.webpdi al massimo 20 MB, con almeno 32 pixel per lato e al massimo 178.956.970 pixel (larghezza × altezza).Se invii sia
texture_image_urlchetexture_prompt, Meshy usatexture_prompt. Contexture_model: meshy-n1, Meshy applica la texture da questa immagine come vista frontale.La texture potrebbe non riuscire bene quando la forma nell'immagine differisce molto dal modello 3D.
- Name
- texture_image_urls
- Type
- string[]
- Description
Da una a quattro immagini dell'oggetto da viste diverse che guidano la texture. Meshy usa la prima immagine come vista frontale. L'ordine delle altre viste (sinistra, retro, destra) non ha importanza.
Ogni immagine segue le stesse regole di
texture_image_url. È un URL pubblico o un Data URI, in formato.jpg,.jpeg,.pngo.webp, di al massimo 20 MB, con almeno 32 pixel per lato e al massimo 178.956.970 pixel (larghezza × altezza).Queste immagini guidano solo la texture e non dipendono da
image_urls. I due elenchi possono contenere immagini diverse e numeri diversi di immagini.texture_image_urlsrichiede il modello di texture Meshy 7 o Meshy N1. Inviala insieme a uno di questi:ai_modelpari ameshy-7.1,latest, o il deprecatomeshy-7texture_modelpari ameshy-7omeshy-n1
Non puoi inviarla insieme a
texture_image_urlotexture_prompt.
- Name
- should_remesh
- Type
- boolean
- predefinito true (meshy-6-lite), false (other models)
- Description
Se rifare il remesh del modello dopo la generazione. Per il modello 3D di qualità più alta, impostalo su
false.
should_remesh = true- Name
- topology
- Type
- string
- predefinito triangle
- Description
Il tipo di faccia del modello dopo il remesh.
Valori disponibili:
quad: una mesh a dominanza di quadrilateritriangle: una mesh a triangoli decimata
Con
texture_model: meshy-n1,quadrestituisce400quando il modello viene sottoposto a remesh, cosa chemeshy-6-litefa per impostazione predefinita.
- Name
- target_polycount
- Type
- integer
- predefinito 30000
- Description
Il numero di facce a cui puntare, da
100a300000. Il risultato può differire dal target, a seconda della geometria del modello. Un valore fuori dall'intervallo restituisce400.
- 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
- save_pre_remeshed_model
- Type
- boolean
- predefinito false
- Description
Se salvare anche il GLB precedente al remesh, restituito in
model_urls.pre_remeshed_glb.
- Name
- symmetry_mode
- Type
- string
- ⚠ deprecato
- predefinito auto
- Description
Ometterlo. Non influisce sull'output.
Valori disponibili:
off: nessuna simmetriaauto: simmetria basata sulla geometria di inputon: simmetria forzata
- Name
- pose_mode
- Type
- string
- Description
La posa per un modello di personaggio,
a-poseot-pose. Per non avere alcuna posa, omettipose_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 T.
- Name
- image_enhancement
- Type
- boolean
- predefinito true
- Description
Se ottimizzare le immagini di input prima della generazione.
falsemantiene l'aspetto esatto delle immagini di input, senza alcuna elaborazione dello stile. Supportato solo conmeshy-6,meshy-7.1olatest. Inviarlo conmeshy-6-literestituisce400.
- Name
- remove_lighting
- Type
- boolean
- predefinito true
- Description
Se rimuovere luci e ombre dalla texture base color. Il risultato più pulito funziona meglio con la tua illuminazione. Lo usa solo il modello di texture Meshy 6, e a
texture_resolution: 8krimuove sempre l'illuminazione. Contexture_model: meshy-n1,truerestituisce400. Conai_model: meshy-6-litee il suo modello di texture predefinito, inviarlo restituisce400.
- Name
- moderation
- Type
- boolean
- predefinito false
- Description
Se analizzare gli input alla ricerca di contenuti dannosi. Meshy analizza ogni immagine di input,
texture_image_urlo ciascuna immagine intexture_image_urls, e il testo intexture_prompt. Se Meshy trova contenuti dannosi, la richiesta restituisce400e Meshy non crea un'attività.
- Name
- target_formats
- Type
- string[]
- Description
I formati di file 3D da generare. Meshy genera e restituisce solo i formati elencati, il che può ridurre la durata dell'attività.
Valori disponibili:
glbobjfbxstlusdz3mf
Se lo ometti, Meshy genera tutti i formati tranne
3mf. Meshy genera3mfsolo quando lo elenchi.
- Name
- auto_size
- Type
- boolean
- predefinito false
- Description
Se stimare l'altezza reale dell'oggetto con la visione AI e ridimensionare il modello di conseguenza. Meshy posiziona l'origine in basso a meno che tu non imposti
origin_at.
auto_size = true- Name
- origin_at
- Type
- string
- predefinito bottom
- Description
Dove posizionare l'origine del modello,
bottomocenter.
- Name
- alpha_thumbnail
- Type
- boolean
- predefinito false
- Description
Se rendere anche un'anteprima con sfondo trasparente (RGBA), restituita in
alpha_thumbnail_urlquando ottieni l'attività.thumbnail_urlnon cambia.
- Name
- multi_view_thumbnails
- Type
- boolean
- predefinito false
- Description
Se rendere anche le anteprime frontale, destra, posteriore e sinistra, restituite in
thumbnail_urlsquando ottieni l'attività.thumbnail_urlnon cambia e mostra ancora la vista frontale. Questo aggiunge circa 5 secondi all'attività.
Valori restituiti
Il campo result della risposta contiene l'ID della nuova attività Multi-immagine in 3D.
Modalità di errore
- Name
400 - Bad Request- Description
La richiesta non può essere eseguita. Il messaggio di errore indica quale problema è stato rilevato. Ad esempio:
- Parametro mancante: non è stato inviato né
image_urlsnéinput_task_id. - Attività di input non valida:
input_task_idnon è un'attività Testo in immagine o Immagine in immagine con statoSUCCEEDED, né una multi-vista. - Numero di immagini non valido:
image_urlsotexture_image_urlsnon contiene da 1 a 4 immagini. - Formato immagine non valido: un'immagine in
image_urlsnon è in un formato supportato. - Input di texture in conflitto:
texture_image_urlsè stato inviato insieme atexture_image_url, atexture_prompt, o ashould_texture: false. - Modello non supportato per texture multi-vista:
texture_image_urlsè stato inviato conai_modelpari ameshy-6omeshy-6-lite, a meno chetexture_modelnon siameshy-7omeshy-n1. - URL non raggiungibile: Meshy non riesce a scaricare un'immagine in
image_urlsotexture_image_urls. - Immagine troppo grande: un'immagine in
image_urls,texture_image_urlotexture_image_urlssupera 20 MB. - Dimensione immagine non valida: un'immagine in
image_urls,texture_image_urlotexture_image_urlsha un lato più corto di 32 pixel, oppure più di 178.956.970 pixel (larghezza × altezza). - Risoluzione non supportata per input multi-immagine:
geometry_resolutionè"4k", che questo endpoint non supporta. Usa2kostandard. - Modello non supportato per le opzioni immagine:
image_enhancementè stato inviato conai_model: "meshy-6-lite", oppureremove_lightingè stato inviato conai_model: "meshy-6-lite"e il suo modello di texture predefinito. - Modello di texture non valido:
texture_modelnon è un nome di modello di texture valido. - Modello di texture non disponibile: una richiesta con texture ha inviato
texture_modelpari ameshy-6omeshy-6-lite. Multi-immagine in 3D accetta solo i modelli di texture che applicano la texture da più viste. Inviameshy-7omeshy-n1, oppure omettitexture_model. - Opzione non supportata per il modello di texture: la richiesta chiede al modello di texture un'opzione che non supporta, ad esempio
enable_pbr: trueconmeshy-n1o una texture4kconmeshy-6-lite. Vedi Modelli.
Correggi la richiesta, quindi inviala di nuovo. Vedi Errori.
- Parametro mancante: non è stato inviato né
- Name
401 - Unauthorized- Description
La chiave API è mancante o non valida. Controlla l'header
Authorization.
- Name
402 - Payment Required- Description
Ad esempio:
- Crediti insufficienti: l'account non ha crediti sufficienti per questa attività, oppure l'account ha raggiunto un limite di crediti. Controlla il tuo saldo crediti, quindi riprova.
- Piano gratuito: creare un'attività richiede un piano a pagamento. Aggiorna il tuo piano nelle impostazioni dell'abbonamento, quindi riprova.
- Name
403 - Forbidden- Description
La moderazione dei contenuti ha bloccato il prompt o un'immagine di input. Modifica l'input, quindi riprova.
- Name
404 - Not Found- Description
input_task_idnon corrisponde a nessuna delle tue attività. Controlla l'ID dell'attività, quindi invia di nuovo la richiesta.
- Name
429 - Too Many Requests- Description
Hai superato il limite di frequenza. Attendi, quindi riprova. Vedi Limiti di frequenza.
Ottenere un task Multi-immagine in 3D
Restituisce un task Multi-immagine in 3D in base al suo ID.
Request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "multi-image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
Parametri
- Name
- id
- Type
- path
- Description
L'ID del task ottenuto dalla risposta di creazione.
Valori restituiti
Elimina un'attività Multi-immagine in 3D
Elimina definitivamente un'attività Multi-immagine in 3D, inclusi i suoi modelli e dati. Non puoi annullare un'eliminazione.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
"message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
Parametri del percorso
- Name
- id
- Type
- path
- Description
L'ID dell'attività da eliminare.
Stato dell'attività
Eliminare un'attività PENDING rimborsa i crediti utilizzati al momento della sua creazione.
Un'attività IN_PROGRESS non può essere eliminata. La richiesta restituisce 409 Conflict,
e l'attività continua a essere eseguita. Meshy non rimborsa un'attività già avviata,
quindi eliminarla ti farebbe perdere sia i crediti che il risultato. Attendi che
raggiunga lo stato SUCCEEDED, FAILED o CANCELED, quindi eliminala.
Eliminare un'attività in uno stato finale (SUCCEEDED, FAILED o CANCELED)
non rimborsa i suoi crediti.
Restituisce
200 OK quando l'attività viene eliminata, oppure 409 Conflict quando l'attività è
IN_PROGRESS.
Elenca i task di Multi-immagine in 3D
Restituisce un elenco dei tuoi task di Multi-immagine in 3D.
Request
curl https://api.meshy.ai/openapi/v1/multi-image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "multi-image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
]
Parametri
- Name
- page_num
- Type
- integer
- predefinito 1
- Description
Il numero di pagina da restituire, fino a
255. Un valore maggiore 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'ordinamento.
Valori disponibili:
+created_at: dal più vecchio al più recente-created_at: dal più recente al più vecchio
Restituisce
Un elenco paginato di oggetti task Multi-immagine in 3D.
Esegui lo streaming di un task Multi-immagine in 3D
Trasmette in streaming gli aggiornamenti di un task Multi-immagine in 3D come Server-Sent Events (SSE).
Request
curl -N https://api.meshy.ai/openapi/v1/multi-image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Error event example
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "multi-image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
Parametri
- Name
- id
- Type
- path
- Description
L'ID del task dalla risposta di creazione.
Valori restituiti
Uno stream di oggetti task Multi-immagine in 3D come Server-Sent Events.
Ogni evento contiene l'oggetto task completo, nella stessa forma restituita dall'endpoint Get. Mentre il task è PENDING o IN_PROGRESS, i suoi campi di risultato non hanno ancora valori.
L'oggetto task Multi-immagine in 3D
Un oggetto task Multi-immagine in 3D descrive una generazione di un modello 3D a partire da una a quattro immagini di un oggetto. Contiene lo stato, il progress e i file del modello quando il task ha successo.
Proprietà
Example Multi-Image to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "multi-image-to-3d",
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***",
"pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"thumbnail_urls": {
"front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
"right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
"back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
"left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
},
"texture_prompt": "",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"expires_at": 1692771679037,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 30
}
- Name
- id
- Type
- string
- Description
L'ID del task. Trattalo come una stringa opaca e non fare affidamento sul suo formato.
- Name
- type
- Type
- string
- Description
Il tipo di task, sempre
multi-image-to-3d.
- Name
- model_urls
- Type
- object
- Description
URL di download per il modello 3D generato, uno per ogni formato di file. Un formato che il task non ha generato non ha una chiave, piuttosto che una stringa vuota.
- Name
glb- Type
- string
- Description
Il file GLB.
- Name
fbx- Type
- string
- Description
Il file FBX.
- Name
obj- Type
- string
- Description
Il file OBJ.
- Name
usdz- Type
- string
- Description
Il file USDZ.
- Name
mtl- Type
- string
- Description
Il file MTL, restituito insieme al file OBJ quando il modello ha delle texture.
- Name
stl- Type
- string
- Description
Il file STL.
- Name
3mf- Type
- string
- Description
Il file 3MF. Presente solo quando
target_formatsinclude3mf.
- Name
pre_remeshed_glb- Type
- string
- Description
Il file GLB precedente al remesh. Presente solo quando hai creato il task con sia
should_remesh: truechesave_pre_remeshed_model: true.
- Name
- thumbnail_url
- Type
- string
- Description
URL di download per un'immagine di anteprima del modello. È identico a
thumbnail_urls.frontquando quel campo è presente.
- Name
- alpha_thumbnail_url
- Type
- string
- Description
URL di download per una versione di
thumbnail_urlcon sfondo trasparente (RGBA). Presente solo quando hai creato il task conalpha_thumbnail: truee Meshy ha renderizzato l'anteprima trasparente.
- Name
- thumbnail_urls
- Type
- object
- Description
URL di download per le anteprime del modello 3D da quattro lati. Ognuno è un URL firmato a un'immagine PNG 512×512, renderizzata con gli stessi materiali e la stessa illuminazione di
thumbnail_url. Puoi usarli per visualizzare in anteprima il modello da più angolazioni senza scaricare il GLB.Presente solo quando hai creato il task con
multi_view_thumbnails: truee il task ha raggiunto lo statoSUCCEEDED. Un task creato senzamulti_view_thumbnails: truenon ha questo campo.- Name
- front
- Type
- string
- Description
La vista frontale, a 0° attorno all'asse verticale. Corrisponde a
thumbnail_url.
- Name
- right
- Type
- string
- Description
La vista destra, a 90°.
- Name
- back
- Type
- string
- Description
La vista posteriore, a 180°.
- Name
- left
- Type
- string
- Description
La vista sinistra, a 270°.
- Name
- texture_prompt
- Type
- string
- Description
Il prompt testuale che ha guidato la texture.
- Name
- texture_image_urls
- Type
- string[]
- Description
URL di download per le immagini di riferimento della texture con cui hai creato il task, nell'ordine in cui le hai inviate. Presente solo quando hai creato il task con
texture_image_urls.
- Name
- ultra_mode
- Type
- boolean
- ⚠ deprecato
- Description
Leggi invece
geometry_resolution.
- Name
- geometry_resolution
- Type
- string
- Description
Il livello Ultra con cui è stato eseguito il task, ossia
2k. Un taskstandardnon ha questo campo.
- Name
- progress
- Type
- integer
- Description
Quanto del task è stato completato, in percentuale. È
0finché il task non inizia e100quando ha successo.
- 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
- expires_at
- Type
- timestamp
- Description
Momento in cui i risultati del task scadono, in millisecondi Unix.
- Name
- finished_at
- Type
- timestamp
- Description
Momento in cui il task è terminato, in millisecondi Unix. È
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 dal task, come un array di oggetti. Di solito contiene un solo oggetto. Ogni oggetto ha questi campi:
- Name
base_color- Type
- string
- Description
La mappa del colore base.
- Name
metallic- Type
- string
- Description
La mappa metallica. Non inclusa quando hai creato il task con
enable_pbr: false.
- Name
normal- Type
- string
- Description
La normal map. Non inclusa quando hai creato il task con
enable_pbr: false.
- Name
roughness- Type
- string
- Description
La mappa di rugosità. Non inclusa quando hai creato il task con
enable_pbr: false.
- Name
emission- Type
- string
- Description
La mappa di emissione. Inclusa solo quando hai creato il task con tutti i seguenti elementi:
ai_model: meshy-6, con il suo modello di texture predefinitoenable_pbr: true- un
texture_resolutiondi2ko4k
- 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. Consulta 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.