Veo Reference Images API Tutorial: From Assets to Video

AI Overview

Сколько справочных изображений может использовать API Veo?

Veo 3.1 поддерживает до трёх справочных изображений для одного человека, персонажа или продукта. Используйте небольшой, логически связанный набор, чётко демонстрирующий идентичность, материалы и форму, а не три несвязанных композиции.

Справочные изображения — это то же самое, что первый и последний кадры?

Нет. Параметр referenceImages обеспечивает согласованность субъекта или стиля, тогда как параметр image задаёт первый кадр, а lastFrame ограничивает конечный кадр. Выберите один из этих режимов в зависимости от того, какой элемент должен оставаться неизменным.

Какая модель Veo поддерживает справочные изображения?

В текущей документации Google по Gemini API справочные изображения указаны для моделей Veo 3.1 и Veo 3.1 Fast, но не для Veo 3.1 Lite или Veo 3.0. Генерация с использованием справочных изображений имеет продолжительность восемь секунд.

Что следует сохранять при интеграции с API?

Сохраняйте идентификаторы входных ресурсов, нормализованный промпт, модель и конфигурацию, имя операции, финальный файл и результат проверки. Такая запись позволяет воспроизвести неудачную генерацию, а не превращать каждую повторную попытку в случайное угадывание.

Выберите режим справочных изображений до начала кодирования

Практическая задача, стоящая за руководством по API Veo для справочных изображений, заключается не только в отправке данных в формате base64. Разработчикам необходимо понимать, какой тип визуального контроля соответствует конкретному кадру, какие поля связаны между собой и как восстановить корректную работу, если выходной результат игнорирует деталь продукта или отклоняется от заданного образа персонажа.

Новый концепт набора справочных изображений, созданный специально для этого руководства. Всадник, шафрановая куртка, янтарные очки и кобальтовый мотоцикл служат чёткими якорями непрерывности; данный пример не позиционируется как эталонный тест для Veo.

Начните с выбора одного из трёх режимов:

Разница принципиальна. Портрет персонажа в referenceImages — это лишь ориентир, а не гарантия того, что первый сгенерированный кадр будет пиксель-в-пиксель воспроизводить этот портрет. Напротив, начальный кадр image жёстко фиксирует исходную композицию, но не предоставляет трёх отдельных ракурсов идентичности. Не смешивайте эти концепции в промпте, а затем не обвиняйте API в выборе неверного ограничения.

Согласно текущей таблице Google по Gemini API, параметр referenceImages поддерживает до трёх объектов VideoGenerationReferenceImage в моделях Veo 3.1 и Veo 3.1 Fast. Модель Veo 3.1 Lite не поддерживает этот параметр. Запрос со справочными изображениями генерирует одно видео длительностью восемь секунд, поддерживает как горизонтальную, так и вертикальную ориентацию и позволяет создавать ролики с разрешением 720p, 1080p или 4K в полных маршрутах Veo 3.1. Повышение разрешения увеличивает задержку и стоимость, поэтому перед масштабированием доставки убедитесь в соответствии с условиями контракта на генерацию.

Для более широкого объяснения на уровне интерфейса до реализации конечной точки см. Руководство по потоку Google Flow и рабочему процессу Veo.

Подготовка справочных изображений и промпта

Создайте единый логически связанный набор ресурсов

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

Справочный портрет персонажа: обратите внимание на форму лица, силуэт причёски, панели куртки и янтарные линзы очков. Читаемый справочный кадр полезнее драматичного, но плохо различимого портрета.

Справочное изображение продукта: полная геометрия колёс, силуэт рамы, кобальтовые панели, куртка и очки видны при нейтральном свете после дождя.

Предварительно обработайте изображения перед платным запросом. Убедитесь в корректности MIME-типа, отклоните пустые файлы, выполните однократное декодирование для выявления повреждений и сохраняйте исходное соотношение сторон, если ваша обработка намеренно не предусматривает кадрирование. Сохраните контрольную сумму и внутренний идентификатор ресурса. Base64 увеличивает размер запроса, поэтому избегайте многократного кодирования чрезмерно крупных оригиналов, когда правильно масштабированная производная версия сохраняет все видимые детали.

