Genius-bot · 11 минут чтения
API для генерации изображений нужен не только для создания картинки с нуля. В практической интеграции часто важнее другой сценарий: взять готовую фотографию, загрузить её в API, передать описание конкретной правки и получить обработанный результат. Такой подход подходит для замены фона, изменения одежды, удаления отдельных объектов и восстановления повреждённых участков.
В этой статье разберём именно редактирование исходного снимка. Для операции «Изменить фото по описанию» предусмотрен отдельный маршрут, а стоимость одного запуска составляет 35 ₽. Для сравнения, новая картинка по описанию стоит 9 ₽ за запуск, поэтому выбор между редактированием и полной генерацией зависит не только от цены, но и от того, насколько важно сохранить исходную фотографию. Получить ключ и посмотреть доступные операции можно в разделе API.
Ниже — последовательность, которую удобно использовать в коде: сначала загружаем исходник через /uploads, затем запускаем /generate с операцией image-edit, после чего проверяем задачу через /tasks/{id}. Если обработку не хочется опрашивать вручную, можно передать callback_url и принять POST-запрос после завершения.
Чем правка отличается от генерации с нуля
У генерации с нуля нет исходного изображения, которое нужно сохранить. Вы задаёте описание сцены, а операция image создаёт картинку по этому описанию. Стоимость такого запуска — 9 ₽.
При редактировании исходник уже существует. В запросе появляется дополнительная информация: какую фотографию нужно обработать и что именно в ней изменить. Операция image-edit стоит 35 ₽ за запуск, то есть дороже новой генерации.
На практике это различие особенно заметно на фотографиях людей, товаров и интерьеров. Если нужно сохранить лицо человека, положение товара, композицию комнаты или другие элементы снимка, редактирование позволяет сформулировать задачу как локальную правку, а не как описание всей сцены заново.
Поэтому сравнивать 35 ₽ и 9 ₽ только как две цены неправильно. У генерации за 9 ₽ нет задачи сохранить конкретный исходный кадр. Если исходник уже соответствует требованиям на 90% и нужно поменять только фон, одежду или один объект, стоимость полного пересоздания — не единственный критерий.
| Операция | Цена за запуск | Когда использовать |
|---|---|---|
Картинка по описанию (image) |
9 ₽ | Нужно создать изображение без исходной фотографии |
Изменить фото по описанию (image-edit) |
35 ₽ | Нужно изменить готовый снимок |
Увеличить качество фото (upscale) |
50 ₽ | Нужно отдельно повысить качество фотографии |
Цены в таблице указаны за один запуск. Отдельной абонентской платы нет, а оплата производится за запуск операции. При выпуске первого ключа на баланс начисляется 50 ₽ для пробы, поэтому несколько первых вызовов можно сделать без дополнительного пополнения, пока хватает тестового остатка.
Загрузка исходника и получение ссылки
Редактирование начинается с передачи исходного файла. Для этого в API есть POST /uploads: файл отправляется на сервер, а в ответе получается ссылка, которую затем можно использовать при запуске операции.
Базовый адрес API — https://genius-bot.ru/wp-json/genius/v1. Авторизация выполняется через заголовок Authorization: Bearer <ключ>. Ключ выдаётся в разделе API после входа и показывается один раз, поэтому в приложении его лучше хранить как секрет и не помещать непосредственно в клиентский код.
Минимальный вариант загрузки через curl выглядит так:
curl -X POST \
https://genius-bot.ru/wp-json/genius/v1/uploads \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@photo.jpg"Из ответа нужно взять полученную ссылку на файл. Затем эта ссылка передаётся в запрос запуска операции. Такой двухэтапный процесс удобнее, чем пытаться отправлять исходное изображение непосредственно вместе с каждым последующим запросом на обработку.
В приложении можно реализовать тот же процесс через Python и библиотеку requests. Например, сначала загружаем JPEG, затем используем URL из ответа для запуска редактирования:
import os
import requests
BASE_URL = "https://genius-bot.ru/wp-json/genius/v1"
API_KEY = os.environ["GENIUS_API_KEY"]
headers = {
"Authorization": f"Bearer {API_KEY}"
}
with open("photo.jpg", "rb") as image_file:
upload = requests.post(
f"{BASE_URL}/uploads",
headers=headers,
files={"file": image_file},
)
upload.raise_for_status()
file_data = upload.json()
print(file_data)Конкретное поле со ссылкой нужно взять из фактического ответа вашего вызова. Это важный момент для интеграции: не стоит жёстко придумывать имя поля, если приложение уже получает JSON от API. После загрузки сохраните URL и используйте его при формировании следующего запроса.
Как описать правку, чтобы не переделали всё
Самая полезная часть запроса на редактирование — не длинное описание всей фотографии, а чёткое указание области изменения. Сначала зафиксируйте, что должно остаться без изменений, затем укажите конкретную правку.
Например, вместо фразы «сделай красивое фото человека на улице» лучше написать: «сохрани человека, позу, лицо, одежду и кадрирование; замени только фон на городскую улицу вечером». В первом варианте задача фактически превращается в повторное описание изображения, во втором явно задана граница изменения.
Для операции image-edit полезно использовать структуру из трёх частей:
что сохранить;- что изменить;
- каким должен быть результат изменения.
Например: «Сохрани человека, его лицо, причёску, позу, одежду и исходную композицию. Удали предмет справа от человека. Восстанови фон за удалённым предметом так, чтобы он соответствовал окружающей стене. Больше ничего в фотографии не меняй».
Такая формулировка особенно полезна, когда требуется изменить фото по описанию через API в автоматическом процессе. Ваше приложение может генерировать описание правки из пользовательских параметров, но в шаблоне запроса стоит отдельно перечислять неизменяемые элементы.
Есть и обратная крайность: слишком общий запрос. Формулировка «улучши фотографию и сделай фон лучше» не определяет, что именно считать фоном и что означает «лучше». Если задача локальная, локальной должна быть и инструкция.
В технической реализации после /uploads отправляется запрос на POST /generate. В нём указывается операция, ссылка на исходный файл и описание изменения. Точный формат полей для запуска следует сверять с ответом и документацией вашего API-раздела, а не строить интеграцию на предположениях о структуре JSON.
Четыре частые задачи: фон, объект, одежда, реставрация
Замена фона. Это один из самых понятных сценариев для редактирования: сам объект съёмки уже подходит, но окружение нужно изменить. Например, для фотографии товара можно оставить сам товар и его положение, а заменить интерьер магазина на нейтральную студийную поверхность.
Запрос лучше формулировать с указанием границы: «сохрани товар, его размеры относительно кадра, форму, цвет и положение; замени только фон на светлый нейтральный студийный фон». Если фон содержит тени, отражения или другие детали, их тоже стоит явно описать, если они должны сохраниться.
Такой сценарий можно назвать «замена фона нейросеть API»: приложение получает исходную фотографию, загружает её через /uploads, запускает image-edit и затем отдаёт пользователю результат.
Удаление объекта. Здесь задача похожа на ретушь. Например, на снимке интерьера случайно оказался стул, который нужно убрать. В описании стоит не только назвать объект, но и указать, чем заполнить освободившуюся область: продолжением пола, стены, мебели или другого окружения.
Хорошая инструкция может выглядеть так: «Удали красный стул в правой части кадра. Восстанови участок пола и стены за ним в соответствии с окружающими поверхностями. Сохрани освещение, перспективу и все остальные предметы без изменений». Это уменьшает неоднозначность по сравнению с коротким «убери стул».
Изменение одежды. Для фотографий людей важно разделить одежду и самого человека. Если требуется поменять рубашку, можно явно указать: «замени только верхнюю одежду на тёмно-синюю рубашку; сохрани лицо, волосы, руки, позу, фон и положение человека».
Здесь особенно важна проверка результата, потому что одежда находится непосредственно рядом с руками, волосами и телом. После обработки нужно смотреть не только на новую вещь, но и на границы её области: рукава, воротник, кисти рук и другие соседние детали.
Реставрация. Если старое фото имеет царапины, потёртости или отдельные повреждённые участки, инструкция должна описывать именно восстановление, а не полную перерисовку снимка. Например: «восстанови повреждённый участок в левом верхнем углу, продолжив окружающий фон; сохрани лица, черты людей, одежду и композицию исходного снимка».
Для такой задачи полезно ограничивать область изменений ещё сильнее. Если повреждён один участок, не нужно просить «реставрировать всю фотографию», когда требуется только локальное восстановление.
| Задача | Что зафиксировать в описании | Что проверить |
|---|---|---|
| Фон | Объект, композицию и положение оставить прежними | Контуры объекта, тени, края |
| Удаление объекта | Название и точное расположение удаляемого элемента | Заполнение пустого места, перспективу |
| Одежда | Часть одежды и элементы человека, которые нельзя менять | Руки, волосы, воротник, границы ткани |
| Реставрация | Повреждённый участок и окружающую структуру | Лица, детали фона, текстуры и артефакты |
Во всех четырёх сценариях принцип один: чем меньше должна быть зона изменения, тем конкретнее нужно описать неизменяемые части. Это особенно важно для автоматической обработки большого количества фотографий, где проверять каждый промпт вручную невозможно.
Когда дешевле сгенерировать заново
Если исходная фотография больше не нужна как основа, операция image стоит 9 ₽ против 35 ₽ за image-edit. В этом случае новая генерация дешевле по цене одного запуска на 26 ₽.
Но стоимость — только часть решения. Если в исходнике есть конкретный человек, товар или композиция, которые требуется сохранить, новая генерация может не соответствовать задаче просто потому, что это уже другая операция: она получает описание будущей картинки, а не редактирует конкретный файл.
Полная генерация логична, когда исходник используется только как идея и не требуется сохранить его конкретные детали. Например, если нужно получить несколько новых вариантов абстрактной рекламной сцены и исходная фотография не является обязательной основой, цена 9 ₽ за запуск может быть достаточной причиной выбрать image.
Редактирование оправдано, когда исходная фотография содержит то, что вы не хотите пересоздавать: конкретную позу, расположение предметов, интерьер, одежду или исходную композицию. В этом случае дополнительные 26 ₽ за запуск — плата за сам сценарий работы с готовым изображением, а не просто за генерацию пикселей.
Для автоматизации полезно заранее разделить задачи на два класса. «Создать новую сцену» отправляйте в image, а «сохранить этот снимок и поменять X» — в image-edit. Такое правило проще поддерживать в коде, чем выбирать операцию после получения результата.
Кроме этих операций, в API есть отдельное увеличение качества фотографии за 50 ₽ за запуск. Если задача заключается именно в повышении качества, а не в изменении содержания кадра, имеет смысл рассматривать upscale как отдельную операцию.
Проверка результата: что смотреть в первую очередь
После получения результата не стоит ограничиваться вопросом «похож ли снимок на исходный». Сначала проверьте область, которую просили изменить, затем ближайшие к ней элементы и только после этого всю композицию.
Для замены фона смотрите на контуры объекта и границы волос, одежды или мебели. Для удаления объекта — на поверхность, которой заполнено освободившееся место. Для одежды — на руки, воротник и края ткани. Для реставрации — на лица и мелкие детали рядом с повреждённым участком.
В автоматическом сценарии состояние задачи можно получать через GET /tasks/{id}. Это позволяет отделить момент постановки операции от момента получения результата. Если приложение не должно постоянно опрашивать API, используйте необязательный параметр callback_url: после готовности задачи на указанный адрес приходит POST.
Перед массовой обработкой фотографий полезно сделать несколько тестовых запусков на реальных типах исходников. Например, если сервис обрабатывает фотографии товаров, проверьте отдельно светлый и тёмный фон, сложные контуры и наличие отражающих поверхностей. Это даст материал для корректировки шаблона описания до того, как запрос станет частью пакетной обработки.
Не забывайте и про ограничение частоты: на один ключ допускается не больше 60 запросов в минуту. При пакетной обработке загрузки файлов, запуска операций и проверки задач нужно учитывать этот предел, а не отправлять весь массив запросов одновременно.
Баланс можно проверять через GET /balance, а список доступных операций и цен — через GET /services. Это позволяет приложению не хранить цены и состояние баланса как единственный источник информации.
В итоге схема интеграции для правки готового снимка получается достаточно прямой: загрузить исходник, получить ссылку, передать её в операцию image-edit с точным описанием изменения, дождаться задачи и проверить результат. Такой api для генерации изображений фактически используется здесь как API редактирования изображений, где исходная фотография является частью входных данных.
Частые вопросы
Можно ли изменить фото по описанию api, не создавая снимок заново?
Да. Для этого предусмотрена операция image-edit стоимостью 35 ₽ за запуск. Сначала исходный файл загружается через POST /uploads, затем запускается операция редактирования.
Сколько стоит замена фона?
Замена фона относится к операции «Изменить фото по описанию» (image-edit) и стоит 35 ₽ за один запуск. Отдельной цены именно за замену фона в указанной справке нет.
Можно ли удалить объект на фотографии?
Да, это типичный сценарий редактирования. В описании стоит указать удаляемый объект, его расположение и то, как должен выглядеть участок после удаления.
Как получить ссылку на загруженное изображение?
Для загрузки используется POST /uploads. API возвращает данные загрузки, из которых приложение получает ссылку для дальнейшего запуска операции.
Можно ли узнать, когда обработка закончилась, без постоянного опроса?
Да. У операции есть необязательный параметр callback_url. После готовности задачи API отправляет на него POST-запрос.
Есть ли ограничение на количество запросов?
Да. На один API-ключ допускается не больше 60 запросов в минуту. Остаток средств можно проверить через GET /balance, а доступные операции и цены — через GET /services.
Для практического подключения и получения ключа используйте страницу подключения API. Ключ показывается один раз после выпуска, поэтому его следует сохранить в безопасном месте.
