Hunyuan 3D API: что нужно знать разработчикам

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

Дора пока. Эта статья о том, что подтверждено, что ещё не определено и о чём разработчики должны спросить перед принятием решения.

Что Hunyuan 3D значит для разработчиков

Система генерации 3D-ресурсов от Tencent

Tencent Hunyuan 3D — это 3D-ответвление более широкого семейства моделей Hunyuan от Tencent. Система генерирует 3D-меши из текстовых запросов, одиночных изображений или мультивидового ввода. Tencent подтвердил два пути доступа: глобальное веб-приложение на 3d.hunyuanglobal.com для прямого использования и Model API через Tencent Cloud для корпоративных рабочих процессов.

Tencent 3D позиционируется для продакшн-использования — игры, визуализация для e-commerce, 3D-печать, рекламный креатив, VFX для кино. Это позиционирование отражено в официальных материалах запуска, а реальный набор функций API его поддерживает.

Версии модели: 3.0, 3.1 и что предположительно добавляет 3.5

История версий важна, потому что архитектура менялась между мажорными релизами. Версия 3.0 представила архитектуру 3D-DiT (Diffusion Transformer) и вышла глобально в конце 2025 года. Международный релиз 3.1 последовал за ней, улучшив ту же линейку.

Упоминания о релизе 3.5 с более высоким разрешением и более быстрой генерацией встречаются в некоторых вторичных источниках, но конкретные заявления о возможностях — цифры разрешения, поведение PBR, скорость генерации — я бы рассматривал как требующие проверки. На этом мои данные заканчиваются. Уточните в официальной документации, прежде чем вписывать версию в спецификацию.

Pro vs Rapid: почему выбор редакции важен

API предоставляет две редакции: Pro и Rapid. Pro — это путь высокого качества с расширенными настройками: мультивидовой ввод, выбор типа генерации, большие бюджеты полигонов. Rapid — это путь высокой скорости с упрощёнными параметрами. Для высокообъёмных пайплайнов, где единообразие результата важнее детализации каждого ресурса, Rapid — правильный выбор. Для героических ресурсов — Pro.

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

Что поддерживает API Hunyuan 3D

Отправка задач и асинхронный запрос статуса

API работает асинхронно. Отправка задания в SubmitHunyuanTo3DProJob возвращает JobId. Опрос QueryHunyuanTo3DProJobTask возвращает один из четырёх статусов: WAIT, RUN, FAIL или DONE. Когда статус становится DONE, URL-адреса файлов результатов возвращаются в поле ResultFile3Ds.

Это означает, что любая продакшн-интеграция требует очереди задач, цикла опроса с выдержкой и обработчиков вебхуков, если Tencent предоставляет их в вашем регионе. Удерживать HTTP-соединение открытым на время выполнения вызова генерации 3D — это неправильный подход.

GLB-вывод, опциональные PBR-текстуры и настраиваемое количество полигонов

Формат вывода по умолчанию — GLB, бинарная форма glTF, который является открытым стандартом передачи 3D от Khronos Group. PBR-текстуры опциональны и настраиваемы. Количество полигонов настраивается в редакции Pro.

GLB — правильный выбор по умолчанию для 99% рабочих процессов с игровыми движками и 3D для веба. Если инструмент на следующем этапе требует OBJ, FBX или USD, планируйте шаг конвертации. Конвертация несложна, но не лишена крайних случаев — UV-развёртки и слоты материалов — это то, где на практике всё ломается.

Доступ к API Tencent Cloud для корпоративных рабочих процессов

Для команд, уже работающих в Tencent Cloud, доступ к API вписывается в существующую IAM, биллинг и наблюдаемость. Для команд за пределами экосистемы Tencent Cloud накладные расходы на интеграцию реальны — выбор региона, управление SecretId/SecretKey и доступность SDK в вашем стеке — всё это стоит проверить перед принятием решения.

Производственные рабочие процессы image-to-3D

Игровые ресурсы и прототипные окружения

Самый стабильный сценарий использования, который я видел в реализации у разработчиков: быстрое прототипирование пропсов, наполнение окружения и итерация от концепта до меша для вертикальных срезов. 2D-скетч концепт-художника превращается в текстурированный GLB за несколько минут. Является ли получившийся меш финальным для продакшна или «заготовкой, которую художник доработает», зависит от класса ресурса и требований к топологии.

Визуализация продуктов для e-commerce

В e-commerce 3D-модель редко является финальным результатом — она служит источником для 360°-вращений, AR-примерки или дополнительных ракурсов изображений продукта. Пайплайн генерации хорошо ложится на этот рабочий процесс: фото продукта на входе, GLB на выходе, рендеринг или AR-доставка — на следующих этапах.

3D-печать и проверка дизайна

Для 3D-печати водонепроницаемая геометрия важнее качества текстур. Перед печатью меш нужно проверить в слайсере на неманифолдные рёбра, дыры и инвертированные нормали. Большинство мешей, сгенерированных ИИ, проходят эти проверки для простых объектов и не проходят для объектов с тонкими элементами или сложными полостями. Сделайте тестовую печать, прежде чем считать модель готовой к печати.

Чеклист готовности к продакшну

Совместимость выходного формата с Unity, Unreal Engine и Blender

GLB импортируется нативно в Unity (через glTFast или встроенный импортёр), Unreal Engine (через плагин glTF Importer) и Blender (встроенный). Что иногда ломается: назначение материалов, когда PBR-карты упакованы иначе, чем ожидает движок, масштаб (единицы измерения по умолчанию различаются в разных инструментах) и скелетные данные для риггованных ресурсов. Ни один из этих случаев не является критичным, но каждый добавляет шаг в пайплайн импорта.