Напишите промпт с учётом требований к сохранению

Хороший промпт сообщает Veo, что происходит в сцене и что должно оставаться неизменным. Используйте следующий универсальный порядок:

Средний трекинг-кадр. Всадник с серебристыми волосами в шафрановой куртке едет на матовом кобальтовом мотоцикле по мокрой прибрежной дороге на рассвете. Сохраните её лицо, короткую стрижку «боб», янтарные очки с защитным экраном, панели куртки, геометрию корпуса мотоцикла, количество колёс и кобальтовое покрытие. Брызги океана движутся естественно; камера перемещается параллельно без вращения вокруг объекта. Оригинальный звук ветра, шин и далёкого прибоя; без диалогов, текста и логотипов.Называйте ссылки по видимым признакам, а не по именам файлов. В каждом восьмисекундном кадре используйте только одно основное действие и одно движение камеры. Противоречивые команды — например, «неподвижная камера» и «быстрое вращение вокруг объекта» — создают проблему координации, которую никакое опорное изображение решить не может. В руководстве по промптингу из изображения в видео описан компактный шаблон «субъект–действие–камера–сохранение», который можно повторно использовать.

Отправьте запрос Veo 3.1

Создайте ссылки на ресурсы в JavaScript

С текущей версией @google/genai SDK представьте каждое подготовленное изображение как объект, содержащий поля imageBytes и mimeType, затем оберните его в объект с полем referenceType: 'asset'. Библиотека SDK считывает ключ API из вашей среды выполнения; храните его на сервере, ни в коем случае не в браузерном JavaScript.

import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({});
const assets = [riderImage, motorcycleImage, glassesImage].map((image) => ({
  image,
  referenceType: 'asset',
}));

let operation = await ai.models.generateVideos({
  model: 'veo-3.1-generate-preview',
  prompt,
  config: {
    referenceImages: assets,
    aspectRatio: '16:9',
    durationSeconds: 8,
    resolution: '720p',
  },
});

Названия полей могут различаться между интерфейсами Gemini API и Vertex AI, поэтому зафиксируйте конкретную версию SDK и проверьте её соответствие официальной документации для конечной точки, которую вы фактически развертываете. Не копируйте JSON-структуру сторонней обёртки в конечную точку Google. Вместо полного base64-представления регистрируйте обезличенный манифест запроса.

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

Опрос, загрузка и сохранение результата

Генерация видео в Veo выполняется асинхронно. Первоначальный вызов возвращает долгоживущую операцию, а не готовый MP4-файл. Осуществляйте опрос по имени операции с разумным интервалом, прекращайте его по достижении ограниченного таймаута и сохраняйте идентификатор операции, чтобы при перезапуске фонового процесса можно было возобновить выполнение, а не отправлять дублирующую задачу.

while (!operation.done) {
  await new Promise((resolve) => setTimeout(resolve, 10_000));
  operation = await ai.operations.getVideosOperation({ operation });
}

const generated = operation.response.generatedVideos[0];
await ai.files.download({
  file: generated.video,
  downloadPath: `outputs/${jobId}.mp4`,
});

Google временно хранит сгенерированные видео на своих серверах в течение двух дней, поэтому своевременно загружайте их в хранилище, находящееся под вашим контролем. Убедитесь, что файл существует, имеет ненулевой размер, корректно декодируется как видео и соответствует ожидаемой длительности. Сохраните кадр-постер для предварительного просмотра, но никогда не рассматривайте постер как подтверждение того, что всё видео воспроизводится без артефактов.

Veo 3.1 cinematic video example for full-clip inspection

Просматривайте полный клип для оценки идентичности, окружения, работы камеры и аудиосопровождения. Движущийся файл выявляет ошибки, которые скрывает одна привлекательная статичная кадровая картинка.

Проверка согласованности и обработка сбоев

Проведите проверку с помощью фиксированной сетки приёмки

Просматривайте каждый результат в нормальном темпе, а затем ещё раз — в момент наиболее сложного движения. Для каждого случая фиксируйте один из трёх исходов: «принято», «требуется доработка» или «отклонено» — по одним и тем же критериям:

