Szybki start
To jest dokumentacja referencyjna API do programowej interakcji z Meshy.
Korzystasz z asystenta kodowania AI? Zobacz naszą stronę Integracja z AI — zainstaluj Meshy MCP server, aby uzyskać dostęp z wywoływaniem narzędzi z Claude Code, Cursor, Windsurf i innych narzędzi zgodnych z MCP, albo skieruj zwykłego agenta czatu do llms.txt.
Meshy API zapewnia prosty interfejs do generowania modeli 3D i tekstur z promptów tekstowych oraz obrazów. Postępuj zgodnie z tym przewodnikiem, aby szybko rozpocząć.
Utwórz klucz API
Utwórz klucz API na stronie ustawień API tutaj, którego użyjesz do bezpiecznego uwierzytelniania swoich żądań. Format klucza API to msy-<random-string>.
Po wygenerowaniu klucza API przechowuj go w bezpiecznym miejscu.
Klucz API trybu testowego
Podczas tworzenia i testowania możesz użyć naszego klucza API trybu testowego, aby poznawać API bez zużywania swoich kredytów:
msy_dummy_api_key_for_test_mode_12345678
Ten specjalny klucz API ma następujące cechy:
- Może być używany do wysyłania żądań do wszystkich punktów końcowych Meshy API
- Podczas używania tego klucza nie są zużywane żadne kredyty
- Wszystkie prawidłowe żądania zwrócą te same przykładowe wyniki zadań, niezależnie od parametrów wejściowych
- Struktura danych odpowiedzi będzie dokładnie odpowiadać produkcyjnemu API
- Idealny do testowania integracji API przed przejściem na prawdziwy klucz API
Klucz API trybu testowego służy wyłącznie do celów programistycznych. Do użytku produkcyjnego użyj własnego klucza API.
Wykonaj pierwsze żądanie API „Tekst na 3D”
W tym przykładzie wygenerujemy model 3D z promptu tekstowego przy użyciu punktu końcowego text-to-3d. Proces obejmuje dwa etapy: etap preview i etap refine. Na etapie preview generowana jest bazowa siatka bez zastosowanej tekstury, co pozwala ocenić geometrię. Na etapie refine siatka preview otrzymuje teksturę na podstawie promptu tekstowego.
Pokażemy, jak wykonać te żądania w skrypcie Python.
Preview
Meshy udostępnia zestaw punktów końcowych REST API. Możesz używać ich z dowolnym wybranym klientem HTTP. Niezależnie od tego, które API wywołujesz, klucz API jest zawsze przekazywany jako nagłówek o nazwie Authorization. Pamiętaj, aby przed użyciem tego skryptu wyeksportować swój klucz API jako zmienną środowiskową o nazwie MESHY_API_KEY.
Kluczowe parametry żądania preview to mode, który zawsze ma wartość "preview", oraz prompt, czyli opis potrzebnego modelu. W tym przykładzie określiliśmy również should_remesh, ale jest to opcjonalne.
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)
To kończy wywołanie API preview.
Pamiętaj, że Meshy API przyjmuje model wykonania asynchronicznego, co oznacza, że podczas tworzenia zadania punkt końcowy API zwraca tylko identyfikator zadania. Następnie musisz odpytywać punkt końcowy statusu zadania z tym identyfikatorem, aby sprawdzić, czy zadanie zostało ukończone.
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)
Po zakończeniu zadania będziesz mieć dostęp do adresów URL modelu z jego odpowiedzi. Pobierzmy model z pola model_urls w odpowiedzi.
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.")
Jeśli do tej pory wszystko działa, Twój preview_model.glb powinien wyglądać podobnie do tego. Nie będzie to dokładne dopasowanie ze względu na wrodzoną losowość w potoku AI.
Refine
Przejdźmy do etapu refine. Aby zainicjować żądanie refine, podaj identyfikator zadania preview jako parametr wejściowy.
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.")
Model 3D refined_model.glb ma teraz w pełni nałożone tekstury ✨.
Połącz wszystko razem
Oto kompletny kod do korzystania z API Tekst na 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.")
Skopiuj i wklej kod do skryptu Python, a następnie go uruchom.
Run the script
python api_request.py
W terminalu powinny pojawić się dane wyjściowe podobne do poniższych:
Następne kroki
- Wolisz najpierw wypróbować punkty końcowe bez pisania kodu? Użyj API Playground, aby skonfigurować i uruchomić żądanie, a następnie skopiuj wygenerowany fragment kodu.
- Pełną dokumentację referencyjną API znajdziesz w sekcji „Punkty końcowe API”, która zawiera szczegółowe informacje o każdym API.
- Poznaj szczegóły dotyczące Cennika, limitów szybkości oraz sposobów rozwiązywania typowych błędów.
- Nie zapomnij regularnie sprawdzać naszego dziennika zmian, aby być na bieżąco z aktualizacjami i poprawkami błędów.
- Masz opinię lub napotykasz problemy? Dołącz do naszej społeczności Discord — chętnie Cię wysłuchamy!