Genius-bot · 12 минут чтения
API генерации видео удобно проверять не с готового приложения, а с одного короткого сценария: отправить описание сцены, дождаться задачи и получить готовый MP4. Такой подход сразу показывает, какие части интеграции отвечают за запрос, ожидание и выдачу результата.
В этой статье разберём первый запуск через API сервиса: от авторизации до проверки статуса задачи. Отдельно разберём, как составлять описание для api генерации видео из текста, сколько стоит запуск и почему по данным доступной справки нельзя заранее назвать конкретную максимальную длительность или разрешение ролика. Получить API-ключ можно в разделе API после входа в аккаунт.
Важный момент для разработчика: документация, приведённая для этой статьи, фиксирует маршруты и цены, но не содержит точной схемы JSON для POST /generate и числовых ограничений по длительности и разрешению видео. Поэтому ниже не будут придуманные параметры вроде duration: 10 или resolution: "1080p". Сначала нужно посмотреть описание операции через GET /services и использовать поля, которые возвращает актуальная схема сервиса.
Что умеет генерация видео из текста сегодня
Для первого эксперимента задача выглядит просто: есть текстовое описание сцены, из него запускается операция video, после чего API возвращает идентификатор задачи. Затем приложение проверяет состояние через GET /tasks/{id} и забирает результат, когда обработка завершена.
Маршрут API имеет базовый адрес https://genius-bot.ru/wp-json/genius/v1. Для запуска операции используется POST /generate, для проверки состояния — GET /tasks/{id}. Отдельно доступны GET /services для списка операций и цен, GET /balance для остатка, а также POST /uploads, если в конкретном сценарии требуется предварительно загрузить файл.
Операция генерации видео по описанию называется video и стоит 119 ₽ за один запуск. Это именно цена операции: она не означает оплату за минуту, токен или секунду готового ролика.
| Операция | Цена за запуск | Что важно для первого теста |
|---|---|---|
Видео по описанию (video) |
119 ₽ | Текстовое описание сцены |
Оживить фото (photo-video) |
25 ₽ | Работа с исходным изображением |
Картинка по описанию (image) |
9 ₽ | Генерация изображения |
Изменить фото по описанию (image-edit) |
35 ₽ | Редактирование изображения |
Говорящий аватар (avatar) |
120 ₽ | Отдельная операция |
Оплата происходит за запуск, без абонентской платы и минимального платежа. При выпуске первого ключа на баланс начисляется 50 ₽ для пробы, поэтому одного стартового бонуса недостаточно для полного запуска операции video стоимостью 119 ₽.
Есть и техническое ограничение по частоте: один ключ может отправлять не более 60 запросов в минуту. Для одиночного ролика это не является центральной проблемой, но при автоматической обработке очереди её нужно учитывать уже на уровне клиента.
Первый запрос: описание сцены и параметры
Сначала получите ключ в разделе API. Он показывается один раз, поэтому его имеет смысл сохранить в переменную окружения, а не вписывать непосредственно в исходный код приложения.
Все запросы к API авторизуются заголовком Authorization со значением Bearer <ключ>. Перед первым запуском полезно проверить доступ и посмотреть список операций:
curl https://genius-bot.ru/wp-json/genius/v1/services \
-H "Authorization: Bearer $GENIUS_API_KEY"Этот запрос является хорошей первой точкой интеграции: он обращается к документированному маршруту GET /services и возвращает список доступных операций и цен. В частности, по нему можно проверить актуальное описание операции video, прежде чем формировать тело запроса на генерацию.
Аналогичная проверка на Python с библиотекой requests выглядит так:
import os
import requests
BASE_URL = "https://genius-bot.ru/wp-json/genius/v1"
API_KEY = os.environ["GENIUS_API_KEY"]
response = requests.get(
f"{BASE_URL}/services",
headers={
"Authorization": f"Bearer {API_KEY}"
},
timeout=30,
)
response.raise_for_status()
print(response.json())На этом месте есть принципиальный нюанс. В исходной справке для статьи указано, что POST /generate запускает операцию, но не приведён точный формат его JSON-тела. Поэтому безопасный пример запуска нельзя составить из выдуманных полей: например, названия prompt, service, duration или resolution нельзя выдавать за официальные параметры без их наличия в актуальном описании операции.
Практически схема первого запуска получается такой: запросить /services, взять из ответа актуальные параметры операции video, передать их в POST /generate, сохранить полученный идентификатор задачи и использовать его в GET /tasks/{id}. Если в запросе указывается callback_url, после завершения обработки сервис отправит на этот адрес POST.
Именно так стоит строить интеграцию, если код должен пережить изменение вспомогательных параметров API: базовый адрес, авторизация и маршруты известны заранее, а конкретную схему операции клиент получает из актуальной справки.
Ожидание и стоимость одного запуска
Генерация видео — асинхронная операция. После отправки задания приложение не должно предполагать, что MP4 уже доступен в том же HTTP-ответе. Идентификатор задачи используется для последующей проверки состояния через GET /tasks/{id}.
Минимальная архитектура клиента состоит из трёх функций: запуск, проверка и обработка готового результата. Это проще поддерживать, чем держать один HTTP-запрос открытым до окончания генерации.
import os
import time
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}"
}
# Тело generate нужно сформировать по актуальной схеме
# операции video из ответа /services.
payload = {
# параметры операции video
}
start = requests.post(
f"{BASE_URL}/generate",
headers=headers,
json=payload,
timeout=30,
)
start.raise_for_status()
task = start.json()
task_id = task["id"]
while True:
response = requests.get(
f"{BASE_URL}/tasks/{task_id}",
headers=headers,
timeout=30,
)
response.raise_for_status()
result = response.json()
print(result)
# Условие готовности нужно взять из фактического
# ответа GET /tasks/{id}.
if result.get("status") in {"completed", "failed"}:
break
time.sleep(5)Последний фрагмент намеренно не подменяет документацию догадкой: названия статусов и полей результата в предоставленной справке не указаны. Для реального клиента их нужно взять из ответа маршрута GET /tasks/{id} и уже после этого зафиксировать в коде.
Если обработка выполняется регулярно, вместо циклического опроса можно использовать webhook. В запросе передаётся необязательный параметр callback_url, после чего при готовности задачи сервис делает POST на указанный адрес. Такой вариант удобен для серверного приложения, которому не требуется постоянно держать отдельный цикл проверки.
Стоимость запуска видео составляет 119 ₽. Баланс можно проверить отдельным запросом:
curl https://genius-bot.ru/wp-json/genius/v1/balance \
-H "Authorization: Bearer $GENIUS_API_KEY"Для первого теста полезно проверять баланс до запуска, а после — ещё раз, если приложение ведёт собственный учёт расходов. При лимите 60 запросов в минуту это особенно важно для программ, которые создают задания в цикле.
Как описать сцену, чтобы получилось задуманное
В нейросеть видео api стоит передавать описание не как литературный рассказ, а как короткое техническое задание для сцены. В нём полезно последовательно указать объект, действие, окружение, движение камеры и визуальный характер кадра.
Например, вместо фразы «красивый автомобиль едет по городу» лучше описывать наблюдаемую сцену: «красный спортивный автомобиль движется по мокрой городской улице ночью, отражения неона на асфальте, камера плавно следует сбоку, автомобили на заднем плане слегка размыты». Здесь есть объект, действие, время суток, поверхность, фон и движение камеры.
Не стоит смешивать в одном первом тесте десять независимых событий. Если в одном описании одновременно задать смену локации, появление нескольких персонажей, сложное взаимодействие предметов и несколько движений камеры, становится труднее понять, какая часть инструкции дала неожиданный результат.
Для первого ролика лучше выбрать одну сцену с одним главным действием. Например:
Городская улица после дождя ночью. Красный спортивный автомобиль
медленно движется вдоль тротуара. На мокром асфальте отражаются
вывески и фонари. Камера плавно следует сбоку за автомобилем.
Кадр кинематографичный, фон слегка размыт.Такое описание задаёт не только предмет, но и его поведение. Слова «медленно движется» относятся к действию, «камера следует сбоку» — к съёмке, а «после дождя», «ночью» и «отражения» — к окружению и освещению.
Если результат отличается от задумки, лучше менять одну часть описания за раз. Например, сначала заменить движение камеры, затем уточнить действие автомобиля, а затем изменить окружение. При цене 119 ₽ за запуск такой подход помогает не тратить несколько запусков на хаотичный перебор формулировок.
Для text to video api особенно важно отделять то, что должно находиться в кадре, от того, что должно происходить. «Старый поезд» описывает объект, «проезжает через заснеженный лес» — действие и окружение, а «камера движется параллельно поезду» — способ наблюдения за сценой.
Если в ролике должен присутствовать человек, полезно конкретизировать видимые характеристики: одежду, положение тела и действие. Вместо «человек идёт» можно написать «мужчина в тёмном пальто идёт по пустой платформе, камера движется перед ним». При этом не стоит добавлять характеристики, которые никак не связаны с изображением и не нужны для сцены.
Отдельно стоит учитывать направление движения. Формулировка «автомобиль едет по улице» задаёт меньше ограничений, чем «автомобиль движется слева направо относительно камеры». Чем точнее сформулировано нужное действие, тем меньше неоднозначности в самом задании.
Ограничения по длине и разрешению
У генерации видео есть естественное ограничение по объёму вычисления: видео нельзя рассматривать как бесконечный текстовый ответ. Но в предоставленной справке сервиса нет конкретного числа, которое можно было бы честно указать как максимальную длительность ролика.
По той же причине нельзя без подтверждения назвать максимальное разрешение вроде 720p или 1080p. Эти значения должны браться из актуальной схемы операции video или из фактического ответа API, если сервис возвращает соответствующие параметры.
Это важное отличие от примеров, где разработчик заранее прописывает duration=10 и resolution=1080p. Если такие поля не указаны в документации, их нельзя считать гарантированной частью API. В интеграции лучше сначала получить список операций через GET /services и проверить доступные параметры именно для текущей версии video.
С практической точки зрения ограничение длины влияет и на постановку задачи. Если сценарий состоит из пяти последовательных событий, не стоит автоматически пытаться описать их одним длинным промптом. Для тестирования API полезнее начать с одного действия, получить короткую сцену и только после этого решать, как собирать более сложную последовательность в приложении.
Если приложению требуется длинная последовательность, архитектура может строиться вокруг нескольких отдельных задач. Каждая задача отвечает за одну сцену, а приложение затем работает с полученными файлами как с отдельными результатами. Конкретный способ объединения файлов уже относится к логике самого приложения, а не к заявленной операции video.
Не следует также путать ограничение длины ролика с ограничением частоты запросов. Первое относится к параметрам конкретной видеогенерации, а второе известно точно: не более 60 запросов в минуту на один API-ключ.
Куда девать готовый файл в приложении
После завершения задачи серверному приложению нужно получить результат из ответа GET /tasks/{id}. Предоставленная справка говорит, что этот маршрут возвращает состояние и результат задачи, но не фиксирует конкретное название поля, в котором находится ссылка на MP4.
Поэтому на этапе интеграции стоит сначала вывести полный JSON результата и посмотреть его структуру. После этого ссылку можно передать пользователю, сохранить в базе данных или скачать на собственное хранилище приложения — в зависимости от того, как устроен ваш продукт.
Если приложение не должно самостоятельно опрашивать API, используйте callback_url. После готовности задачи сервис отправит POST на указанный адрес, и ваш сервер сможет обработать уведомление, найти соответствующий task_id и продолжить свой сценарий.
Типичный серверный поток получается таким: пользователь вводит описание → приложение отправляет задачу → сохраняет идентификатор → получает уведомление или проверяет статус → извлекает результат → показывает или сохраняет готовое видео.
Если исходный сценарий требует файла, предусмотрен отдельный маршрут POST /uploads. Он используется для загрузки файла и получения ссылки, которую затем можно применять в операции, если это предусмотрено её актуальной схемой.
Для разработки удобно не смешивать эти этапы в одном обработчике HTTP-запроса пользователя. Запуск задачи, ожидание результата и выдача файла лучше сделать отдельными функциями или этапами фоновой обработки. Тогда интерфейс приложения не зависит напрямую от времени генерации.
Ещё один практический момент — хранение ключа. Значение из заголовка Authorization не стоит помещать в JavaScript-код браузера или коммитить в репозиторий. Сервер приложения может брать его из переменной окружения GENIUS_API_KEY, как в примерах выше.
Для самого первого теста достаточно проверить четыре вещи: ключ принимается, операция video присутствует в списке сервисов, баланс позволяет выполнить запуск и результат задачи возвращается через GET /tasks/{id}. После этого уже имеет смысл добавлять webhook, очереди и хранение файлов.
У API есть и совместимый с OpenAI интерфейс для чата: POST /chat/completions и GET /models работают в том же формате, что и у OpenAI, поэтому в клиентской библиотеке меняются base_url и ключ. Для этой статьи он не нужен: генерация видео запускается через отдельную операцию video.
Частые вопросы
Сколько стоит один запуск видео?
Операция «Видео по описанию» (video) стоит 119 ₽ за один запуск. Оплата идёт за запуск, без абонентской платы и минимального платежа.
Можно ли сразу указать длительность ролика в запросе?
В предоставленной справке не указано точное название параметра длительности и его допустимые значения. Поэтому перед использованием такого поля нужно посмотреть актуальную схему операции video, а не добавлять параметр по предположению.
Как понять, что видео уже готово?
Для этого используется GET /tasks/{id}. Маршрут возвращает состояние и результат задачи; конкретные названия полей состояния нужно брать из фактического ответа API.
Нужно ли постоянно опрашивать API?
Нет. Для задачи можно передать необязательный callback_url. Когда обработка завершится, сервис отправит POST на указанный адрес.
Какой лимит запросов у ключа?
Не более 60 запросов в минуту на один API-ключ. При создании очереди задач этот лимит нужно учитывать отдельно от стоимости запусков.
Где взять ключ для API?
После входа ключ выдаётся в разделе API и показывается один раз. Открыть страницу управления API-ключом можно перед первым тестовым запросом.
