Зачем использовать одну модель изображений, если один API Cloudinary может предоставить вашему приложению доступ ко всем пяти текущим семействам моделей? Flux, Recraft, GPT Image, Nano Banana и Ideogram обладают разными творческими возможностями. Предоставление доступа к ним через унифицированный API генерации изображений Cloudinary позволяет продукту выбирать подходящую модель для каждой задачи, не создавая отдельные конвейеры для аутентификации, хранения, метаданных, трансформации и доставки для каждого провайдера.
Pixel Pursuit превращает это преимущество мультимодельности в игру «Угадай изображение» на Next.js. Cloudinary генерирует скрытое изображение, сохраняет его как управляемый ресурс, трансформирует оригинал в прогрессивные подсказки и подготавливает его для оптимизированной доставки с опциональной маршрутизацией через Enterprise multi-CDN. В результате получается повторно используемый, доступный для поиска медиаресурс, который можно изменять, проверять, трансформировать и доставлять из той же продуктовой среды Cloudinary.
Этот проект демонстрирует стандартные и премиальные уровни всех пяти семейств моделей, ремикширование изображений (image-to-image), чтение метаданных, галерею и проверку доставки. Игроки могут сравнивать интерпретации моделей, в то время как разработчики сохраняют единый рабочий процесс API и ресурсов. Живая демонстрация ограничивает каждый браузер двумя вызовами генерации, после чего предлагает посетителям клонировать репозиторий и подключить свою учетную запись Cloudinary.
- Исходный код: https://github.com/musebe/nextjs-cloudinary-ai-guessing-game
- Живая демонстрация: https://nextjs-cloudinary-ai-guessing-game.vercel.app/
Игрок открывает игру и читает краткое руководство для первого посещения, прежде чем потратить попытку генерации. Он выбирает семейство моделей и уровень, затем сервер выбирает загаданный промпт и вызывает эндпоинт Cloudinary text-to-image. Ответ никогда не отправляется в браузер в виде простого JSON. Он защищен внутри зашифрованного аутентифицированного токена и проверяется серверным маршрутом.
Каждая неверная догадка продвигает один и тот же ресурс через четыре подсказки:
- Глубокое размытие скрывает почти все детали.
- Пикселизированная версия обнажает цвета и формы.
- Автоматическая обрезка с учетом центра тяжести фокусируется на предполагаемом объекте.
- Полное изображение раскрывает ответ.
Как только раунд решен или раскрыт, игрок может проверить происхождение (provenance) в Cloudinary и использовать исходный ресурс в качестве аутентифицированной ссылки для новой генерации image-to-image.
Эта архитектура разделяет три зоны доверия. Браузер отвечает за представление и ввод игрока. Сервер Next.js отвечает за учетные данные, промпты, проверку ответов, квоты и аутентифицированное чтение метаданных. Cloudinary отвечает за управляемые оригиналы, метаданные генерации, производные ресурсы и доставку.
Вам понадобятся:
- Node.js версии 20.9 или новее.
- Бесплатная учетная запись Cloudinary.
- Дополнение Cloudinary Image Generation.
- Знание React и маршрутизаторов Next.js App Router.
Проект использует 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 key и API secret. Проект отправляет запросы к API генерации изображений из маршрута Node.js с использованием базовой HTTP-аутентификации, как описано в документации по аутентификации Image Generation. Секретный ключ должен оставаться на сервере.
Клонируйте и настройте проект:
Добавьте свои значения в .env.local:
Имя облака является публичным, так как оно появляется в URL-адресах доставки. API key и secret доступны только на сервере. Не добавляйте к секретному ключу префикс 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, поэтому браузеру не нужно имя неподписанного пресета.
- В разделе хранения установите Asset folder в значение image-guessing-game.
- В разделе метаданных ресурса добавьте pixel-pursuit в Tags.
- Оставьте входящие и немедленные (eager) трансформации пустыми. Эта игра применяет размытие, пикселизацию, обрезку, формат и качество во время доставки, чтобы можно было создавать несколько подсказок из неизменного оригинала.
- Нажмите Save.
Полученная конфигурация должна соответствовать:
Эта статья предполагает использование режима динамических папок, где Asset folder управляет расположением ресурса в медиабиблиотеке, не меняя путь к его публичному идентификатору. Если ваша продуктовая среда использует устаревший режим фиксированных папок, консоль покажет другие параметры папок. Следуйте документации по режимам папок и сохраняйте согласованность места назначения с CLOUDINARY_IMAGE_GENERATION_FOLDER.
Затем обновите .env.local:
Перезапустите npm run dev после изменения среды. Сгенерируйте один раунд, откройте Assets > Media Library и проверьте папку image-guessing-game. Ресурс должен содержать пользовательский тег pixel-pursuit плюс автоматический тег Cloudinary text-to-image. Ремикс image-to-image получает тег image-to-image. Контекст ресурса также должен раскрывать model_id, prompt и seed, соответствующие автоматическим тегам и метаданным, задокументированным для Image Generation.
Не делайте этот пресет стандартным для всей продуктовой среды. Приложение явно отправляет upload_preset: "pixel-pursuit-generations" в цели генерации, что ограничивает влияние пресета только этим рабочим процессом.
На момент публикации проект предоставляет полный каталог поддерживаемых моделей Image Generation:
Интерфейс представляет каждое семейство с определенной целью, а не просто как идентификатор модели. 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 в общедоступном идентификаторе (public 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 проверяет запрошенное семейство и уровень, проверяет лимит демо-версии, выбирает промпт, принадлежащий серверу, вызывает вспомогательную функцию и возвращает управляемый актив вместе с токеном раунда.
Если бы маршрут генерации возвращал ответ с public ID, игрок мог бы открыть DevTools и обойти игру. Pixel Pursuit шифрует ответ, принятые псевдонимы, asset ID, public ID и время истечения срока действия с использованием AES-256-GCM.
Токен использует случайный 12-байтовый вектор инициализации, дополнительные аутентифицированные данные и ключ, производный от секретного ключа Cloudinary, доступного только серверу. Срок его действия истекает через два часа. Браузер может передавать его между запросами, но не может прочитать или изменить его, не нарушив аутентификацию.
Маршрут POST /api/guess расшифровывает токен и нормализует как догадку, так и принятые ответы:
Это позволяет игнорировать несущественные различия в регистре, пробелах, пунктуации и диакритических знаках, не ослабляя при этом токен. Маршрут возвращает ответ только после правильной догадки или явного раскрытия.
Генерация — это только начало жизненного цикла изображения. Трансформации Cloudinary позволяют игре создавать несколько представлений из одного сохраненного оригинала. MysteryClueImage сопоставляет текущий этап со свойствами трансформации CldImage:
Глубокое размытие затрудняет понимание первой подсказки. Пикселизация обнажает широкую палитру и силуэт. Миниатюра с автоматическим центрированием (automatic-gravity) использует функцию Cloudinary, учитывающую содержимое, для создания близкой подсказки без необходимости вручную сохранять координаты обрезки. Финальный этап показывает полное изображение.
Это производные активы. Cloudinary сохраняет оригинал, создает трансформированную версию при первом запросе ее URL и кэширует ее для последующей доставки. Таким образом, вы можете изменить последовательность подсказок, не перегенерируя AI-изображение. Прочитайте руководство по трансформациям изображений для получения дополнительных комбинаций.
Представление доказательства (proof view) добавляет f_auto и q_auto к заполнению 960 на 960 с автоматическим центрированием. Руководство по трансформациям Next.js объясняет, как эти параметры доставки выбирают эффективный формат и качество для контекста запроса.
После завершения раунда игрок может описать вариацию, например: «преврати это в постер в стиле бумажной аппликации на закате». Конечная точка image_to_image в Cloudinary принимает управляемые активы по неизменяемому asset ID. Маршрут ремикса не доверяет произвольному asset ID клиента. Сначала он открывает токен завершенного раунда, считывает источник через Admin API и подтверждает, что возвращенный public 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 как для text-to-image, так и для image-to-image параллельно, объединяет и удаляет дубликаты по asset ID, проверяет настроенную папку и сортирует их по времени создания.
Запрос tags: true и context: true раскрывает данные о происхождении, которые Cloudinary сохранил с каждым активом:
- Тип генерации
- ID модели
- Промпт
- Сид (seed), если поддерживается
- Папка актива и public ID
- Размеры, формат, байты и время создания
Это делает галерею устойчивой к обновлению страниц и перезапуску приложения. Это также иллюстрирует, когда использовать Admin API: используйте URL-адреса доставки для пикселей, но используйте аутентифицированные серверные вызовы Admin API, когда вашему интерфейсу нужны записи об активах и метаданные. Никогда не вызывайте Admin API напрямую из браузера.
Как только игрок узнает ответ, маршрут доказательства открывает решенный токен и одновременно выполняет две проверки:
- Он считывает неизменяемый asset ID из Admin API Cloudinary.
- Он отправляет HEAD-запрос на трансформированный URL доставки.
Панель сообщает сохраненный контекст генерации плюс имя хоста доставки, HTTP-статус, тип контента, трансформацию, время отклика, заголовок кэша и наблюдаемые заголовки multi-CDN edge. Это полезнее, чем размещение декоративной метки «на базе multi-CDN» на экране, потому что это связывает утверждение с текущим активом и запросом.
Корпоративные опции multi-CDN от Cloudinary включают динамическое переключение и интеллектуальный выбор, в то время как URL-адреса приложений остаются стабильными. Динамическое переключение может направлять каждый запрос, используя текущие данные о производительности и доступности, в то время как интеллектуальный выбор сопоставляет типы активов или аудитории с соответствующей сетью. Панель сообщает только те заголовки edge, которые она наблюдает, и не утверждает, что корпоративная маршрутизация multi-CDN активна для каждой учетной записи. Ознакомьтесь с решениями Cloudinary multi-CDN для получения информации о доступности, поведении маршрутизации и ценовых последствиях.
Раунды text-to-image и ремиксы image-to-image потребляют квоту дополнений. Cloudinary документирует текущую кредитную модель в разделе планов генерации изображений и квот. Публичная демо-версия нуждается в видимой, предсказуемой границе.
Pixel Pursuit разрешает два вызова генерации на браузер. Созданный сервером HttpOnly cookie хранит счетчик и подпись HMAC-SHA256. Посетитель не может увеличить или уменьшить действительный счетчик из клиентского JavaScript, и оба маршрута генерации потребляют один и тот же лимит. При нуле оставшихся вызовов API возвращает HTTP 429 с URL-адресом репозитория, а интерфейс объясняет, как клонировать и настроить проект.
Эта защита намеренно сделана на уровне демо-версии. Файлы cookie идентифицируют браузер, а не человека, и их можно очистить. Если вам нужно строгое соблюдение правил использования, добавьте аутентификацию и сохраняйте счетчики в транзакционной базе данных или общем ограничителе скорости. Также объедините лимиты приложения с оповещениями учетной записи Cloudinary и мониторингом квот.
Запустите сервер разработки:
Откройте http://localhost:3000 и протестируйте эту последовательность:
- Прочитайте и закройте руководство по игре при первом посещении.
- Выберите семейство моделей и уровень, затем сгенерируйте раунд.
- Отправляйте неверные догадки и убедитесь, что подсказка становится яснее.
- Решите или раскройте раунд и откройте доказательство Cloudinary.
- Создайте ремикс с эталонным изображением, если осталась одна генерация.
- Посетите /generations и убедитесь, что оба актива и их метаданные отображаются.
- Попробуйте еще одну генерацию и убедитесь, что ограничение в два вызова предлагает инструкции по клонированию.
Перед развертыванием выполните:
Настройте те же переменные среды на вашей хостинговой платформе. Храните секретный ключ API и секрет подписи демо-версии только на стороне сервера. Если ваша платформа поддерживает управление длительностью маршрутов, оставьте достаточно времени для 120-секундного тайм-аута запроса на генерацию проекта.
Pixel Pursuit делает процесс генерации изображений прозрачным — от ввода подсказки до доставки результата. Cloudinary создает и хранит актив, Next.js защищает состояние игры, URL-трансформации формируют последовательность подсказок, Admin API обеспечивает надежное происхождение данных, а опциональная доставка через Enterprise multi-CDN завершает путь к игроку.
Эта комбинация полезна не только в играх. Тот же шаблон можно использовать для инструментов проверки кампаний, обозревателей креативных вариантов, рабочих процессов визуализации продуктов или конвейеров модерируемого контента. Начните с репозитория, подключите свою учетную запись Cloudinary и замените каталог подсказок и последовательность ключей на тот опыт, который необходим вашим пользователям.
Готовы вывести свой рабочий процесс с медиафайлами на новый уровень? Начните использовать Cloudinary бесплатно и создавайте лучшие визуальные интерфейсы уже сегодня.
