Как использовать Image to 3D Model API: полное руководство 2026

Image to 3D Model API превращает одно фото в готовую к использованию 3D-модель за секунды — без ручного моделирования. Ручное создание каждого ассета медленно и дорого, и для игровых студий, AR-приложений и команд электронной коммерции это быстро становится узким местом, задерживающим запуски. API преобразования изображения в 3D-модель от Meshy устраняет это трение: отправьте изображение, преобразуйте его в 3D-модель за секунды и загрузите полностью текстурированную сетку в таких форматах, как GLB, FBX и OBJ. Это руководство проведет вас через весь рабочий процесс — от создания ключа API до загрузки вашей первой модели — с готовым кодом, который можно запустить за минуты.

Что такое Image to 3D Model API?

По своей сути Image to 3D Model API — это REST-эндпоинт на базе ИИ Meshy для преобразования изображения в 3D-модель. Вы отправляете одно изображение (JPG, JPEG или PNG) в виде публичного URL или строки base64, и API возвращает текстурированную 3D-модель — включая геометрию и текстуры базового цвета — в стандартных форматах, таких как GLB, FBX, OBJ, USDZ, STL и 3MF. Дополнительные опции включают PBR-карты, текстуры до 4K и миниатюры предварительного просмотра с нескольких ракурсов.

Работая на базе нашей новейшей модели Meshy 6, API позволяет настраивать топологию и количество полигонов, задавать режимы поз и управлять текстурированием с помощью текстовой подсказки или референсного изображения — идеально для создания ассетов для игр, AR/VR, 3D-печати и визуализации продуктов.

Что нужно для использования Image to 3D API?

Вам много не понадобится. Убедитесь, что у вас есть:

• Аккаунт Meshy — зарегистрируйтесь бесплатно если у вас его нет. Вы сгенерируете ключ API из панели управления в Шаге 1.

• Ключ API — используется для аутентификации каждого запроса. Мы покажем, как его создать, и вы можете использовать бесплатный тестовый ключ, чтобы следовать инструкции без траты кредитов.

• Входное изображение — четкое .jpg, .jpeg или .png, размещенное по общедоступному URL (или закодированное в base64). Чистый фон и четко видимый объект дают наилучшие результаты.

• Способ отправки HTTP-запросов — curl (используется в примерах ниже), Postman или любая HTTP-библиотека на вашем языке. Базовое знакомство с REST API и JSON полезно, но не обязательно.

Вот и все — опыт 3D-моделирования не требуется. Давайте начнем.

Как преобразовать изображение в 3D-модель с помощью API (пошаговое руководство)

Шаг 1: Настройте параметры API

Все необходимое для начала работы находится на странице настроек API. Это ваш центр управления API Meshy, и он содержит три ключевых раздела:

• Ключи API — создавайте и управляйте ключами, которые аутентифицируют ваши запросы.

• Вебхуки — получайте автоматические уведомления о завершении ваших задач.

• Использование — отслеживайте остаток кредитов и потребление API в реальном времени.

Давайте рассмотрим каждый из них.

Получите свой ключ API

Прежде чем делать какие-либо запросы, вам понадобится ключ API для безопасной аутентификации. На странице настроек API нажмите Generate API Key. Каждый ключ имеет формат msy-<случайная-строка>.

Совет: После создания сохраните ключ API в надежном месте (например, в менеджере паролей или переменной окружения). Относитесь к нему как к паролю — никогда не помещайте его в систему контроля версий и не раскрывайте в клиентском коде.

Тестовый ключ API

Во время разработки и тестирования вы можете использовать тестовый ключ API для изучения API без расходования ваших кредитов:

msy_dummy_api_key_for_test_mode_12345678

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

• Его можно использовать для отправки запросов ко всем эндпоинтам API Meshy.

• Кредиты не расходуются при использовании этого ключа.

• Все корректные запросы возвращают один и тот же результат примера задачи, независимо от входных параметров.

• Структура данных ответа полностью соответствует рабочему API.

Это делает его идеальным для тестирования вашей интеграции перед переходом на ваш реальный ключ API.

Настройка вебхуков (опционально)

Генерация 3D-модели требует времени, поэтому вместо постоянного опроса API для проверки статуса задачи вы можете позволить Meshy уведомить вас в момент ее завершения. Для этого и нужны вебхуки.

В разделе Webhooks на странице настроек добавьте URL эндпоинта, на который Meshy должен отправлять уведомления о событиях. Когда статус задачи меняется (например, она завершается или завершается с ошибкой), Meshy отправляет HTTP-запрос POST на ваш URL с деталями задачи в теле запроса.

Совет: Вебхуки — рекомендуемый подход для продакшена. Они уменьшают количество ненужных API-вызовов и позволяют вашему приложению реагировать на результаты в реальном времени. Для быстрых тестов опрос также подходит. Чтобы протестировать код вебхука локально, направьте его на прокси-URL от сервиса вроде smee.io.

