Veo 3: как пользоваться API на примере Veo 3.1
Veo 3 через API Relay используют так: создают ключ, выбирают veo-3.1, отправляют описание сцены на /v1/videos и сохраняют видео из ответа либо после завершения задачи. В каталоге Relay есть Veo 3.1; инструкция не относится к интерфейсу Google и его подпискам. Для нового аккаунта сначала нужно выполнить условие оплаченных пополнений, описанное ниже.
Коротко
Используйте точный ID
veo-3.1, а не предположение о версии Veo 3.0.Начните с одной простой сцены и проверьте параметры в карточке модели.
Сохраните ID задачи, читайте статус и скачивайте файл после
completed.
Veo 3: как пользоваться моделью Veo 3.1 в Relay
Откройте каталог видео, найдите veo-3.1 и прочитайте её карточку. Там проверяют ID, тип модели и цену. Параметры длительности и размера сверяйте с руководством модели; наличие ID не подтверждает любую комбинацию полей. Не копируйте идентификатор из старого видео или поста: точное имя в API должно совпадать с каталогом. Запрос с несуществующей версией не станет рабочим после повторной отправки.
Перед запуском создайте отдельный ключ и передайте его процессу как RELAY_API_KEY. Не вставляйте ключ в промпт, URL или исходный код. Для первого опыта достаточно одной модели и одной сцены. Больше вариантов только усложнят диагностику, если ответ окажется ошибкой.
Как описать первую сцену
Хороший первый промпт содержит предмет, действие, место, свет, камеру и ограничения. Например: «белая чашка на деревянном столе, над ней поднимается пар, неподвижная камера, мягкий дневной свет, без текста и логотипов». В нём нет сюжета из десяти действий и противоречивых указаний.
Сначала оставьте один план и один объект. Не требуйте точный заголовок в кадре или монтаж из нескольких локаций. Если результат прошёл простую проверку, меняйте только один элемент: добавьте движение камеры или второй объект. Так понятно, что повлияло на следующую генерацию.
Перед отправкой запишите критерий приёмки. Для чашки это сохранение объекта, видимый пар, неподвижная камера и отсутствие текста. Длительность выбирайте по руководству модели. Если нужная комбинация не указана, не гадайте и не маскируйте ошибку повтором.
Как создать задачу через API
Relay принимает видеозапросы на POST /v1/videos. Для создания нужны ключ и JSON. Сначала подготовьте файл запроса, затем отправьте его: curl сохранит тело ответа в video.json и напечатает HTTP-статус.
До запуска проверьте ограничения нового аккаунта. Создание видео недоступно до оплаченных пополнений на $10 и отвечает 402 new_account_limit; приветственный бонус в порог не входит. Способы и условия пополнения смотрите на странице цен и в кабинете.
Задайте RELAY_API_KEY и VIDEO_SECONDS в окружении. Выберите длительность по руководству модели: предел шлюза в 600 секунд не означает, что модель принимает любое значение внутри него. Сохраните следующий код как request.py и запустите python3 request.py, затем выполните curl. Поле размера опущено: универсальное значение для этих моделей здесь не подтверждено.
import json
import os
from pathlib import Path
seconds = int(os.environ["VIDEO_SECONDS"])
if not 1 <= seconds <= 600:
raise ValueError("VIDEO_SECONDS должен быть целым числом от 1 до 600")
body = {
"model": "veo-3.1",
"prompt": "Белая чашка на деревянном столе, над чашкой поднимается пар, неподвижная камера, мягкий дневной свет, без текста и логотипов.",
"duration_seconds": seconds,
}
Path("request.json").write_text(json.dumps(body, ensure_ascii=False), encoding="utf-8")curl --fail-with-body https://relay-llm.ru/v1/videos \
-H "Authorization: Bearer $RELAY_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @request.json \
--output video.json --write-out '%{http_code}\n'Что делать с ответом 200 или 202
Прочитайте HTTP-статус, который напечатал curl. При ошибке не пытайтесь декодировать тело как видео: сначала прочитайте JSON ошибки. При 200 видео готово в data[0].b64_json. Сохраните следующий код как save_video.py и запустите python3 save_video.py рядом с ответом:
import base64
import json
from pathlib import Path
reply = json.loads(Path("video.json").read_text(encoding="utf-8"))
encoded = reply["data"][0]["b64_json"]
Path("video.mp4").write_bytes(base64.b64decode(encoded))При 202 в video.json находятся id и status: "queued". Задайте полученный ID в VIDEO_JOB_ID и проверяйте статус с паузой в несколько секунд:
curl --fail-with-body "https://relay-llm.ru/v1/videos/$VIDEO_JOB_ID" \
-H "Authorization: Bearer $RELAY_API_KEY"queued означает ожидание, running выполнение. После completed скачайте файл:
curl --fail-with-body "https://relay-llm.ru/v1/videos/$VIDEO_JOB_ID/content" \
-H "Authorization: Bearer $RELAY_API_KEY" \
--output video.mp4Сохраните файл до expires_at. Статус проверяется без новой генерации и без оплаты. При failed прочитайте объект error и сохраните ID; по документации Relay списания за такую задачу нет. При сетевом обрыве после POST не создавайте дубликат вслепую: сначала проверьте известную задачу и журнал. Полный контракт приведён в документации видео.
Как проверить готовый ролик
Посмотрите файл целиком. Проверьте чашку, пар, неподвижную камеру и отсутствие текста. Если нарушен один признак, меняйте в промпте именно его. Не меняйте одновременно сцену, модель, размер и длительность, иначе следующий результат не объяснит причину различия.
Храните рядом с файлом промпт, модель, параметры, ID задачи и дату. Это даст вам повторяемый пример для следующего запуска и поможет команде не перепутать похожие варианты. Видеогенерация может дать технически готовый ролик, который не подходит редакционно, поэтому критерии приёмки нужны до запуска.
Как проверить цену и расход
Цена и параметры видео меняются вместе с каталогом, поэтому проверяйте карточку модели и страницу цен перед серией задач. В журнале кабинета видны выполненные вызовы. В бюджет включайте отобранные и отбракованные ролики, если задача выполнилась: редакционная непригодность не отменяет выполненную генерацию.
При 401 проверьте ключ, при 404, путь и ID задачи, при 402, баланс. Для 429 прочитайте правила лимитов и дождитесь паузы, не создавайте пачку одинаковых задач. В сообщение поддержки передавайте безопасный идентификатор запроса, но не ключ.
Почему готовый файл может не подойти
Статус completed означает готовность файла, а не выполнение всех творческих требований. Если пар пропал или чашка изменила форму, сохраните пример брака и исправьте описание одного признака. Точные титры добавьте при монтаже. Не рассчитывайте получить синхронный звук или надпись без отдельной проверки возможностей модели и просмотра результата.
Это инструкция «Veo 3: как пользоваться» в Google или в Relay?
Это вызов API Relay с моделью veo-3.1. Подписка и интерфейс Google в нём не используются.
Почему API вернул ID, а не файл?
Модель создала асинхронную задачу. Проверяйте её статус и скачивайте файл после completed.
Когда нужно сохранять видео?
Сразу после completed, до времени expires_at, указанного для задачи.
Где проверить допустимые параметры?
ID и цену проверьте в каталоге видео, формат запроса в документации API. Допустимые для модели значения сверяйте с её руководством.