Schnellstart
Dies ist die API-Referenz für die programmgesteuerte Interaktion mit Meshy.
Verwendest du einen KI-Coding-Assistenten? Sieh dir unsere Seite zur KI-Integration an — installiere den Meshy MCP-Server für Tool-Calling-Zugriff aus Claude Code, Cursor, Windsurf und anderen MCP-kompatiblen Tools, oder verweise einen einfachen Chat-Agenten auf llms.txt.
Die Meshy API bietet eine einfache Schnittstelle, um 3D-Modelle und Texturen aus Text-Prompts und Bildern zu generieren. Folge dieser Anleitung, um schnell loszulegen.
API Key erstellen
Erstelle hier auf der Seite mit den API-Einstellungen einen API key, den du verwenden wirst, um deine Anfragen sicher zu authentifizieren. Das Format des API key ist msy-<random-string>.
Nachdem du einen API key generiert hast, speichere ihn an einem sicheren Ort.
API Key für den Testmodus
Während der Entwicklung und beim Testen kannst du unseren API key für den Testmodus verwenden, um die API zu erkunden, ohne deine Credits zu verbrauchen:
msy_dummy_api_key_for_test_mode_12345678
Dieser spezielle API key hat die folgenden Eigenschaften:
- Er kann verwendet werden, um Anfragen an alle Meshy API endpoints zu senden
- Bei Verwendung dieses Schlüssels werden keine Credits verbraucht
- Alle gültigen Anfragen geben unabhängig von den Eingabeparametern dieselben beispielhaften Aufgabenergebnisse zurück
- Die Struktur der Antwortdaten entspricht exakt der Produktions-API
- Perfekt zum Testen deiner API-Integration, bevor du zu deinem echten API key wechselst
Der API key für den Testmodus ist nur für Entwicklungszwecke vorgesehen. Für den Produktionseinsatz verwende bitte deinen eigenen API key.
Erste "Text to 3D"-API-Anfrage senden
In diesem Beispiel generieren wir ein 3D-Modell aus einem Text-Prompt mithilfe des text-to-3d endpoint. Der Prozess umfasst zwei Phasen: die Vorschauphase und die Verfeinerungsphase. In der Vorschauphase wird ein Basis-Mesh ohne angewendete Textur generiert, sodass du die Geometrie bewerten kannst. In der Verfeinerungsphase wird das Vorschau-Mesh basierend auf dem Text-Prompt texturiert.
Wir zeigen dir, wie du diese Anfragen in einem Python-Skript stellst.
Vorschau
Meshy stellt eine Reihe von REST-API endpoints bereit. Du kannst sie mit einem beliebigen HTTP-Client deiner Wahl verwenden. Unabhängig davon, welche API du aufrufst, wird der API key immer als Header mit dem Namen Authorization übergeben. Bitte denke daran, deinen API key als Umgebungsvariable mit dem Namen MESHY_API_KEY zu exportieren, bevor du dieses Skript verwendest.
Die wichtigsten Parameter der Vorschauanfrage sind mode, der immer "preview" ist, und prompt, eine Beschreibung des Modells, das du benötigst. In diesem Beispiel haben wir außerdem should_remesh angegeben, aber dieser Parameter ist optional.
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)
Damit ist der Vorschau-API-Aufruf abgeschlossen.
Bitte beachte, dass die Meshy API ein asynchrones Ausführungsmodell verwendet. Das bedeutet, dass der API endpoint beim Erstellen einer Aufgabe nur eine Aufgaben-ID zurückgibt. Anschließend musst du den Aufgabenstatus-endpoint mit dieser ID abfragen, um zu prüfen, ob die Aufgabe abgeschlossen ist.
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)
Sobald die Aufgabe abgeschlossen ist, kannst du über ihre Antwort auf die Modell-URLs zugreifen. Laden wir das Modell aus dem Feld model_urls in der Antwort herunter.
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.")
Wenn bis hierhin alles funktioniert, sollte deine Datei preview_model.glb ungefähr so aussehen. Aufgrund der inhärenten Zufälligkeit in der KI-Pipeline wird sie nicht exakt übereinstimmen.
Verfeinern
Fahren wir mit der Verfeinerungsphase fort. Um die Verfeinerungsanfrage zu starten, gib die Aufgaben-ID der Vorschau als Eingabeparameter an.
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.")
Das 3D-Modell refined_model.glb ist jetzt vollständig texturiert ✨.
Alles zusammenfügen
Hier ist der vollständige Code für die Verwendung der Text to 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.")
Kopiere den Code in ein Python-Skript, füge ihn ein und führe es aus.
Run the script
python api_request.py
Du solltest in deinem Terminal eine Ausgabe wie die folgende sehen:
Nächste Schritte
- Möchtest du endpoints lieber zuerst ausprobieren, ohne Code zu schreiben? Verwende den API Playground, um eine Anfrage zu konfigurieren und auszuführen, und kopiere anschließend das generierte Snippet.
- Die vollständige API-Referenz findest du im Abschnitt "API Endpoints", der detaillierte Informationen zu jeder API bereitstellt.
- Erkunde Details zu Preisen, Rate Limits und dazu, wie du häufige Fehler behebst.
- Vergiss nicht, regelmäßig unser Changelog auf Updates und Fehlerbehebungen zu prüfen.
- Hast du Feedback oder Probleme? Tritt unserer Discord-Community bei – wir freuen uns, von dir zu hören!