К содержимому
Блог

Veo 3: как пользоваться API на примере Veo 3.1

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 или исходный код. Для первого опыта достаточно одной модели и одной сцены. Больше вариантов только усложнят диагностику, если ответ окажется ошибкой.

Veo 3.1Цена не указана

Как описать первую сцену

Хороший первый промпт содержит предмет, действие, место, свет, камеру и ограничения. Например: «белая чашка на деревянном столе, над ней поднимается пар, неподвижная камера, мягкий дневной свет, без текста и логотипов». В нём нет сюжета из десяти действий и противоречивых указаний.

Сначала оставьте один план и один объект. Не требуйте точный заголовок в кадре или монтаж из нескольких локаций. Если результат прошёл простую проверку, меняйте только один элемент: добавьте движение камеры или второй объект. Так понятно, что повлияло на следующую генерацию.

Перед отправкой запишите критерий приёмки. Для чашки это сохранение объекта, видимый пар, неподвижная камера и отсутствие текста. Длительность выбирайте по руководству модели. Если нужная комбинация не указана, не гадайте и не маскируйте ошибку повтором.

Как создать задачу через 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. Поле размера опущено: универсальное значение для этих моделей здесь не подтверждено.

python
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")
bash
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 рядом с ответом:

python
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 и проверяйте статус с паузой в несколько секунд:

bash
curl --fail-with-body "https://relay-llm.ru/v1/videos/$VIDEO_JOB_ID" \
  -H "Authorization: Bearer $RELAY_API_KEY"

queued означает ожидание, running выполнение. После completed скачайте файл:

bash
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. Допустимые для модели значения сверяйте с её руководством.

Посмотреть модель

Модели из статьи

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.