Быстрый старт

Это справочник 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-ключ тестового режима, чтобы изучать API без расходования кредитов:

msy_dummy_api_key_for_test_mode_12345678

Этот специальный API-ключ имеет следующие характеристики:

  • Его можно использовать для отправки запросов ко всем эндпоинтам Meshy API
  • При использовании этого ключа кредиты не расходуются
  • Все корректные запросы будут возвращать одни и те же примеры результатов задач независимо от входных параметров
  • Структура данных ответа будет точно соответствовать production API
  • Идеально подходит для тестирования вашей интеграции с API перед переходом на ваш реальный API-ключ

API-ключ тестового режима предназначен только для разработки. Для использования в production применяйте собственный API-ключ.

Выполните первый API-запрос «Текст в 3D»

В этом примере мы сгенерируем 3D-модель из текстового prompt с помощью text-to-3d endpoint. Процесс включает два этапа: этап preview и этап refine. На этапе preview создается базовая сетка без примененной текстуры, что позволяет оценить геометрию. На этапе refine preview-сетка текстурируется на основе текстового prompt.

Мы покажем, как выполнить эти запросы в Python-скрипте.

Preview

Meshy предоставляет набор эндпоинтов REST API. Вы можете использовать их с любым HTTP-клиентом на ваш выбор. Независимо от того, какой API вы вызываете, API-ключ всегда передается как заголовок с именем Authorization. Не забудьте экспортировать свой API-ключ как переменную окружения с именем MESHY_API_KEY перед использованием этого скрипта.

Ключевые параметры запроса preview — это 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 preview завершен.

Имейте в виду, что Meshy API использует модель асинхронного выполнения: при создании задачи API endpoint возвращает только ID задачи. Затем необходимо опрашивать endpoint статуса задачи с этим 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 должен выглядеть примерно так. Он не будет точным совпадением из-за внутренней случайности в AI-пайплайне.

Preview-модель

Refine

Перейдем к этапу refine. Чтобы инициировать refine-запрос, передайте ID preview-задачи как входной параметр.

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 теперь полностью текстурирована ✨.

Refine-модель

Собираем все вместе

Ниже приведен полный код для использования 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 сообществу — мы будем рады вас услышать!