Швидкий старт
Це довідник API для програмної взаємодії з Meshy.
Використовуєте асистента для кодування зі ШІ? Дивіться нашу сторінку Інтеграція зі ШІ — установіть Meshy MCP server для доступу до виклику інструментів із Claude Code, Cursor, Windsurf та інших MCP-сумісних інструментів або спрямуйте звичайного чат-агента на llms.txt.
Meshy API надає простий інтерфейс для генерації 3D-моделей і текстур із текстових prompt та зображень. Дотримуйтесь цього посібника, щоб швидко почати.
Створіть API-ключ
Створіть API-ключ на сторінці налаштувань API тут, який ви використовуватимете для безпечної автентифікації ваших запитів. Формат API-ключа — msy-<random-string>.
Після того як ви згенеруєте API-ключ, збережіть його в безпечному місці.
API-ключ тестового режиму
Під час розробки та тестування ви можете використовувати наш API-ключ тестового режиму, щоб досліджувати API без витрачання ваших кредитів:
msy_dummy_api_key_for_test_mode_12345678
Цей спеціальний API-ключ має такі характеристики:
- Його можна використовувати для надсилання запитів до всіх кінцевих точок Meshy API
- Під час використання цього ключа кредити не витрачаються
- Усі дійсні запити повертатимуть однакові приклади результатів завдань незалежно від вхідних параметрів
- Структура даних відповіді точно відповідатиме виробничому API
- Ідеально підходить для тестування вашої інтеграції API перед переходом на ваш справжній API-ключ
API-ключ тестового режиму призначений лише для розробки. Для використання у виробничому середовищі використовуйте власний API-ключ.
Зробіть свій перший API-запит "Текст у 3D"
У цьому прикладі ми згенеруємо 3D-модель із текстового prompt за допомогою text-to-3d кінцевої точки. Процес складається з двох етапів: етапу попереднього перегляду та етапу уточнення. На етапі попереднього перегляду генерується базова сітка без застосованої текстури, що дає змогу оцінити геометрію. На етапі уточнення сітка попереднього перегляду текстурується на основі текстового prompt.
Ми покажемо вам, як виконувати ці запити в Python-скрипті.
Попередній перегляд
Meshy надає набір кінцевих точок REST API. Ви можете використовувати їх із будь-яким HTTP-клієнтом на ваш вибір. Незалежно від того, який API ви викликаєте, API-ключ завжди передається як заголовок із назвою Authorization. Не забудьте експортувати ваш API-ключ як змінну середовища з назвою MESHY_API_KEY перед використанням цього скрипта.
Ключові параметри запиту попереднього перегляду — це mode, який завжди має значення "preview", і prompt, опис потрібної вам моделі. У цьому прикладі ми також указали should_remesh, але він необов’язковий.
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)
Це завершує виклик API попереднього перегляду.
Пам’ятайте, що Meshy API використовує модель асинхронного виконання, тобто коли ви створюєте завдання, кінцева точка API повертає лише ID завдання. Потім ви маєте опитувати кінцеву точку статусу завдання з цим ID, щоб перевірити, чи завершилося завдання.
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)
Після завершення завдання ви зможете отримати доступ до URL-адрес моделей із його відповіді. Завантажимо модель із поля model_urls у відповіді.
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.")
Якщо все працює належним чином, ваш preview_model.glb має виглядати приблизно так. Він не буде точним збігом через внутрішню випадковість у ШІ-конвеєрі.
Уточнення
Перейдемо до етапу уточнення. Щоб ініціювати запит уточнення, надайте ID завдання попереднього перегляду як вхідний параметр.
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.")
3D-модель refined_model.glb тепер повністю текстурована ✨.
Об’єднаймо все разом
Ось повний код для використання API Текст у 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.")
Скопіюйте та вставте код у Python-скрипт і запустіть його.
Run the script
python api_request.py
Ви маєте побачити у своєму терміналі приблизно такий вивід:
Наступні кроки
- Віддаєте перевагу спочатку спробувати кінцеві точки без написання коду? Використайте API Playground, щоб налаштувати й виконати запит, а потім скопіювати згенерований фрагмент.
- Повний довідник API можна знайти в розділі "Кінцеві точки API", де наведено докладну інформацію про кожен API.
- Дізнайтеся більше про Ціни, обмеження швидкості і способи усунення поширених помилок.
- Не забувайте регулярно переглядати наш журнал змін, щоб бути в курсі оновлень і виправлень помилок.
- Маєте відгуки або зіткнулися з проблемами? Приєднуйтеся до нашої Discord спільноти — ми будемо раді почути вас!