Качество текстур, топология и бюджет полигонов

Сгенерированная топология редко представляет собой чистую квадовую сетку, которую художник построил бы вручную. Для статичных пропсов это менее важно. Для деформируемых или анимированных ресурсов — очень важно. Планируйте шаг ретопологии для всего, что должно деформироваться. Бюджеты полигонов — что может производить редакция Pro в сравнении с тем, что может отображать ваша целевая платформа — должны сопоставляться на уровне вызова API, а не в постобработке.

Очереди, повторные попытки и упавшие задания

Упавшие задания возвращают статус FAIL. В текущей документации нужно проверить, оплачиваются ли упавшие задания и какова семантика повторных попыток. Стройте логику повторных попыток на основе задокументированного поведения, а не предположений. Ключи идемпотентности, если поддерживаются, спасают от двойного списания при сетевых повторах.

Коммерческое использование и проверка лицензии

Для закрытого доступа к API через Tencent Cloud условия коммерческого использования прописаны в соглашении об услугах и должны быть проверены юридической командой перед выпуском. Для открытых релизов в организации Tencent-Hunyuan на GitHub файл LICENSE каждого репозитория является источником истины — они различаются в зависимости от релиза и обновляются. Проверяйте в момент интеграции, а не на этапе планирования.

Прямой API Tencent vs агрегационный слой

Когда прямого доступа к API достаточно

Если продукт зависит ровно от одной 3D-модели и команда уже работает в Tencent Cloud, прямой доступ к API — более простой путь. Один поставщик, один SDK, одна строка биллинга.

Когда доступ к нескольким моделям снижает риск привязки

Если продукту нужно сравнивать 3D-модели от разных провайдеров — Hunyuan 3D, Trellis, TripoSR и других — или если выбор модели, вероятно, будет меняться по мере развития области, агрегационный слой снижает стоимость переключения. Единый интерфейс для нескольких 3D AI-провайдеров означает, что смена модели становится заменой параметра, а не переработкой интеграции.

В документации API WaveSpeedAI описан один из паттернов такого унифицированного доступа. Компромисс стабилен: тонкий слой между вашим кодом и провайдерами в обмен на избавление от необходимости поддерживать особенности каждого провайдера. Стоит оценить в сравнении с прямым доступом применительно к вашей конкретной нагрузке, а не абстрактно.

FAQ

Выводит ли Hunyuan 3D GLB или другие 3D-форматы?

GLB — задокументированный формат вывода по умолчанию. Совместимость с OBJ подтверждена в сторонних источниках, но точный набор поддерживаемых форматов по редакциям нужно верифицировать по актуальной документации API. Для большинства пайплайнов с игровыми движками и веб-3D GLB — это то, что нужно.

В чём разница между Hunyuan 3D Pro и Rapid?

Pro — редакция высокого качества с расширенными настройками: мультивидовой ввод, выбор типа генерации, настраиваемые бюджеты полигонов до высоких шестизначных чисел. Rapid — редакция, оптимизированная по скорости, с упрощёнными параметрами, предназначенная для высокообъёмных рабочих процессов, где единообразие важнее детализации каждого ресурса. Точные различия параметров и актуальные цены нужно уточнять по официальной документации.

Работает ли API Hunyuan 3D синхронно или асинхронно?

Асинхронно. Отправляете задание, получаете JobId, опрашиваете эндпоинт статуса до тех пор, пока статус не станет DONE или FAIL. Нет синхронного эндпоинта «отправил и получил бинарник в ответ» — модель работает слишком долго для разумного HTTP-паттерна такого рода. Планируйте интеграцию вокруг асинхронного потока с самого начала.

Бесплатен ли Hunyuan 3D?

Для глобального веб-приложения есть бесплатный уровень — в анонсе запуска Tencent упоминались 20 бесплатных генераций в день для индивидуальных пользователей и 200 бесплатных кредитов для корпоративных пользователей API Tencent Cloud. Сверх этого уровня использование оплачивается. Поиск по запросу «бесплатная генерация 3D-модели из изображения» вернёт заявления от многих провайдеров; уточняйте актуальные условия бесплатного уровня на официальной странице цен, прежде чем полагаться на какие-либо цифры, поскольку они меняются.

Когда разработчикам стоит сравнить Hunyuan 3D с другими 3D-моделями?

До интеграции, а не после. Прогоните репрезентативную нагрузку — от пяти до десяти эталонных входных данных, охватывающих категории, которые действительно нужны вашему продукту, — через модель и хотя бы одну другую 3D AI-альтернативу. Сравните по геометрической точности, качеству текстур, топологии, времени генерации и цене за ресурс. Правильное сравнение занимает полдня и позволяет избежать проекта миграции в будущем.

Заключение

Hunyuan 3D — серьёзный вариант для разработчиков, внедряющих 3D AI в продакшн. API задокументирован, выходные форматы стандартны, пути доступа понятны. То, что ещё меняется — точные возможности версий, различия параметров редакций, ценовые уровни — нужно верифицировать по официальной документации в момент интеграции, а не брать из вторичных источников.

Команды, которые справились с этим правильно, относились к выбору 3D-модели как к самостоятельному архитектурному решению с собственными критериями оценки и собственной наблюдаемостью. Прогоните реальную нагрузку. Это расскажет вам больше, чем всё, что я могу сказать.

Предыдущие статьи: