Як використовувати Image to 3D Model API: Повний посібник 2026

API перетворення зображення в 3D-модель перетворює одне фото на готову до використання 3D-модель за лічені секунди — без ручного моделювання. Ручне моделювання кожного активу повільне та дороге, а для ігрових студій, AR-додатків та команд електронної комерції воно швидко стає вузьким місцем, яке затримує запуски. API перетворення зображення в 3D-модель від Meshy усуває цю перешкоду: надішліть зображення, перетворіть його на 3D-модель за секунди та завантажте повністю текстуровану сітку у форматах GLB, FBX та OBJ. Цей посібник проведе вас через увесь робочий процес — від створення ключа API до завантаження вашої першої моделі — з готовим кодом, який можна запустити за лічені хвилини.

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

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

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

Що потрібно для використання API перетворення зображення в 3D?

Вам не потрібно багато, щоб слідувати цьому посібнику. Переконайтеся, що у вас є:

• Обліковий запис 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?

• Використовуйте один чітко видимий об'єкт. Один головний об'єкт, розташований по центру та повністю в кадрі, дає ШІ найчистішу основу — уникайте перевантажених сцен, сильного кадрування та екстремальних ракурсів.

• Віддавайте перевагу чистому, незахаращеному фону. Суцільний або простий фон допомагає моделі відокремити об'єкт від оточення.

• Використовуйте рівномірне, розсіяне освітлення. Різкі тіні та сильні відблиски можуть додати оманливі деталі до згенерованої текстури.

• Почніть із зображення високої роздільної здатності та чіткості. Чим більше деталей на вході, тим більше на виході — розмиті або низькоякісні вхідні дані призводять до менш деталізованих моделей.

Які мови програмування можна використовувати з API перетворення зображення в 3D?

Будь-яка мова, яка може виконувати 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. Завжди перевіряйте Ціни для отримання актуальних тарифів.

Які параметри приймає API перетворення зображення в 3D?

Надішліть POST на /openapi/v1/image-to-3d з цими параметрами: Обов'язкові (один із):

Необов'язкові:

Наступні кроки з API перетворення зображення в 3D

Тепер ви маєте повний робочий процес: створіть ключ API, надішліть зображення, опитуйте або використовуйте вебхук для отримання результату, а потім завантажте свою модель. Ті самі чотири кроки масштабуються від швидкого прототипу до робочого конвеєра, який автоматично перетворює тисячі зображень на 3D-активи. Отримайте свій ключ на сторінці налаштувань API та запустіть свою першу модель сьогодні. Вважаєте за краще почати з текстового запиту, а не з фото? Використовуйте API перетворення тексту в 3D-модель.

Часті запитання

Як перетворити зображення на 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-друку.

Які формати зображень можна завантажувати?

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

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

Так. Текстурування увімкнено за замовчуванням ("should_texture": true). Щоб додати PBR-карти (металік, шорсткість, нормалі), встановіть "enable_pbr": true — на meshy-6/latest це також включає карту випромінювання. Для текстури базового кольору в 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. Деталі дивіться на сторінці Ціни.

Як довго дійсні посилання для завантаження?

Посилання для завантаження дійсні протягом 3 днів на планах Pro та Studio. Корпоративні клієнти отримують постійні посилання. Зберігайте файли вчасно — прострочені посилання неможливо відновити, і вам доведеться запускати завдання заново.

Чи можна запускати кілька завдань одночасно?

Так, одночасні запити підтримуються. Якщо ви отримуєте помилку 429 Too Many Requests, ваш обліковий запис досяг ліміту швидкості — застосуйте експоненційну затримку та повторіть спробу. Сторінка Обмеження швидкості містить інформацію про ліміти для вашого плану.

Завдання показує FAILED — що роби