Genius-bot · 10 минут чтения
Ниже — готовый HTML-текст статьи с указанной структурой, примерами API и ценами из предоставленной справки.
:::writing{variant=”document” id=”58321″ title=”Аватары и обложки через API: массовая персонализация”}
api генерации картинок нужен не только для создания отдельных изображений по кнопке. В продукте его можно встроить в сценарии, где картинка появляется автоматически: аватар по описанию пользователя, обложка для статьи нейросетью или изображение под конкретный заказ. Ключ API можно получить в разделе API после входа; при выпуске первого ключа на баланс начисляется 50 ₽.
Практическая задача здесь не сводится к одному POST-запросу. Нужно определить, какие данные передавать в промпт, где хранить результат, когда повторно использовать уже созданное изображение, как ограничить частоту запросов и что делать с пользовательскими описаниями. Ниже разберём эту схему на конкретных сценариях и ценах.
Для массовой персонализации особенно важна стоимость одного запуска. Операция «Картинка по описанию» стоит 9 ₽, поэтому при 1000 уникальных изображений расчётная стоимость запусков составит 9000 ₽, если каждый запрос действительно требует отдельной генерации.
Где персонализированная картинка окупается
Персонализация имеет смысл там, где одно изображение отличается от другого данными конкретного пользователя или объекта. Например, интернет-магазин может формировать картинку под заказ: цвет товара, выбранный вариант упаковки, имя клиента или заданный визуальный контекст. В редакторе контента похожий механизм позволяет создавать изображение на основе заголовка и нескольких полей статьи.
Аватар — ещё один простой сценарий. Пользователь заполняет форму вроде «женщина, 30 лет, короткие тёмные волосы, деловой стиль, фон офиса», а приложение превращает эти параметры в единое описание для операции генерации. Здесь важно отделять пользовательские поля от системной части промпта, чтобы сохранять единый формат результата.
| Сценарий | Операция | Цена за запуск |
|---|---|---|
| Аватар по описанию | image | 9 ₽ |
| Обложка статьи | image | 9 ₽ |
| Изменение готового изображения | image-edit | 35 ₽ |
| Увеличение качества готового изображения | upscale | 50 ₽ |
Цены в таблице указаны за один запуск. Если изображение можно получить один раз и затем отдавать десяткам пользователей, фактическая стоимость показа будет зависеть уже не от количества просмотров, а от количества уникальных генераций.
API работает с оплатой за запуск, без абонентской платы и минимального платежа. При лимите 60 запросов в минуту на один ключ имеет смысл учитывать этот предел уже на уровне очереди задач, а не только после получения ошибки от API.
Аватар по описанию: что спрашивать у пользователя
Для сценария «генерация аватаров api» лучше не давать пользователю полностью свободное текстовое поле. Свободный текст сложнее модерировать, сложнее кэшировать и сложнее приводить к повторяемому стилю. Форма из нескольких параметров даёт приложению структуру, которую можно преобразовать в единый промпт.
Минимальный набор может состоять из типа персонажа, возраста, причёски, одежды, фона и визуального стиля. Например, вместо одного поля «опишите себя» можно использовать значения «портрет», «короткие тёмные волосы», «деловой костюм», «нейтральный фон», «минималистичный цифровой портрет».
Системную часть описания лучше хранить отдельно от пользовательских данных. Приложение собирает итоговый prompt из фиксированного шаблона и разрешённых значений формы. Это позволяет менять стиль сразу для всей функции, не заставляя пользователя каждый раз заново описывать визуальные требования.
Для запуска операции нужен POST на маршрут /generate. Базовый адрес API — https://genius-bot.ru/wp-json/genius/v1, а авторизация передаётся заголовком Authorization: Bearer <ключ>.
Например, сервер вашего приложения может отправить запрос так:
curl -X POST "https://genius-bot.ru/wp-json/genius/v1/generate" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"service": "image",
"prompt": "Портретный аватар, короткие темные волосы, деловой стиль, нейтральный фон, единый минималистичный визуальный стиль"
}'Конкретные поля тела запроса следует формировать согласно контракту используемой операции. В архитектуре приложения важно разделить создание задачи и получение результата: после запуска состояние можно проверять через GET /tasks/{id}. Для асинхронного сценария также предусмотрен необязательный параметр callback_url, на который приходит POST после готовности задачи.
Такой подход удобен для очереди: пользователь отправляет форму, приложение создаёт задачу и сразу возвращает интерфейсу идентификатор. После завершения задача переводится в готовое состояние, а полученный результат сохраняется рядом с профилем пользователя.
Обложка к статье из её заголовка
Для редакционной системы входными данными может быть только заголовок статьи. Например, из названия «Как хранить результаты генерации изображений» приложение формирует описание будущей обложки. К заголовку стоит добавить фиксированные требования: композиция, визуальный стиль, запрет на лишний текст и формат, если он задан интерфейсом.
Ключевой момент — не отправлять заголовок напрямую без обработки. В нём могут быть кавычки, служебные символы, слишком длинные формулировки или слова, которые не стоит буквально переносить в изображение. Сервер сначала нормализует текст, затем собирает промпт по шаблону.
Например, шаблон может выглядеть так:
prompt = f"""
Создай обложку для статьи.
Заголовок: {title}
Стиль: единый минималистичный редакционный стиль.
Композиция: один главный визуальный объект, чистый фон.
Не добавляй текст, логотипы и интерфейсные элементы.
"""После генерации результат лучше связывать не только с пользователем, но и с конкретной версией статьи. Если редактор изменил заголовок, приложение должно понимать, что старая обложка относится к предыдущей версии контента.
На Python запрос можно вынести в отдельную функцию. Это удобно, если одна и та же логика используется для статей, карточек товаров и пользовательских профилей:
import requests
BASE_URL = "https://genius-bot.ru/wp-json/genius/v1"
API_KEY = "YOUR_API_KEY"
def generate_image(prompt):
response = requests.post(
f"{BASE_URL}/generate",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
json={
"service": "image",
"prompt": prompt,
},
timeout=30,
)
response.raise_for_status()
return response.json()
result = generate_image(
"Обложка для статьи, минималистичный редакционный стиль, "
"тема: хранение результатов генерации изображений"
)
print(result)После запуска приложение может опрашивать /tasks/{id} до получения результата либо использовать callback_url. Для production-сценария второй вариант позволяет не держать HTTP-запрос пользователя открытым всё время выполнения задачи.
Кэш и повторное использование
Кэш особенно важен там, где один и тот же набор входных данных может повторяться. Для обложки статьи естественным ключом может быть хэш нормализованного заголовка плюс версия системного промпта. Для аватара — хэш структурированных параметров пользователя плюс идентификатор выбранного стиля.
Например, приложение получает параметры style=minimal, background=office и описание персонажа. Из отсортированных значений строится строка, затем её хэш используется как ключ в базе данных. Если такой ключ уже существует и результат валиден, новый запуск не нужен.
Это меняет расчёт стоимости. Допустим, 5000 пользователей открыли одну и ту же публичную страницу статьи. Без кэша приложение потенциально может попытаться создать 5000 изображений по одному шаблону. При кэшировании достаточно одного запуска за 9 ₽, после чего остальные запросы получают сохранённый результат.
Для пользовательских изображений кэширование должно учитывать приватность и принадлежность результата. Нельзя автоматически отдавать изображение другого пользователя только потому, что совпал текстовый prompt. Поэтому ключ кэша должен включать идентификатор пользователя, если результат персональный.
Повторяемость стиля также лучше решать на уровне приложения. Храните версию шаблона промпта, например avatar-style-v3. Когда визуальные требования меняются, увеличивайте версию. Старые изображения тогда остаются связанными со старым шаблоном, а новые создаются уже по обновлённому.
Если изображение требуется изменить, а не создать с нуля, в API предусмотрена операция «Изменить фото по описанию» за 35 ₽. Для готовых изображений, которым требуется повышение качества, предусмотрена операция upscale за 50 ₽.
Модерация запросов пользователей
Модерацию лучше ставить до вызова платной операции. Пользовательский текст сначала проходит собственные проверки приложения, затем только разрешённое описание передаётся в генерацию. Это одновременно снижает риск нежелательных запросов и количество оплачиваемых запусков, которые не должны были выполняться.
Полезно разделить входные данные на два слоя. Первый — структурированные значения из формы, которые можно проверить по спискам разрешённых вариантов. Второй — свободное описание, для которого нужны ограничения длины, очистка управляющих символов и отдельная проверка содержимого.
Не стоит рассчитывать на то, что модерация закончится проверкой длины строки. Запрос на 200 символов может быть проблемным так же, как запрос на 2000 символов. Кроме того, длинные повторяющиеся запросы могут использоваться для ненужной нагрузки на ваш endpoint.
Для продукта удобно сохранять статус модерации отдельно от статуса задачи API. Например: pending_moderation, rejected, queued, processing, completed. Тогда оператор может отличить отклонённый пользовательский запрос от технической ошибки или незавершённой генерации.
Если приложение принимает изображения от пользователя для последующего редактирования, сначала загружайте разрешённый файл через POST /uploads, получайте ссылку и используйте её в следующем шаге. Сам факт наличия маршрута загрузки позволяет разделить передачу файла и запуск операции.
Ограничения на пользователя и защита от перебора
Лимит API составляет не больше 60 запросов в минуту на один ключ. Это техническое ограничение сервиса, но для продукта собственного лимита обычно недостаточно: один пользователь может занять весь доступный поток и создать очередь для остальных.
Поэтому ограничения стоит делать на нескольких уровнях. Например, для одного пользователя можно установить дневной лимит генераций, отдельный короткий лимит на повторные запросы и максимальный размер очереди. Значения этих продуктовых лимитов выбираются уже исходя из вашей модели использования и бюджета.
Полезен и cooldown для одинаковых запросов. Если пользователь пять раз подряд отправляет одну и ту же форму, приложение может не запускать пять задач, а вернуть уже существующую задачу или её результат. Это особенно важно для кнопки «сгенерировать ещё раз», которая по смыслу действительно должна создавать новую вариацию.
Отдельно контролируйте баланс. Маршрут GET /balance позволяет получить остаток, а GET /services — список доступных операций и цен. Перед массовым запуском можно проверять баланс и останавливать очередь, если средств недостаточно для очередной партии.
Для нагрузки удобно использовать очередь заданий. Ваш API принимает пользовательский запрос, создаёт внутреннюю запись, а worker запускает операции с контролем скорости. При лимите 60 запросов в минуту это позволяет распределять работу равномерно, вместо того чтобы отправлять сотни запросов одновременно.
При первом выпуске ключа на баланс начисляется 50 ₽. При цене 9 ₽ за одну генерацию изображения этого достаточно для пяти полных запусков с остатком 5 ₽, если считать только операцию image. Это можно учитывать при создании тестового окружения и автоматических проверках интеграции.
Частые вопросы
Сколько стоит генерация одного изображения?
Операция «Картинка по описанию» стоит 9 ₽ за один запуск. Другие операции имеют отдельные цены, например редактирование изображения — 35 ₽, увеличение качества — 50 ₽.
Можно ли использовать API для аватаров и обложек?
Да. Для обоих сценариев подходит операция image: приложение формирует описание изображения и отправляет его на POST /generate. Дальше результат можно сохранить и повторно использовать из собственного хранилища.
Как узнать состояние задачи?
Для этого предусмотрен маршрут GET /tasks/{id}. Альтернативно можно передать callback_url, чтобы после готовности задачи API отправил POST на указанный адрес.
Есть ли ограничение на частоту запросов?
Да. На один API-ключ разрешено не больше 60 запросов в минуту. Собственный лимит на пользователя рекомендуется организовать отдельно на уровне приложения.
Нужно ли платить абонентскую плату?
Нет. Оплата взимается за запуск операции, без абонентской платы и без минимального платежа. При выпуске первого ключа на баланс начисляется 50 ₽ для пробного использования.
Где получить ключ и посмотреть API?
После входа ключ выдаётся в разделе API и показывается один раз. Базовый адрес API: https://genius-bot.ru/wp-json/genius/v1.
