Avvio rapido
Questo è il riferimento API per interagire programmaticamente con Meshy.
Usi un assistente di coding AI? Consulta la nostra pagina Integrazione AI — installa il MCP server di Meshy per l'accesso con chiamata di strumenti da Claude Code, Cursor, Windsurf e altri strumenti compatibili con MCP, oppure indirizza un semplice agente chat a llms.txt.
La Meshy API fornisce un'interfaccia semplice per generare modelli 3D e texture da prompt testuali e immagini. Segui questa guida per iniziare rapidamente.
Crea una chiave API
Crea una chiave API nella pagina delle impostazioni API qui, che userai per autenticare le tue richieste in modo sicuro. Il formato della chiave API è msy-<random-string>.
Una volta generata una chiave API, conservala in un luogo sicuro.
Chiave API in modalità test
Durante lo sviluppo e i test, puoi usare la nostra chiave API in modalità test per esplorare l'API senza consumare i tuoi crediti:
msy_dummy_api_key_for_test_mode_12345678
Questa chiave API speciale ha le seguenti caratteristiche:
- Può essere usata per effettuare richieste a tutti gli endpoint della Meshy API
- Nessun credito viene consumato quando si usa questa chiave
- Tutte le richieste valide restituiranno gli stessi risultati di task di esempio, indipendentemente dai parametri di input
- La struttura dei dati della risposta corrisponderà esattamente all'API di produzione
- Perfetta per testare la tua integrazione API prima di passare alla tua vera chiave API
La chiave API in modalità test è destinata esclusivamente allo sviluppo. Per l'uso in produzione, usa la tua chiave API.
Effettua la tua prima richiesta API "Testo in 3D"
In questo esempio, genereremo un modello 3D da un prompt testuale usando l'endpoint text-to-3d. Il processo prevede due fasi: la fase di preview e la fase di refine. Nella fase di preview, viene generata una mesh di base senza texture applicata, consentendoti di valutare la geometria. Nella fase di refine, alla mesh di preview viene applicata una texture in base al prompt testuale.
Ti mostreremo come effettuare queste richieste in uno script Python.
Preview
Meshy fornisce un insieme di endpoint API REST. Puoi usarli con qualsiasi client HTTP di tua scelta. Indipendentemente dall'API che chiami, la chiave API viene sempre passata come header denominato Authorization. Ricorda di esportare la tua chiave API come variabile d'ambiente denominata MESHY_API_KEY prima di usare questo script.
I parametri chiave della richiesta di preview sono mode, che è sempre "preview", e prompt, una descrizione del modello di cui hai bisogno. In questo esempio, abbiamo specificato anche should_remesh, ma è facoltativo.
api_request.py
import requests
import os
import time
headers = {
"Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}
# 1. Generate a preview model and get the task ID
generate_preview_request = {
"mode": "preview",
"prompt": "a monster mask",
"should_remesh": True,
}
generate_preview_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_preview_request,
)
generate_preview_response.raise_for_status()
preview_task_id = generate_preview_response.json()["result"]
print("Preview task created. Task ID:", preview_task_id)
Questo completa la chiamata API di preview.
Tieni presente che la Meshy API adotta un modello di esecuzione asincrona, il che significa che quando crei un task, l'endpoint API restituisce solo un ID task. Devi quindi eseguire il polling dell'endpoint di stato del task con questo ID per verificare se il task è terminato.
api_request.py
# 2. Poll the preview task status until it's finished
preview_task = None
while True:
preview_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
headers=headers,
)
preview_task_response.raise_for_status()
preview_task = preview_task_response.json()
if preview_task["status"] == "SUCCEEDED":
print("Preview task finished.")
break
print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
Una volta terminato il task, potrai accedere agli URL del modello dalla sua risposta. Scarichiamo il modello dal campo model_urls nella risposta.
api_request.py
# 3. Download the preview model in glb format
preview_model_url = preview_task["model_urls"]["glb"]
preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()
with open("preview_model.glb", "wb") as f:
f.write(preview_model_response.content)
print("Preview model downloaded.")
Se finora tutto funziona, il tuo preview_model.glb dovrebbe apparire simile a questo. Non sarà una corrispondenza esatta, a causa della casualità intrinseca nella pipeline AI.
Refine
Procediamo alla fase di refine. Per avviare la richiesta di refine, fornisci l'ID task di preview come parametro di input.
api_request.py
# 4. Generate a refined model and get the task ID
generate_refined_request = {
"mode": "refine",
"preview_task_id": preview_task_id,
}
generate_refined_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_refined_request,
)
generate_refined_response.raise_for_status()
refined_task_id = generate_refined_response.json()["result"]
print("Refined task created. Task ID:", refined_task_id)
# 5. Poll the refined task status until it's finished
refined_task = None
while True:
refined_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
headers=headers,
)
refined_task_response.raise_for_status()
refined_task = refined_task_response.json()
if refined_task["status"] == "SUCCEEDED":
print("Refined task finished.")
break
print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
# 6. Download the refined model in glb format
refined_model_url = refined_task["model_urls"]["glb"]
refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()
with open("refined_model.glb", "wb") as f:
f.write(refined_model_response.content)
print("Refined model downloaded.")
Il modello 3D refined_model.glb ora ha una texture completa ✨.
Metti tutto insieme
Ecco il codice completo per usare l'API Testo in 3D.
api_request.py
import requests
import os
import time
headers = {
"Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}
# 1. Generate a preview model and get the task ID
generate_preview_request = {
"mode": "preview",
"prompt": "a monster mask",
"should_remesh": True,
}
generate_preview_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_preview_request,
)
generate_preview_response.raise_for_status()
preview_task_id = generate_preview_response.json()["result"]
print("Preview task created. Task ID:", preview_task_id)
# 2. Poll the preview task status until it's finished
preview_task = None
while True:
preview_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
headers=headers,
)
preview_task_response.raise_for_status()
preview_task = preview_task_response.json()
if preview_task["status"] == "SUCCEEDED":
print("Preview task finished.")
break
print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
# 3. Download the preview model in glb format
preview_model_url = preview_task["model_urls"]["glb"]
preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()
with open("preview_model.glb", "wb") as f:
f.write(preview_model_response.content)
print("Preview model downloaded.")
# 4. Generate a refined model and get the task ID
generate_refined_request = {
"mode": "refine",
"preview_task_id": preview_task_id,
}
generate_refined_response = requests.post(
"https://api.meshy.ai/openapi/v2/text-to-3d",
headers=headers,
json=generate_refined_request,
)
generate_refined_response.raise_for_status()
refined_task_id = generate_refined_response.json()["result"]
print("Refined task created. Task ID:", refined_task_id)
# 5. Poll the refined task status until it's finished
refined_task = None
while True:
refined_task_response = requests.get(
f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
headers=headers,
)
refined_task_response.raise_for_status()
refined_task = refined_task_response.json()
if refined_task["status"] == "SUCCEEDED":
print("Refined task finished.")
break
print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
time.sleep(5)
# 6. Download the refined model in glb format
refined_model_url = refined_task["model_urls"]["glb"]
refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()
with open("refined_model.glb", "wb") as f:
f.write(refined_model_response.content)
print("Refined model downloaded.")
Copia e incolla il codice in uno script Python ed eseguilo.
Run the script
python api_request.py
Dovresti vedere nel tuo terminale un output simile al seguente:
Prossimi passi
- Preferisci provare gli endpoint senza scrivere prima codice? Usa l'API Playground per configurare ed eseguire una richiesta, quindi copia lo snippet generato.
- Puoi trovare il riferimento API completo nella sezione "Endpoint API", che fornisce informazioni dettagliate su ciascuna API.
- Esplora i dettagli su Prezzi, Limiti di frequenza e su come risolvere i common errors.
- Non dimenticare di consultare regolarmente il nostro changelog per aggiornamenti e correzioni di bug.
- Hai feedback o stai riscontrando problemi? Unisciti alla nostra community Discord - ci piacerebbe ricevere tue notizie!