Альтернативная композиция изменяет время съёмки и кадрирование, сохраняя те же якоря непрерывности. Используйте такой кадр для оценки того, сохраняется ли идентичность ресурсов при смене сцены.

Если все сгенерированные результаты теряют одну и ту же характеристику, скорее всего, неверно выбраны опорные изображения или иерархия промптов. Если ошибки возникают случайным образом, зафиксируйте входные данные и повторите генерацию перед тем, как полностью переписывать всё. Если композиция должна заканчиваться строго заданным изображением, используйте параметры image и lastFrame, а не добавляйте в referenceImages дополнительные инструкции по сохранению.

Seedance product-motion output for comparing geometry and controlled camera behavior

Это видео сгенерировано другой моделью и относится к другому типу кадра; оно приведено в качестве примера реального движения для оценки, а не как эталон Veo. Применяйте тот же набор критериев для геометрии и поведения камеры.

Разделяйте ошибки провайдера от творческих неудач. Ошибки аутентификации, превышения квоты, недопустимого MIME-типа, неподдерживаемой конфигурации, фильтрации по безопасности, таймаута или завершённого, но непригодного к использованию клипа требуют разных подходов к обработке. Автоматически повторяйте только временные сетевые или сервисные сбои. Отклонённый промпт или некачественный визуальный результат должны направляться на ручную проверку, а не попадать в бесконечный цикл платных попыток.Перед окончательным экспортом подтвердите частоту поставки с помощью руководства по частоте кадров для ИИ-видео, поскольку сгенерированная частота 24 кадра в секунду и настройки доставки на платформе связаны между собой, но не являются взаимозаменяемыми решениями.

Интегрируйте это в рабочий процесс Seedance Agent

Сырой API Veo подходит, когда разработчик уже самостоятельно управляет хранением ассетов, версионированием промптов, опросом операций, утверждениями и политикой повторных попыток. Seedance Agent полезен, когда реальная задача требует более чем одного вызова: преобразование брифа в список кадров, назначение ролей для справочных материалов, выбор поддерживаемой модели для каждого кадра, проверка реальных результатов и повторный запуск только тех сегментов, которые завершились с ошибкой.

Для последовательности с райдером агент может однократно зарегистрировать портрет, мотоцикл и очки; создать отдельные задания — для трекингового кадра вдоль побережья и для финального кадра в синий час; обеспечить согласованность правил сохранения для обоих заданий; и предоставить оба клипа на утверждение. API остаётся слоем генерации, тогда как агент управляет производственным состоянием. Это снижает риск случайных дублирующих запросов и предотвращает ситуацию, при которой позднее редактирование промпта незаметно изменяет канонический набор ассетов.

Оценивайте стоимость за утверждённую секунду, а не за количество выполненных запросов. Сравните Veo 3.1 с другими вариантами по таким параметрам, как стабильность идентичности, пригодность финальных кадров, время проверки и количество повторных запусков, используя сравнение Seedance 2.5 и Veo 3.1. Цель состоит не в том, чтобы принудительно пропускать каждый кадр через одну и ту же модель, а в том, чтобы обеспечить последовательную видеопоследовательность с минимально возможным количеством избежимых правок.

Заключение

Надёжная интеграция API ссылочных изображений Veo начинается с выбора подходящего режима управления, подготовки до трёх логически связанных ссылочных ассетов, написания одного чёткого промпта, описывающего движение и сохранение, отправки корректного запроса Veo 3.1, сохранения долгоживущей операции, загрузки результатов до истечения срока хранения и проверки полного клипа по фиксированной шкале оценок. Отделяйте временные повторные вызовы API от творческих повторных запусков и переключайтесь на интерполяцию первого и последнего кадров, когда точность конечных точек важнее гибкости в указании ассетов; если проект требует планирования кадров, совместного использования ссылочных материалов, маршрутизации моделей, этапов утверждения и целенаправленных повторных запусков вокруг вызова API, начните рабочий процесс с Seedance Agent →