Зачем использовать одну модель для работы с изображениями, если единый API Cloudinary может предоставить вашему приложению сразу все пять актуальных семейств? Flux, Recraft, GPT Image, Nano Banana и Ideogram обладают разными творческими преимуществами. Предоставление доступа к ним через унифицированный API генерации изображений Cloudinary позволяет продукту выбирать подходящую модель для каждой конкретной задачи без необходимости создания отдельных конвейеров аутентификации, хранения, метаданных, трансформации и доставки для каждого провайдера.
Pixel Pursuit преобразует это преимущество множества моделей в игру на угадывание изображений в Next.js. Cloudinary генерирует скрытое изображение, сохраняет его как управляемый актив, преобразует оригинал в прогрессивные подсказки и подготавливает его к оптимизированной доставке с опциональной многоуровневой маршрутизацией через несколько CDN (multi-CDN) для корпоративных клиентов. Результатом является повторно используемый медиаактив с возможностью поиска, который можно ремиксировать, проверять, трансформировать и доставлять из той же среды продуктов Cloudinary.
Этот проект демонстрирует стандартный и премиальный уровни во всех пяти семействах, ремиксирование изображений «изображение-в-изображение», чтение метаданных, галерею и проверку доставки. Игроки могут сравнивать интерпретации моделей, в то время как разработчики сохраняют единый API и рабочий процесс с активами. Живое демонстрационное приложение ограничивает каждый браузер двумя вызовами генерации, после чего помогает посетителям клонировать репозиторий и подключить собственную учетную запись Cloudinary.
- Исходный код: https://github.com/musebe/nextjs-cloudinary-ai-guessing-game
- Живая демо-версия: https://nextjs-cloudinary-ai-guessing-game.vercel.app/
Игрок открывает игру и читает краткое руководство для первого посещения перед тем, как потратить попытку генерации. Он выбирает семейство моделей и уровень, после чего сервер выбирает случайный промпт-загадку и вызывает эндпоинт текст-в-изображение от Cloudinary. Ответ никогда не отправляется в браузер в виде простого JSON. Он защищен внутри зашифрованного аутентифицированного токена раунда и проверяется серверным маршрутом.
Каждая неверная догадка продвигает тот же актив через четыре подсказки:
- Глубокое размытие скрывает практически каждую деталь.
- Пиксельная версия обнажает цвета и формы.
- Кадрирование на основе автоматического определения центра тяжести фокусируется на вероятном объекте.
- Полное изображение раскрывает ответ.
Как только раунд разгадан или ответ раскрыт, игрок может проверить происхождение (provenance) в Cloudinary и использовать исходный актив в качестве аутентифицированной ссылки для новой генерации в режиме «изображение-в-изображение».
Эта архитектура разделяет три зоны доверия. Браузер отвечает за представление и ввод данных игроком. Сервер Next.js отвечает за учетные данные, промпты, проверку ответов, решения по квотам и аутентифицированное чтение метаданных. Cloudinary отвечает за управляемые оригиналы, метаданные генерации, производные активы и доставку.
Вам понадобятся:
- Node.js 20.9 или новее.
- Бесплатная учетная запись Cloudinary.
- Дополнение Cloudinary Image Generation.
- Знакомство с React и обработчиками маршрутов App Router в Next.js.
В проекте используются Next.js 16, React 19, TypeScript, Tailwind CSS, shadcn/ui, next-cloudinary и SDK Cloudinary для Node.js.
API генерации изображений постоянно развивается, поэтому перед релизом обязательно проверьте документацию доп. модуля Image Generation и справочник по API на наличие актуальных моделей, лимитов и полей запросов.
Откройте дополнение Image Generation в консоли Cloudinary и оформите подписку на него. Для новой учетной записи выполнение первой генерации в консоли активирует доступный план. Официальное руководство по дополнению описывает регистрацию, генерацию в консоли, поддерживаемые модели и текущее поведение квот.
Затем откройте раздел Settings > API Keys и скопируйте имя облака (cloud name), ключ API (API key) и секрет API (API secret). Проект отправляет запросы к API генерации изображений из маршрута Node.js с базовой HTTP-аутентификацией, как описано в документации по аутентификации Image Generation. Секрет должен оставаться на сервере.
Клонируйте проект и настройте его:
Добавьте ваши значения в файл .env.local:
Имя облака является общедоступным, так как оно отображается в URL-адресах доставки. Ключ API и секрет предназначены исключительно для сервера. Не добавляйте к секрету префикс NEXT_PUBLIC_.
Приложение может использовать CLOUDINARY_API_SECRET для подписи своего демонстрационного cookie-файла использования. Чтобы разделить эти задачи, сгенерируйте другое значение с высокой энтропией:
API возвращает управляемый актив. Без пресета код передает папку в target.public_id. Подписанный пресет централизует папку и пользовательский тег, а не повторяет правила хранения. Руководство по пресетам загрузки Cloudinary объясняет безопасность пресетов, режимы папок, приоритет и программное управление.
Создайте пресет в консоли:
- Выберите значок шестеренки «Settings» в консоли Cloudinary.
- Откройте Upload, затем выберите вкладку Upload Presets.
- Нажмите Add Upload Preset.
- Введите pixel-pursuit-generations в поле Upload preset name.
- Установите для параметра Signing mode значение Signed. Запрос на генерацию поступает с аутентифицированного сервера Next.js, поэтому браузеру не нужно имя неподписанного пресета.
- В разделе хранения (storage) установите для Asset folder значение image-guessing-game.
- В разделе метаданных актива добавьте pixel-pursuit в теги (Tags).
- Оставьте поля входящих и предварительных (eager) трансформаций пустыми. Эта игра применяет размытие, пикселизацию, кадрирование, формат и качество в момент доставки, чтобы иметь возможность создавать несколько подсказок из неизмененного оригинала.
- Нажмите Save.
Полученная конфигурация должна соответствовать:
В этой статье предполагается использование динамического режима папок, при котором Asset folder определяет расположение актива в Медиабиблиотеке без изменения его пути public ID. Если среда вашего продукта использует устаревший фиксированный режим папок, консоль отображает другие опции папок. Следуйте документации по режимам папок и сохраняйте соответствие пункта назначения переменной CLOUDINARY_IMAGE_GENERATION_FOLDER.
Затем обновите .env.local:
Перезапустите npm run dev после изменения окружения. Сгенерируйте один раунд, откройте Assets > Media Library и изучите папку image-guessing-game. Актив должен содержать пользовательский тег pixel-pursuit плюс автоматический тег текст-в-изображение от Cloudinary. Ремикс «изображение-в-изображение» получает тег image-to-image. Контекст актива также должен содержать model_id, prompt и seed, соответствующие автоматическим тегам и метаданным, документированным для Image Generation.
Не делайте этот пресет пресетом по умолчанию для всей среды продукта. Приложение явно отправляет upload_preset: "pixel-pursuit-generations" в цели генерации, что ограничивает влияние пресета только на этот рабочий процесс.
На момент публикации проект представляет полный каталог поддерживаемых моделей Image Generation:
Интерфейс представляет каждое семейство через его назначение, а не только через ID модели. Flux делает акцент на фотореалистичных сценах, Recraft ориентирован на векторную графику и иллюстрации, GPT Image подходит для творческих работ в стиле рекламных кампаний, Nano Banana — универсальный вариант, а Ideogram поддерживает текст, реализм и искусство. Model Mix циклически переключает каталог, позволяя игре сравнивать семейства от раунда к раунду.
Поддержка seed важна, когда вам нужен воспроизводимый или тесно связанный результат. Сервер генерирует случайный seed только для тех семейств моделей, которые его принимают. Это позволяет избежать отправки неподдерживаемых полей запроса и при этом сохранить возвращенный seed в результате и контексте Cloudinary. Перед публикацией перепроверьте официальную таблицу моделей, так как API постоянно развивается.
Основной запрос находится в src/lib/cloudinary/image-generation.ts. Он следует спецификации справочника по API Image Generation, вызывает эндпоинт v2 с областью видимости учетной записи, запрашивает квадратное изображение размером 1K и сохраняет ответ как управляемый актив.
Полная реализация включает сигнал прерывания на 120 секунд, структурированную обработку ошибок, идентификаторы запросов и синтаксический анализ квот аддонов. UUID в публичном ID предотвращает коллизии. Цель managed_asset может включать как public_id, так и upload_preset, как показано в примере управляемой цели Cloudinary. Ответ API предоставляет как asset_id, так и public_id, и приложение сохраняет оба, поскольку они решают разные задачи:
- public_id — это стабильный входной параметр для URL-адресов доставки Cloudinary и CldImage.
- asset_id — это неизменяемый идентификатор для чтения через Admin API и проверенных ссылок.
POST /api/generate route проверяет запрошенное семейство и уровень, проверяет лимит демо-версии, выбирает промпт, принадлежащий серверу, вызывает вспомогательную функцию и возвращает управляемый актив вместе с токеном раунда.
Если бы маршрут генерации возвращал ответ с публичным ID, игрок мог бы открыть DevTools и обойти игру. Pixel Pursuit шифрует ответ, принятые варианты, ID актива, публичный ID и время истечения срока действия с помощью AES-256-GCM.
Токен использует случайный 12-байтовый вектор инициализации, дополнительные аутентифицированные данные и ключ, производный от секретного ключа Cloudinary, хранящегося только на сервере. Срок его действия истекает через два часа. Браузер может переносить его между запросами, но не может читать или изменять его без нарушения аутентификации.
POST /api/guess route расшифровывает токен и нормализует как вариант ответа пользователя, так и принятые правильные ответы:
Это позволяет допускать незначительные различия в регистре, пробелах, знаках препинания и диакритических знаках без ослабления безопасности токена. Маршрут возвращает ответ только после правильной догадки или явного раскрытия.
Генерация — это лишь начало жизненного цикла изображения. Трансформации Cloudinary позволяют игре создавать несколько представлений из одного сохраненного оригинала. MysteryClueImage сопоставляет текущий этап со свойствами трансформации CldImage:
Глубокое размытие затрудняет первоначальную подсказку. Пикселизация обнажает широкую палитру и силуэт. Миниатюра с автоматическим центрированием использует интеллектуальное автоматическое центрирование Cloudinary с учетом содержимого для создания подсказки крупным планом без необходимости вручную сохранять координаты кадрирования. Финальный этап подгоняет изображение целиком.
Это производные активы. Cloudinary сохраняет оригинал, создает преобразованную версию при первом запросе ее URL-адреса и кэширует ее для последующей доставки. Таким образом, вы можете изменить последовательность подсказок без повторной генерации AI-изображения. Прочитайте руководство по трансформации изображений для получения информации о других комбинациях.
Режим проверки добавляет f_auto и q_auto к заливке 960 на 960 с автоматическим центрированием. Руководство по трансформации Next.js объясняет, как эти параметры доставки выбирают эффективный формат и качество для запрашивающего контекста.
После завершения раунда игрок может описать вариацию, например: «преврати это в постер из бумаги на закате». Конечная точка image_to_image в Cloudinary принимает управляемые активы по неизменяемому ID актива. Маршрут ремикса не доверяет произвольному ID актива клиента. Сначала он открывает токен решенного раунда, читает источник через Admin API и подтверждает, что возвращенный публичный ID и настроенная папка генерации соответствуют токену.
Затем вспомогательная функция генерации вызывает /image_to_image с управляемой ссылкой:
Flux, Recraft, GPT Image и Nano Banana в настоящее время предоставляют модели с возможностью редактирования в проекте. Recraft поддерживает только стандартный уровень редактирования, а Ideogram опущен, поскольку текущий каталог не содержит для него модели редактирования.
Ремикс сохраняется как еще один управляемый актив и автоматически получает тег и контекст генерации image-to-image от Cloudinary. Это превращает завершенный игровой раунд во второй творческий рабочий процесс при сохранении проверок достоверности исходного актива.
Страница /generations не является массивом истории на стороне клиента. src/lib/cloudinary/generations.ts параллельно запрашивает resources_by_tag для текстовых изображений и изображений на основе изображений, объединяет и удаляет дубликаты результатов по ID актива, проверяет настроенную папку и сортирует их по времени создания.
Запрос tags: true и context: true открывает доступ к происхождению, сохраненному Cloudinary с каждым активом:
- Тип генерации
- ID модели
- Промпт
- Сид (если поддерживается)
- Папка актива и публичный ID
- Размеры, формат, размер в байтах и время создания
Это делает галерею устойчивой к перезагрузкам страниц и перезапускам приложения. Это также иллюстрирует, когда использовать Admin API: используйте URL-адреса доставки для пикселей, но используйте аутентифицированные вызовы Admin API на стороне сервера, когда вашему интерфейсу требуются записи активов и метаданные. Никогда не вызывайте Admin API напрямую из браузера.
Как только игрок узнает ответ, маршрут проверки открывает токен решенного раунда и выполняет две проверки одновременно:
- Он считывает неизменяемый ID актива из Admin API Cloudinary.
- Он отправляет HEAD-запрос на преобразованный URL-адрес доставки.
Панель отображает сохраненный контекст генерации, а также хост доставки, HTTP-статус, тип контента, трансформацию, время отклика, заголовок кэша и наблюдаемые заголовки граничной сети (edge) мульти-CDN. Это полезнее, чем размещение декоративной надписи «работает на базе мульти-CDN» на экране, поскольку связывает это заявление с текущим активом и запросом.
Варианты корпоративной мульти-CDN от Cloudinary включают динамическое переключение и интеллектуальный выбор, в то время как URL-адреса приложения остаются стабильными. Динамическое переключение может направлять каждый запрос на основе текущих данных о производительности и доступности, в то время как интеллектуальный выбор сопоставляет типы активов или аудиторию с подходящей сетью. Панель отображает только те граничные заголовки, которые она наблюдает, и не утверждает, что маршрутизация Enterprise multi-CDN активна для каждой учетной записи. Ознакомьтесь с решениями multi-CDN от Cloudinary на предмет доступности, поведения маршрутизации и последствий для ценообразования.
Раунды text-to-image и ремиксы image-to-image расходуют квоту аддонов. Cloudinary документирует текущую модель кредитования в разделе планов и квот генерации изображений. Общедоступное демо должно иметь видимые и предсказуемые границы.
Pixel Pursuit разрешает два вызова генерации на браузер. Созданный сервером файл cookie HttpOnly хранит счетчик и подпись HMAC-SHA256. Посетитель не может увеличить или уменьшить действительное значение счетчика из клиентского JavaScript, и оба маршрута генерации используют один и тот же лимит. При нуле оставшихся вызовов API возвращает HTTP 429 с URL-адресом репозитория, а интерфейс объясняет, как клонировать и настроить проект.
Эта защита носит намеренно демонстрационный характер. Файлы cookie идентифицируют браузер, а не человека, и их можно очистить. Если вам требуется строгий контроль использования, добавьте аутентификацию и сохраняйте счетчики в транзакционной базе данных или общем ограничичителе скорости (rate limiter). Также комбинируйте лимиты приложения с оповещениями учетной записи Cloudinary и мониторингом квот.
Запустите сервер разработки:
Откройте http://localhost:3000 и протестируйте эту последовательность:
- Прочитайте и закройте игровое руководство для первого посещения.
- Выберите семейство и уровень модели, затем сгенерируйте раунд.
- Отправляйте неверные ответы и убедитесь, что подсказка становится понятнее.
- Разгадайте или откройте раунд и откройте проверку Cloudinary.
- Создайте ремикс на основе исходного изображения, если осталась одна генерация.
- Посетите /generations и убедитесь, что оба актива и их метаданные отображаются.
- Попробуйте еще одну генерацию и убедитесь, что ограничение в два вызова предлагает инструкции по клонированию.
Перед развертыванием выполните:
Настройте те же переменные среды на вашей хостинг-платформе. Секрет API и секрет подписи демо должны оставаться исключительно на стороне сервера. Если на вашей платформе есть средства управления длительностью маршрутов, выделите достаточно времени для тайм-аута запроса генерации проекта, составляющего 120 секунд.
Pixel Pursuit делает генерацию изображений прозрачной от подсказки до доставки. Cloudinary создает и сохраняет актив, Next.js защищает состояние игры, URL-трансформации формируют последовательность подсказок, Admin API обеспечивает надежное происхождение, а опциональная доставка через корпоративную мульти-CDN сеть может завершить путь к игроку.
Эта комбинация полезна не только в играх. Тот же паттерн может поддерживать инструменты проверки кампаний, проводники креативных вариантов, рабочие процессы визуализации продуктов или модерируемые контент-пайплайны. Начните с репозитория, подключите собственный аккаунт Cloudinary и замените каталог подсказок и последовательность подсказок на тот интерфейс, который нужен вашим пользователям.
Готовы вывести свой рабочий процесс с медиафайлами на новый уровень? Начните использовать Cloudinary бесплатно и создавайте лучшие визуальные интерфейсы уже сегодня.