Попробуйте без кода — API Playground (опционально)

Уже есть ключ API? Прежде чем писать код, вы можете выполнить реальную задачу Image to 3D прямо в браузере.

Откройте meshy.ai/api-playground, выберите Image to 3D на левой панели и заполните три поля:

1. Authorization — вставьте ваш ключ API (msy-xxxxxxxxxx)

2. Image — загрузите .jpg, .jpeg или .png с вашего компьютера

3. Нажмите Send

Playground отправляет задачу и автоматически опрашивает результаты. После завершения вы увидите предварительный просмотр 3D-модели и ссылки для скачивания прямо в браузере — без единой строки кода.

Про-совет: Панель необработанных запросов/ответов справа показывает, что именно API отправляет и возвращает. Вы можете скопировать содержимое напрямую — возьмите task_id из ответа и model_urls после завершения задачи. Они понадобятся вам на следующих шагах.

Шаг 2: Отправьте задачу Image to 3D

Имея ключ API, запустите задачу одним POST-запросом:

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

Вы получите ответ, подобный этому:

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Значение result — это ваш task_id — сохраните его. Он понадобится на следующем шаге для проверки прогресса и получения модели.

Опционально: Чтобы получать автоматические уведомления о завершении задачи, добавьте поле webhook_url в тело JSON — например "webhook_url": "https://yourapp.com/webhooks/meshy". См. Шаг 3, Вариант B, чтобы узнать, как это работает.

Шаг 3: Получите результаты

Ваша задача не выполняется мгновенно — Meshy обрабатывает ее в фоновом режиме. У вас есть два способа получить результат:

Вариант A: Опрос статуса (самый простой)

Отправляйте GET-запрос каждые 5 секунд, пока status не изменится на SUCCEEDED:

curl https://api.meshy.ai/openapi/v1/image-to-3d/{task_id} \
  -H "Authorization: Bearer $MESHY_API_KEY"

Ответ выглядит так:

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

Несколько полей, которые стоит знать:

• model_urls содержит ссылки для скачивания для каждого сгенерированного формата. По умолчанию это glb, fbx, obj, usdz, stl и mtl (файл материала, который идет в паре с obj).

• model_url — это сокращение на ссылку GLB — удобно, если нужен только GLB.

• consumed_credits показывает, сколько кредитов было использовано задачей (равно 0 для неудачных задач, так как кредиты возвращаются).

• thumbnail_url присутствует всегда и указывает на миниатюру вида спереди.

• thumbnail_urls появляется только при multi_view_thumbnails: true и содержит виды спереди, справа, сзади и слева.

• alpha_thumbnail_url появляется только при alpha_thumbnail: true и содержит миниатюру с прозрачным фоном.

Возможные значения status: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Вариант B: Вебхук (рекомендуется для продакшена)

Если вы указали webhook_url в Шаге 2, Meshy автоматически отправит POST-запрос с объектом завершенной задачи на ваш URL — опрос не требуется.

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 Что выбрать? Опрос подходит для прототипирования и разовых задач. Используйте вебхуки в продакшене — это надежнее и экономит API-вызовы.

Шаг 4: Загрузите вашу 3D-модель

Когда status станет SUCCEEDED, возьмите URL для скачивания из model_urls и загрузите нужный формат:

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

Флаг -o model.glb сохраняет файл в текущую рабочую директорию под этим именем — используйте полный путь (например, -o /path/to/model.glb), чтобы сохранить в другое место.

По умолчанию каждая задача возвращает GLB, FBX, OBJ, USDZ, STL и MTL (файл материала для OBJ). 3MF опционален — вы получите его, только если явно запросите через target_formats (см. таблицу параметров ниже).

⚠️ Ссылки действительны 3 дня (корпоративные тарифы получают постоянные ссылки). Загружайте и сохраняйте модели своевременно — ссылки перестанут работать после истечения срока, и вам придется запускать задачу заново.

Готовы использовать эту модель в вашем DCC-инструменте? См. руководство Bridge to Blender — у Meshy также есть мосты для Unity, Unreal, Maya и других.

Как получить наилучшие результаты преобразования изображения в 3D?

• Используйте один четко видимый объект. Один главный объект, расположенный по центру и полностью в кадре, дает ИИ самую чистую основу — избегайте загруженных сцен, сильной обрезки и экстремальных ракурсов.

• Предпочитайте чистый, незагроможденный фон. Сплошной или простой фон помогает модели отделить объект от окружения.

• Используйте равномерное, рассеянное освещение. Резкие тени и сильные блики могут внести в сгенерированную текстуру вводящие в заблуждение детали.

• Начинайте с изображения высокого разрешения и четкости. Больше деталей на входе означает больше деталей на выходе — размытые или низкоразрешающие изображения дают более мягкие модели.

На каких языках программирования можно использовать Image to 3D API?

На любом языке, который может отправлять HTTP-запросы — вы отправляете POST с JSON и опрашиваете с помощью GET. Распространенные варианты:

• Python — используйте библиотеку requests или httpx

• JavaScript / TypeScript — используйте fetch (встроенный) или axios

• Go — используйте net/http из стандартной библиотеки

• cURL — отлично подходит для быстрого тестирования из терминала

Вы также можете найти готовые примеры кода для всех четырех в API Playground.

Сколько кредитов стоит задача Image to 3D?

Стоимость зависит от версии модели и от того, генерируются ли текстуры. Стандартная настройка (meshy-6 с текстурированием) стоит 30 кредитов за задачу:

Неудачные задачи автоматически возвращают кредиты — consumed_credits возвращает 0. Всегда проверяйте актуальные тарифы на странице Pricing.

Какие параметры принимает Image to 3D API?

Отправьте POST на /openapi/v1/image-to-3d со следующими параметрами: Обязательный (один из):

Опциональные:

Следующие шаги с Image to 3D API

Теперь у вас есть полный рабочий процесс: создайте ключ API, отправьте изображение, опрашивайте или используйте вебхук для получения результата, затем загрузите модель. Те же четыре шага масштабируются от быстрого прототипа до производственного конвейера, который автоматически превращает тысячи изображений в 3D-ассеты. Получите ключ на странице настроек API и отправьте свою первую модель уже сегодня. Предпочитаете начать с текстовой подсказки вместо фото? Используйте Text to 3D Model API.

Часто задаваемые вопросы

Как преобразовать изображение в 3D-модель через API?

Отправьте POST-запрос на /openapi/v1/image-to-3d с вашим image_url и ключом API, затем опрашивайте задачу (или используйте вебхук), пока ее status не станет SUCCEEDED. Ответ содержит ссылки для скачивания сгенерированной модели. Полный четырехшаговый процесс — ключ, отправка, получение, скачивание — описан в пошаговом руководстве выше.

Какие выходные форматы (STL, GLB, OBJ) поддерживает API?

Каждая задача по умолчанию возвращает GLB, FBX, OBJ, USDZ, STL и MTL, а 3MF доступен по запросу через target_formats. GLB лучше всего подходит для веба и AR, FBX и OBJ — для DCC-инструментов и игровых движков, USDZ — для iOS AR, а STL — для 3D-печати.

Какие форматы изображений можно загружать?

Image to 3D API поддерживает изображения JPG, JPEG и PNG размером до 100 МБ — больше, чем лимит в 20 МБ в интерфейсе Meshy Workspace. Для наиболее точных результатов используйте PNG с прозрачным или чистым белым фоном, что помогает API изолировать объект и создать более качественную 3D-модель.

Можно ли получить текстурированную 3D-модель из API?

Да. Текстурирование включено по умолчанию ("should_texture": true). Чтобы добавить PBR-карты (metallic, roughness, normal), установите "enable_pbr": true — на meshy-6/latest это также включает карту emission. Для текстуры базового цвета в 4K установите "hd_texture": true (поддерживается только на meshy-6/latest; PBR-карты остаются в 2K). Вы также можете управлять стилем текстуры с помощью texture_prompt или texture_image_url.

Можно ли сгенерировать 3D-модель, готовую для 3D-печати (STL)?

Да — STL генерируется по умолчанию, поэтому преобразование изображения в 3D STL не требует дополнительных параметров: просто возьмите model_urls.stl после завершения задачи. Это делает рабочие процессы преобразования изображения в 3D-печать простыми, так как STL является стандартным форматом, ожидаемым слайсерами. Если вам нужен только STL, установите "target_formats": ["stl"], чтобы пропустить другие форматы и сократить время генерации.

Какие тарифы включают доступ к API?

Доступ к API предоставляется на тарифах Pro, Studio и Enterprise — это функция уровня Pro и выше. Бесплатный тариф Starter не включает доступ к API. Подробности см. на странице Pricing.

Как долго действительны ссылки для скачивания?

Ссылки для скачивания действительны в течение 3 дней на тарифах Pro и Studio. Корпоративные клиенты получают постоянные ссылки. Сохраняйте файлы своевременно — истекшие ссылки невозможно восстановить, и вам придется запускать задачу заново.

Можно ли запускать несколько задач одновременно?

Да, одновременные запросы поддерживаются. Если вы получили ошибку 429 Too Many Requests, ваша учетная запись достигла лимита скорости — реализуйте экспоненциальную задержку и повторите попытку. См. страницу Rate Limits для получения информации о лимитах вашего тарифа.

Задача показывает FAILED — что делать?

Проверьте task_error.message, чтобы узнать причину. Распространенные:

Если проблема не устранена, обратитесь в службу поддержки Meshy.