API Immagine in 3D
Trasforma un'immagine in un modello 3D, con o senza texture, nei formati che preferisci. Invia l'immagine, oppure utilizza l'output di un task Testo in immagine o Immagine in immagine.
Crea un'attività Immagine in 3D
Crea un'attività Immagine in 3D. L'attività viene eseguita in background. Per sapere quanto tempo richiede di solito un'attività, consulta Tempi di elaborazione.
Request
# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>"
}'
# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible image url or base64-encoded data URI>",
"ai_model": "meshy-7.1",
"geometry_resolution": "4k",
"enable_pbr": true,
"should_remesh": true,
"target_polycount": 100000,
"should_texture": true,
"pose_mode": "a-pose",
"target_formats": ["glb"]
}'
# Textured with Meshy N1 from the input image
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${YOUR_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"image_url": "<your publicly accessible 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 non invii
image_url. L'ID di un'attività Testo in immagine o Immagine in immagine la cui immagine vuoi usare come input. L'attività deve essere una che hai creato con l'API, deve avere lo statoSUCCEEDEDe deve aver prodotto esattamente un'immagine.
- Name
- image_url
- Type
- string
- Obbligatorio
- Description
Obbligatorio a meno che non invii
input_task_id. L'immagine da trasformare in un modello 3D, come URL pubblico o data URI codificato in base64, ad esempiodata:image/jpeg;base64,<i tuoi dati immagine codificati in base64>. Se invii entrambi, Meshy usainput_task_id.L'immagine deve essere un file JPG, JPEG, PNG o WebP di al massimo 20 MB, di almeno 32 pixel per lato e di al massimo 178.956.970 pixel (larghezza × altezza).
- Name
- model_type
- Type
- string
- predefinito standard
- Description
Il tipo di mesh 3D da generare.
Valori disponibili:
standard: una mesh ad alto dettagliosmart-topology: una mesh da un modello Smart Topology, che scegli conai_model(meshy-t2omeshy-t2.5)
Con
smart-topology, Meshy ignorashould_remesh,save_pre_remeshed_modeledecimation_mode, e accetta solotopology: triangle.
- Name
- ai_model
- Type
- string
- predefinito latest
- Description
Il modello IA che genera il modello 3D. I valori disponibili dipendono da
model_type.Modelli standard (
model_type: standard):latest: Meshy 7.1meshy-7.1meshy-6meshy-6-litemeshy-7(deprecato): usa invecemeshy-7.1. Verrà ritirato il 31 dicembre 2026.
I modelli Smart Topology (
model_type: smart-topology) producono triangoli, con un numero di facce che puoi impostare contarget_polycount:meshy-t2: topology più pulita e parti naturalmente separatemeshy-t2.5(predefinito): dettaglio più nitido per asset di gioco
Consulta 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.
Valori disponibili:
standard2k: esegue il passaggio Ultra a 2048³4k: esegue il passaggio Ultra a 4096³, per il massimo dettaglio superficiale
2krichiedemeshy-7.1,latest, o il deprecatomeshy-7.4krichiedemeshy-7.1olatest.
- Name
- ultra_mode
- Type
- boolean
- ⚠ deprecato
- predefinito false
- Description
Usa invece
geometry_resolution.ultra_mode: trueequivale ageometry_resolution: "2k".
- Name
- should_texture
- Type
- boolean
- predefinito true
- Description
Se generare le texture.
truerestituisce un modello con texture, mentrefalsesalta la texturizzazione e restituisce una mesh senza texture.
should_texture = true- Name
- texture_model
- Type
- string
- predefinito depends on ai_model
- Description
Il modello IA che applica le texture al modello 3D, nella stessa attività. Omettilo 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 di colore base a 2K generata solo da immagini di riferimentomeshy-6-lite: Meshy 6 Lite, una texture a 2K al costo più bassomeshy-6: Meshy 6, solo come predefinito perai_model: meshy-6
Ogni
ai_modelaccettameshy-7,meshy-n1emeshy-6-lite. Un'opzione non supportata dal modello di texture scelto restituisce400. Conmeshy-n1, un modello generato con oltre 7.999.999 triangoli fa fallire l'attività, e Meshy rimborsa i relativi crediti. Conshould_texture: false, Meshy ignoratexture_model, ma un valore sconosciuto restituisce comunque400.Consulta Modelli per sapere cosa fa ciascun modello di texture e quale scegliere.
- Name
- enable_pbr
- Type
- boolean
- predefinito false
- Description
Se generare anche le mappe PBR (metallic, roughness e normal) oltre al colore base.
truerichiedeshould_texture: true, e restituisce400conshould_texture: false. Contexture_model: meshy-n1,truerestituisce400.Il modello di texture Meshy 6 genera anche una mappa di emissione, tranne con
texture_resolution: 8k.
- Name
- texture_resolution
- Type
- string
- predefinito 2k
- Description
La dimensione della texture di colore base. Una texture più grande cattura più dettagli superficiali.
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 produce una mappa di emissione.
- Name
- hd_texture
- Type
- boolean
- ⚠ deprecato
- predefinito false
- Description
Usa invece
texture_resolution.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 che guida la texture, come URL pubblico o 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 al massimo 20 MB, di almeno 32 pixel per lato e di al massimo 178.956.970 pixel (larghezza × altezza).Meshy guida la texture con uno solo tra
texture_promptetexture_image_url. Se invii entrambi, Meshy usatexture_prompt. Per il costo in crediti della texturizzazione, consulta Prezzi.Con
texture_model: meshy-n1, Meshy applica la texture da questa immagine come vista frontale, oppure dall'immagine di input quando la ometti.La texturizzazione a partire da un'immagine potrebbe non funzionare bene quando la forma dell'immagine differisce molto dalla geometria del modello 3D.
- Name
- should_remesh
- Type
- boolean
- predefinito true (meshy-6-lite), false (other models)
- Description
Se eseguire la fase di remesh. Per il modello 3D della massima qualità, impostalo su
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 prevalenza di quadrilateritriangle: una mesh triangolare decimata
L'output di Smart Topology è solo triangolare, quindi
quadconmeshy-t2omeshy-t2.5restituisce400. Contexture_model: meshy-n1,quadrestituisce400quando il modello viene sottoposto a remesh, cosa chemeshy-6-litefa per impostazione predefinita.
- 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 memorizzare anche un GLB del modello da prima della fase di remesh. Meshy lo restituisce in
model_urls.pre_remeshed_glb.
- Name
- target_polycount
- Type
- integer
- Description
Il numero di facce a cui mirare. Il risultato può differire dall'obiettivo, a seconda della geometria del modello.
Si applica in due casi distinti:
- Remesh: Quando
should_remeshètruesu un modellostandard, Meshy decima la mesh fino a circa questo numero. Se impostidecimation_mode, Meshy lo usa e ignoratarget_polycount. - Smart Topology: Quando
model_typeèsmart-topologyeai_modelèmeshy-t2omeshy-t2.5, Meshy genera il modello con questo numero di facce. Non viene eseguito alcun remesh, e non è necessarioshould_remesh.
L'intervallo e il valore predefinito dipendono dal caso:
Caso Intervallo Predefinito Remesh 100-30000030000meshy-t2100-150004000meshy-t2.5100-3000015000Un 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. Consulta Modelli.
- Remesh: Quando
- Name
- symmetry_mode
- Type
- string
- ⚠ deprecato
- predefinito auto
- Description
Omettilo, perché non influisce sull'output. I suoi valori controllavano la simmetria durante la generazione:
off: nessuna simmetriaauto: simmetria scelta in base alla 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
Usa invece
pose_mode. Se generare il modello in posa A o T.
- Name
- surface_mode
- Type
- string
- ⚠ deprecato
- Description
Usa invece
ai_model. Non influisce sull'output, perché la generazione del modello che selezionava è stata ritirata.I valori accettati sono
organicehard. Qualsiasi altro valore restituisce400.
- Name
- image_enhancement
- Type
- boolean
- predefinito true
- Description
Se ottimizzare l'immagine di input prima della generazione.
falsemantiene l'aspetto esatto dell'immagine di input, senza alcuna elaborazione di stile.Funziona solo con
meshy-6,meshy-7.1olatest. Conmeshy-6-liteomodel_type: smart-topology, restituisce400.
- Name
- remove_lighting
- Type
- boolean
- predefinito true
- Description
Se rimuovere luci e ombre dalla texture di colore base. Il risultato è più pulito e funziona meglio con la tua illuminazione.
Ha effetto solo con il modello di texture Meshy 6, e un modello di texture che non lo supporta restituisce
400pertrue. Conmodel_type: smart-topology, o conai_model: meshy-6-litee il suo modello di texture predefinito, inviarlo restituisce400.
- Name
- moderation
- Type
- boolean
- predefinito false
- Description
Se analizzare questi input per contenuti dannosi prima della generazione:
image_urltexture_image_urltexture_prompt
Se Meshy rileva contenuti dannosi, la richiesta restituisce
400e Meshy non crea un'attività.
- Name
- target_formats
- Type
- string[]
- Description
I formati di file da generare. Meshy genera e restituisce solo i formati che elenchi, il che può ridurre la durata dell'attività. Se lo ometti, Meshy genera ogni formato tranne
3mf, che ottieni solo se lo elenchi.Valori disponibili:
glbobjfbxstlusdz3mf
- Name
- auto_size
- Type
- boolean
- predefinito false
- Description
Se stimare l'altezza reale dell'oggetto con la visione IA e ridimensionare il modello di conseguenza. Meshy posiziona l'origine in basso a meno che non imposti
origin_at.
- Name
- alpha_thumbnail
- Type
- boolean
- predefinito false
- Description
Se renderizzare anche un'anteprima con sfondo trasparente (RGBA), restituita in
alpha_thumbnail_urlquando recuperi l'attività.thumbnail_urlnon cambia.
- Name
- multi_view_thumbnails
- Type
- boolean
- predefinito false
- Description
Se renderizzare anche le anteprime frontale, destra, posteriore e sinistra, restituite in
thumbnail_urlsquando recuperi l'attività.thumbnail_urlnon cambia e mostra ancora la vista frontale. Questo aggiunge circa 5 secondi all'attività.
auto_size = true- Name
- origin_at
- Type
- string
- predefinito bottom
- Description
Dove posizionare l'origine del modello,
bottomocenter.
Restituisce
Il campo result della risposta contiene l'ID della nuova attività 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_urlnéinput_task_id. - Attività di input non valida:
input_task_idnon è un'attività Testo in immagine o Immagine in immagine con statoSUCCEEDEDche ha prodotto esattamente un'immagine. - Formato immagine non valido: L'immagine
image_urlnon è un file JPG, JPEG, PNG o WebP. - URL non raggiungibile: Meshy non riesce a scaricare l'immagine
image_url, perché l'URL restituisce404o va in timeout. - Immagine troppo grande: L'immagine
image_urlotexture_image_urlsupera i 20 MB. - Dimensioni immagine non valide: L'immagine
image_urlotexture_image_urlha un lato più corto di 32 pixel, o più di 178.956.970 pixel (larghezza × altezza). - Data URI non valido: La stringa base64 è malformata.
- Combinazione di parametri non valida:
enable_pbrètrue, eshould_textureèfalse. - Modello non supportato per Ultra:
geometry_resolutionè2ko4k, con unai_modelche non può eseguirlo. - Modello non supportato per le opzioni immagine: uno dei seguenti:
image_enhancementè stato inviato conai_model: "meshy-6-lite"omodel_type: "smart-topology".remove_lightingè stato inviato conmodel_type: "smart-topology", oppure conai_model: "meshy-6-lite"e il suo modello di texture predefinito.
- Modello di texture non valido:
texture_modelnon è uno dei valori disponibili. - Modello di texture non disponibile:
texture_modelèmeshy-6con unai_modeldiverso dameshy-6. Inviameshy-7,meshy-n1omeshy-6-lite, oppure omettilo. - 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. Consulta Modelli.
Correggi la richiesta, quindi inviala di nuovo. Consulta 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 tuo limite di frequenza. Attendi, quindi riprova. Consulta Limiti di frequenza.
Recupera un task Immagine in 3D
Restituisce un task Immagine in 3D in base al suo ID.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "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",
"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": 30
}
Parametri
- Name
- id
- Type
- path
- Description
L'ID del task restituito dalla risposta di creazione.
Restituisce
Elimina un task Immagine in 3D
Elimina definitivamente un task Immagine in 3D, inclusi i suoi modelli e i relativi dati. Non puoi annullare un'eliminazione.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v1/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 del task da eliminare.
Stato del task
Eliminare un task PENDING rimborsa i crediti utilizzati al momento della sua creazione.
Un task IN_PROGRESS non può essere eliminato. La richiesta restituisce 409 Conflict,
e il task continua a essere eseguito. Meshy non rimborsa un task già avviato,
quindi eliminarlo ti farebbe perdere sia i crediti che il risultato. Attendi che
raggiunga lo stato SUCCEEDED, FAILED, o CANCELED, quindi eliminalo.
Eliminare un task in uno stato finale (SUCCEEDED, FAILED, o CANCELED)
non rimborsa i suoi crediti.
Restituisce
200 OK quando il task viene eliminato, oppure 409 Conflict quando il task è
IN_PROGRESS.
Elenco delle attività Immagine in 3D
Restituisce un elenco delle tue attività Immagine in 3D.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "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",
"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": 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 attività 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 attività Immagine in 3D.
Streamare un task Immagine in 3D
Trasmette gli aggiornamenti di un task Immagine in 3D sotto forma di Server-Sent Events (SSE).
Request
curl -N https://api.meshy.ai/openapi/v1/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": "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",
"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": 30
}
Parametri
- Name
- id
- Type
- path
- Description
L'ID del task restituito dalla risposta di creazione.
Restituisce
Uno stream di oggetti task Immagine in 3D sotto forma di Server-Sent Events.
Ogni evento contiene l'intero oggetto task, nello stesso formato restituito dall'endpoint Get. Mentre il task è in stato PENDING o IN_PROGRESS, i suoi campi dei risultati non hanno ancora alcun valore.
L'oggetto task Immagine in 3D
Un oggetto task Immagine in 3D descrive una generazione di un modello 3D a partire da un'immagine. Contiene lo stato, il progresso e i file del modello quando il task ha successo.
Proprietà
Example Image to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "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": "",
"texture_image_url": "",
"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",
"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": 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
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, anziché avere 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 a un file OBJ quando il modello ha 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 3D. Quando
thumbnail_urlsè presente, è la stessa immagine dithumbnail_urls.front. Meshy lo mantiene per retrocompatibilità.
- 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. Ogni valore è un URL firmato a un PNG 512×512, renderizzato con gli stessi materiali e la stessa illuminazione di
thumbnail_url. Usali per visualizzare in anteprima il modello da diverse angolazioni, ad esempio in una pipeline batch, senza scaricare il GLB.Presente solo quando hai creato il task con
multi_view_thumbnails: truee il task ha raggiunto lo statoSUCCEEDED. I task creati senzamulti_view_thumbnails: truenon includono 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_url
- Type
- string
- Description
URL di download per l'immagine che ha guidato la texture.
- 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,
2ko4k. Un taskstandardnon include questo campo.
- Name
- progress
- Type
- integer
- Description
Quanta parte del task è stata completata, in percentuale. È
0finché il task non parte ed è100quando ha successo.
- Name
- started_at
- Type
- timestamp
- Description
Momento in cui il task è iniziato, in millisecondi Unix. È
0finché il task non parte.
- 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 il risultato del task scade, 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
Le mappe di texture generate dal task, come array di oggetti. Di solito contiene un solo oggetto, con questi campi:
- Name
base_color- Type
- string
- Description
URL di download per la mappa del colore base.
- Name
metallic- Type
- string
- Description
URL di download per la mappa metallic. Il campo è assente quando hai creato il task con
enable_pbr: false.
- Name
normal- Type
- string
- Description
URL di download per la normal map. Il campo è assente quando hai creato il task con
enable_pbr: false.
- Name
roughness- Type
- string
- Description
URL di download per la mappa roughness. Il campo è assente quando hai creato il task con
enable_pbr: false.
- Name
emission- Type
- string
- Description
URL di download per la mappa emission. Meshy lo include solo quando hai creato il task con tutti questi parametri:
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 davanti a 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.