Genius-bot · 12 минут чтения
Если в продукте нужно не сгенерировать ролик с нуля, а превратить уже готовый снимок в короткую анимацию, нужен другой сценарий. api генерации видео здесь начинается не с текстового промпта, а с файла: изображение загружается, сервис возвращает ссылку, после чего запускается операция «Оживить фото». Ключ для доступа к API выдаётся в разделе API сервиса после входа.
На практике такой конвейер состоит из нескольких отдельных запросов. Сначала приложение получает ссылку на изображение через POST /uploads, затем передаёт её в POST /generate, сохраняет идентификатор задачи и проверяет результат через GET /tasks/{id}. Для фоновой обработки вместо постоянного опроса можно передать callback_url и получить POST-запрос после готовности задачи.
Ниже разберём именно сценарий «изображение → видео»: какие фотографии имеет смысл отправлять, где возникает необходимость в подсказке к движению, что проверять до загрузки и как считать стоимость, если операция запускается сотни или тысячи раз.
Чем оживление фото отличается от генерации из текста
У операции «Оживить фото» входные данные уже содержат визуальную сцену. На изображении определены люди, предметы, фон, композиция и исходный стиль. Задача заключается не в том, чтобы описать будущий кадр с нуля, а в том, чтобы использовать фотографию как основу для движения.
Это принципиальное отличие от операции video, которая предназначена для генерации видео по описанию и стоит 119 ₽ за один запуск. Для готового изображения используется операция photo-video стоимостью 25 ₽ за запуск. Поэтому в пользовательском интерфейсе или внутреннем API продукта эти два сценария лучше разделять: «создать видео по описанию» и «оживить существующее фото» имеют разные входы и разные цены.
| Операция | Вход | Цена за запуск |
|---|---|---|
Оживить фото (photo-video) |
Изображение | 25 ₽ |
Видео по описанию (video) |
Описание | 119 ₽ |
Изменить фото по описанию (image-edit) |
Изображение + описание | 35 ₽ |
Картинка по описанию (image) |
Описание | 9 ₽ |
Если пользователь уже загрузил фотографию и хочет добавить к ней движение, логика «фото в видео нейросеть» подходит лучше, чем повторная генерация изображения с последующей генерацией ролика. При этом конкретное содержимое результата зависит от самой операции и исходного изображения, поэтому приложение не должно рассчитывать на заранее заданный визуальный эффект.
Для интеграции используется базовый адрес https://genius-bot.ru/wp-json/genius/v1. Все запросы к API авторизуются заголовком Authorization: Bearer <ключ>. Ключ выдаётся после входа в личный раздел API и показывается один раз, поэтому его стоит сразу сохранить в секретах приложения, а не в исходном коде.
Загрузка изображения и получение ссылки
Для файла используется отдельный маршрут POST /uploads. Это важный этап: вместо передачи большого изображения непосредственно в запросе на генерацию сначала загружается файл, а API возвращает ссылку, которую затем можно использовать при запуске операции.
Пример с curl выглядит так:
curl -X POST "https://genius-bot.ru/wp-json/genius/v1/uploads" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@photo.jpg"В реальном приложении значение, которое вернул /uploads, нужно сохранить до следующего запроса. Не стоит вручную собирать URL файла или подменять его локальным путём: задача генерации должна получить ссылку, возвращённую после загрузки.
Следующий этап — запуск операции. Для него используется POST /generate. В запросе передаётся нужная операция и данные, необходимые для неё, включая ссылку на загруженное изображение. Точный ответ запуска следует сохранять целиком или как минимум вместе с идентификатором задачи, который потребуется для проверки состояния.
Схема кода на Python может выглядеть следующим образом:
import requests
BASE_URL = "https://genius-bot.ru/wp-json/genius/v1"
API_KEY = "YOUR_API_KEY"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
with open("photo.jpg", "rb") as f:
upload = requests.post(
f"{BASE_URL}/uploads",
headers=headers,
files={"file": f},
timeout=60,
)
upload.raise_for_status()
upload_data = upload.json()
image_url = upload_data["url"]
generate = requests.post(
f"{BASE_URL}/generate",
headers=headers,
json={
"service": "photo-video",
"image_url": image_url,
},
timeout=60,
)
generate.raise_for_status()
task = generate.json()
print(task)Названия полей в примере показывают структуру сценария, а не заменяют проверку фактического ответа API в вашем коде. Главное разделение здесь остаётся неизменным: сначала загрузка, затем запуск задачи. Если API возвращает идентификатор задачи, его нужно использовать для последующего запроса к GET /tasks/{id}.
Для серверного приложения удобнее считать генерацию асинхронной операцией. Запрос к /generate не должен блокировать пользовательский интерфейс до готовности видео. Приложение может сохранить ID задачи, показать статус обработки и запросить результат позже.
Если polling вам не подходит, у операции есть необязательный параметр callback_url. При его использовании после готовности задачи на указанный адрес приходит POST-запрос. Такой вариант удобен, когда ваш backend уже умеет принимать события от фоновых задач.
Какие фото оживают хорошо, а какие не стоит и пробовать
Перед отправкой файла полезно отделить техническую проверку от визуальной. API должен получить корректное изображение, но даже технически подходящий файл не обязательно является хорошей исходной сценой для анимации. Чем понятнее изображение задаёт объект и его положение в кадре, тем проще сформулировать ожидаемое движение.
Для аватарки обычно удобнее использовать фотографию, где лицо хорошо видно и не закрыто крупными предметами. Для карточки товара — изображение, в котором сам объект не сливается с фоном и занимает заметную часть кадра. Для воспоминаний подойдут фотографии с одним понятным главным сюжетом: человеком, парой людей, автомобилем, пейзажем или другим объектом, которому можно задать простое движение.
Сложнее работать со снимками, где главный объект сильно обрезан границами кадра, закрыт другими объектами или имеет очень мелкие детали. То же относится к фотографиям с большим количеством лиц и пересекающихся объектов: при попытке анимации движение одного элемента может визуально затрагивать соседние области.
Есть и практический критерий для продукта: не стоит заставлять пользователя несколько раз отправлять заведомо неподходящий файл. До вызова /uploads можно проверить расширение, MIME-тип, размер файла и факт успешного чтения изображения. Это не гарантирует качество будущей анимации, но отсекает часть ошибок ещё на стороне вашего приложения.
Если пользователь хочет оживить старую фотографию, сначала имеет смысл привести исходник к приемлемому виду. В API есть отдельная операция upscale за 50 ₽ за запуск и image-edit за 35 ₽, но это уже дополнительные операции с отдельной оплатой. Их использование следует закладывать в продуктовый сценарий только тогда, когда такая обработка действительно нужна.
Подсказка к движению: когда она нужна
Одной фотографии иногда достаточно, чтобы задать исходную сцену, но в прикладном продукте пользователю полезно дать возможность описать желаемое движение. Например, можно попросить указать, что человек слегка поворачивает голову, камера медленно приближается или элементы фона получают лёгкое движение.
Такая подсказка должна описывать именно движение, а не заново пересказывать фотографию. Если на снимке уже есть человек у окна, нет необходимости повторять весь сюжет в каждом запросе. Гораздо понятнее отделить исходный визуальный материал от инструкции: фотография задаёт сцену, а текст — ожидаемую динамику.
В интерфейсе это можно представить как два поля: «Изображение» и «Движение». Первое обязательно для сценария photo-video, второе можно сделать необязательным, если продукт допускает запуск с настройками по умолчанию.
Для разработчика это также упрощает обработку ошибок. Если пользователь загрузил файл, но не заполнил описание движения, приложение не должно отправлять пустую строку туда, где ожидается содержательная инструкция. Лучше либо использовать предусмотренное приложением значение по умолчанию, либо явно сообщить пользователю, что нужно указать движение.
При этом не стоит обещать конкретную длительность, количество кадров или определённую траекторию камеры, если эти параметры не указаны в справке API. В документации сервиса для операции photo-video подтверждена сама операция «Оживить фото» и её цена 25 ₽ за запуск, поэтому интерфейс лучше строить вокруг этих подтверждённых возможностей.
Ошибки формата и размера файла
Ошибки с изображениями чаще всего появляются ещё до генерации. Приложение получает файл от пользователя, а затем выясняется, что это не тот тип данных, который ожидался, файл повреждён, имеет неподходящий размер или фактически не является изображением, несмотря на расширение.
Первую проверку стоит делать локально. Проверяйте, что файл существует, открывается как изображение, имеет ожидаемый MIME-тип и не превышает установленный вашим продуктом лимит. Если конкретные допустимые форматы и максимальный размер для /uploads не указаны в доступной справке, их не следует придумывать и жёстко приписывать API.
Отдельно обрабатывайте ситуацию, когда пользователь загружает изображение с расширением .jpg, но содержимое файла не соответствует этому формату. Расширение само по себе не является надёжной проверкой. На backend полезно определить реальный тип файла, а затем только передавать его в загрузку.
Ещё одна типичная ошибка — повторная отправка одной и той же задачи после сетевого тайм-аута. Если запрос к /generate не дал ответа вовремя, приложение не знает автоматически, была ли операция принята. Поэтому архитектуру лучше строить так, чтобы ID задачи и состояния обрабатывались отдельно от HTTP-таймаутов, а повторный запуск не происходил без необходимости.
У ключа есть ограничение частоты: не более 60 запросов в минуту. Это важно учитывать при массовой обработке фотографий. Если продукт запускает много операций одновременно, полезно поставить очередь и ограничить количество запросов, чтобы не отправлять десятки запросов в одну секунду без контроля.
Стоимость тоже лучше считать на уровне очереди. Одна операция photo-video стоит 25 ₽, поэтому 100 запусков — 2500 ₽, а 1000 запусков — 25 000 ₽, если каждый запуск тарифицируется как одна операция и дополнительных операций в цепочке нет. При предварительном upscale, редактировании или других шагах их стоимость добавляется отдельно.
| Количество запусков photo-video | Расчёт | Стоимость |
|---|---|---|
| 1 | 1 × 25 ₽ | 25 ₽ |
| 10 | 10 × 25 ₽ | 250 ₽ |
| 100 | 100 × 25 ₽ | 2500 ₽ |
| 1000 | 1000 × 25 ₽ | 25 000 ₽ |
Оплата происходит за запуск, без абонентской платы и без минимального платежа. При выпуске первого ключа на баланс начисляется 50 ₽ для пробного использования, поэтому одной такой суммы достаточно для двух полных запусков «Оживить фото», если не расходовать баланс на другие операции.
Текущий остаток можно получать через GET /balance, а список доступных операций и цен — через GET /services. Для production-интеграции удобно проверять баланс до постановки большой пачки задач и отдельно учитывать стоимость каждого запуска в собственной статистике.
Сценарии в продукте: аватарки, карточки, воспоминания
Самый простой пользовательский сценарий — оживление аватарки. Пользователь загружает портрет, выбирает действие «Оживить фото», при необходимости задаёт движение, а backend последовательно выполняет загрузку и запуск задачи. После готовности видео приложение получает результат через проверку задачи или callback.
В карточках товаров такой механизм можно использовать как дополнительный формат демонстрации изображения. Исходный снимок товара становится входом операции, а текстовая подсказка может задавать характер движения. При этом разработчику стоит хранить связь между ID товара, исходным URL изображения и ID задачи, чтобы результат можно было корректно вернуть в нужную карточку.
Третий сценарий — архивные фотографии и воспоминания. Здесь особенно важен контроль исходного файла: старое фото может потребовать предварительной обработки, а лишние шаги увеличивают итоговую стоимость. Если в цепочку добавить upscale за 50 ₽, а затем photo-video за 25 ₽, базовая стоимость двух операций составит 75 ₽ на одно изображение.
При больших объёмах удобно разделить систему на три компонента: загрузчик файлов, очередь генерации и обработчик результатов. Загрузчик отвечает за /uploads, очередь — за вызовы /generate с учётом лимита 60 запросов в минуту на ключ, а обработчик — за /tasks/{id} или входящие callback-запросы.
Для пользовательского интерфейса полезно хранить как минимум исходный файл, ссылку после загрузки, идентификатор задачи, статус, дату запуска и стоимость операции. Тогда можно показать пользователю, что изображение уже принято, задача выполняется, а после завершения — сохранить готовый результат рядом с исходником.
Отдельно стоит учитывать экономику повторных запусков. Если пользователь нажал «оживить» пять раз, это пять запусков по 25 ₽, а не одна операция с пятью вариантами. Поэтому кнопку повторного запуска лучше делать явной, а перед массовой генерацией показывать количество создаваемых задач и соответствующую стоимость.
Для автоматизации также пригодится callback_url. Вместо того чтобы постоянно спрашивать GET /tasks/{id}, backend может принять уведомление о готовности и обновить запись в базе. При этом обработчик callback должен быть рассчитан на повторную доставку события: полезно проверять ID задачи и не создавать второй результат, если та же задача уже отмечена как завершённая.
В итоге связка для сценария «оживить фото api» достаточно компактна: получить ключ, загрузить изображение через /uploads, запустить photo-video через /generate, дождаться состояния через /tasks/{id} или использовать callback. Основные проблемы возникают не в количестве маршрутов, а в проверке исходного файла, обработке асинхронности, ограничении частоты и расчёте стоимости на объёме.
Частые вопросы
Сколько стоит оживить одну фотографию через API?
Операция «Оживить фото» (photo-video) стоит 25 ₽ за один запуск. Если перед ней используются дополнительные операции, например увеличение качества за 50 ₽, их стоимость оплачивается отдельно.
Можно ли передать фотографию напрямую в генерацию?
Сценарий предусматривает отдельную загрузку через POST /uploads с последующим получением ссылки. Затем эта ссылка используется при запуске операции через POST /generate.
Как узнать, готово ли видео?
После запуска можно проверить состояние по маршруту GET /tasks/{id}. Для асинхронной обработки также предусмотрен необязательный callback_url: когда задача готова, на него приходит POST-запрос.
Есть ли ограничение на частоту запросов?
Да. На один API-ключ разрешено не более 60 запросов в минуту. При массовой обработке фотографий это стоит учитывать на уровне очереди запросов.
Что делать, если изображение не загружается?
Сначала проверьте, что файл действительно является изображением, корректно читается, имеет ожидаемый тип и не нарушает ограничения, заданные вашим приложением. Если конкретный допустимый формат или максимальный размер не указан в справке API, не следует приписывать сервису неподтверждённый лимит.
Где получить API-ключ?
После входа ключ выдаётся в разделе доступа к API. Он показывается один раз, поэтому после выпуска его нужно сохранить в безопасном месте, например в секретах backend-приложения.
