Snelstart
Dit is de API-referentie voor programmatische interactie met Meshy.
Gebruik je een AI-codeerassistent? Bekijk onze pagina AI-integratie — installeer de Meshy MCP server voor tool-calling-toegang vanuit Claude Code, Cursor, Windsurf en andere MCP-compatibele tools, of verwijs een gewone chatagent naar llms.txt.
De Meshy API biedt een eenvoudige interface om 3D-modellen en texturen te genereren op basis van tekstprompts en afbeeldingen. Volg deze gids om snel aan de slag te gaan.
Maak een API-sleutel aan
Maak hier een API-sleutel aan op de pagina met API-instellingen, die je gebruikt om veilig je requests te authenticeren. De indeling van de API-sleutel is msy-<random-string>.
Zodra je een API-sleutel hebt gegenereerd, sla je deze op een veilige locatie op.
Test-modus API-sleutel
Tijdens ontwikkeling en testen kun je onze test-modus API-sleutel gebruiken om de API te verkennen zonder je credits te verbruiken:
msy_dummy_api_key_for_test_mode_12345678
Deze speciale API-sleutel heeft de volgende kenmerken:
- Hij kan worden gebruikt om requests te doen naar alle Meshy API-endpoints
- Er worden geen credits verbruikt wanneer je deze sleutel gebruikt
- Alle geldige requests retourneren dezelfde voorbeeldtaakresultaten, ongeacht de invoerparameters
- De structuur van de responsgegevens komt exact overeen met de productie-API
- Perfect om je API-integratie te testen voordat je overschakelt naar je echte API-sleutel
De test-modus API-sleutel is alleen bedoeld voor ontwikkelingsdoeleinden. Gebruik voor productie je eigen API-sleutel.
Doe je eerste "Tekst naar 3D"-API-request
In dit voorbeeld genereren we een 3D-model op basis van een tekstprompt met behulp van de text-to-3d endpoint. Het proces omvat twee fasen: de preview-fase en de refine-fase. In de preview-fase wordt een basismesh gegenereerd zonder toegepaste textuur, zodat je de geometrie kunt beoordelen. In de refine-fase wordt de preview-mesh van textuur voorzien op basis van de tekstprompt.
We laten je zien hoe je deze requests uitvoert in een Python-script.
Preview
Meshy biedt een set REST API-endpoints. Je kunt ze gebruiken met elke HTTP-client naar keuze. Ongeacht welke API je aanroept, wordt de API-sleutel altijd doorgegeven als een header met de naam Authorization. Vergeet niet je API-sleutel te exporteren als een omgevingsvariabele met de naam MESHY_API_KEY voordat je dit script gebruikt.
De belangrijkste parameters voor het preview-request zijn mode, die altijd "preview" is, en prompt, een beschrijving van het model dat je nodig hebt. In dit voorbeeld hebben we ook should_remesh opgegeven, maar dit is optioneel.
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)
Hiermee is de preview-API-aanroep voltooid.
Houd er rekening mee dat de Meshy API een asynchroon uitvoeringsmodel hanteert, wat betekent dat wanneer je een taak aanmaakt, de API endpoint alleen een taak-ID retourneert. Vervolgens moet je de endpoint voor de taakstatus pollen met deze ID om te controleren of de taak is voltooid.
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)
Zodra de taak is voltooid, kun je de model-URL's openen vanuit de respons. Laten we het model downloaden uit het veld model_urls in de respons.
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.")
Als alles tot nu toe werkt, zou je preview_model.glb er ongeveer zo uit moeten zien. Het zal geen exacte match zijn, vanwege de inherente willekeur in de AI-pipeline.
Refine
Laten we doorgaan naar de refine-fase. Om het refine-request te starten, geef je de preview-taak-ID op als invoerparameter.
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.")
Het 3D-model refined_model.glb is nu volledig van textuur voorzien ✨.
Alles bij elkaar
Hier is de volledige code voor het gebruik van de Tekst naar 3D API.
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.")
Kopieer en plak de code in een Python-script en voer het uit.
Run the script
python api_request.py
Je zou uitvoer in je terminal moeten zien zoals het volgende:
Volgende stappen
- Wil je liever eerst endpoints proberen zonder code te schrijven? Gebruik de API Playground om een request te configureren en uit te voeren, en kopieer daarna de gegenereerde snippet.
- Je vindt de volledige API-referentie in de sectie "API-endpoints", die gedetailleerde informatie biedt over elke API.
- Verken details over Prijzen, rate limits en hoe je veelvoorkomende fouten kunt oplossen.
- Vergeet niet regelmatig onze changelog te bekijken voor updates en bugfixes.
- Heb je feedback of ondervind je problemen? Word lid van onze Discord community - we horen graag van je!