Veo 참조 이미지 API 튜토리얼: 자산에서 비디오로

AI Overview

Veo API는 최대 몇 개의 참조 이미지를 사용할 수 있나요?

Veo 3.1은 한 사람, 캐릭터 또는 제품당 최대 세 개의 참조 이미지를 허용합니다. 서로 관련 없는 세 가지 구성 대신, 정체성, 재질, 형태를 명확히 보여주는 작고 일관된 세트를 사용하세요.

참조 이미지는 첫 번째 프레임과 마지막 프레임과 동일한가요?

아니요. referenceImages는 주체 또는 스타일의 일관성을 안내하는 데 사용되며, image는 첫 번째 프레임을 설정하고 lastFrame은 종료 프레임을 제약합니다. 고정되어야 하는 요소에 따라 하나의 모드를 선택하세요.

어떤 Veo 모델이 참조 이미지를 지원하나요?

Google의 현재 Gemini API 문서에서는 Veo 3.1 및 Veo 3.1 Fast에서만 참조 이미지를 지원한다고 명시되어 있으며, Veo 3.1 Lite나 Veo 3.0은 지원하지 않습니다. 참조 이미지를 사용한 생성은 8초 길이로 실행됩니다.

API 통합 시 어떤 정보를 저장해야 하나요?

입력 자산 ID, 정규화된 프롬프트, 모델 및 구성, 작업 이름, 최종 파일, 검토 결과를 저장하세요. 이 기록을 통해 실패한 샷을 재현 가능하게 하여, 매번 반복 시도 시 막연한 추측을 피할 수 있습니다.

코딩 전에 참조 모드를 선택하세요

Veo 참조 이미지 API 튜토리얼의 실무적 핵심은 단순히 base64 데이터를 전송하는 것이 아닙니다. 개발자는 촬영에 가장 적합한 시각적 제어 방식을 파악하고, 관련 필드를 그룹화하며, 출력 결과가 제품 세부 사항을 무시하거나 캐릭터에서 벗어날 경우 어떻게 복구할지 알아야 합니다.

이 가이드를 위해 새롭게 제작된 참조 세트 개념입니다. 라이더, 샤프란색 자켓, 앰버색 안경, 코발트색 오토바이는 명확한 연속성 기준점을 제공합니다. 이는 Veo 벤치마크로 제시되지 않습니다.

다음 세 가지 모드 중 하나를 먼저 선택하세요:

차이점이 중요합니다. referenceImages 내 캐릭터 초상화는 지침일 뿐이며, 첫 렌더링 프레임이 해당 초상화를 픽셀 단위로 정확히 재현한다는 보장은 없습니다. 반대로, 시작 image는 초기 구성을 고정하지만 세 가지 별개의 정체성 관점을 제공하지는 않습니다. 프롬프트에서 개념을 혼합한 후 API가 잘못된 제약 조건을 선택했다고 탓하지 마세요.

Google의 현재 Gemini API 표에 따르면, referenceImages는 Veo 3.1 및 Veo 3.1 Fast에서 최대 세 개의 VideoGenerationReferenceImage 객체를 지원합니다. Veo 3.1 Lite는 이 필드를 지원하지 않습니다. 참조 이미지 요청은 하나의 비디오를 생성하며, 8초 길이를 사용하고 가로형 또는 세로형 모두 지원합니다. 전체 Veo 3.1 경로에서는 720p, 1080p 또는 4K 해상도로 생성할 수 있습니다. 해상도가 높을수록 지연 시간과 비용이 증가하므로, 배포 규모를 확장하기 전에 샷 계약을 반드시 검증하세요.

엔드포인트 구축 전에 더 포괄적인 인터페이스 수준 설명이 필요하시다면, Google Flow 및 Veo 워크플로우 가이드를 참조하세요.

참조 이미지 및 프롬프트 준비

하나의 일관된 자산 세트 구축

정체성이 일치하는 참조 이미지를 사용하세요. 유용한 세 이미지 패키지는 깔끔한 얼굴 및 의상 전면도, 제품 기하학적 전면도, 그리고 반드시 유지되어야 할 작은 액세서리로 구성될 수 있습니다. 색온도, 렌즈 왜곡, 비율을 호환되도록 유지하세요. 한 이미지에 코발트색 오토바이가 있고 다른 이미지에 네이비색 섀시가 나타난다면, 프롬프트는 어느 기하학이 기준인지 신뢰성 있게 결정할 수 없습니다.

캐릭터 참조: 얼굴 윤곽, 머리카락 실루엣, 자켓 패널, 앰버 렌즈를 점검하세요. 극적이나 가려진 초상보다는 읽기 쉬운 참조가 더 유용합니다.

제품 참조: 전체 바퀴 기하학, 프레임 실루엣, 코발트 패널, 자켓, 안경이 비 후 중립 조명 아래에서 선명하게 보입니다.

유료 요청 전에 이미지를 사전 처리하세요. MIME 유형을 확인하고, 빈 파일은 거부하며, 손상 여부를 확인하기 위해 한 번 디코딩한 후, 파이프라인이 의도적으로 자르지 않는 한 원본 종횡비를 유지하세요. 체크섬과 내부 자산 ID를 저장하세요. Base64는 요청 크기를 증가시키므로, 모든 시각적 세부 정보를 충분히 유지하는 올바른 크기의 파생 이미지가 존재할 때 과도하게 큰 마스터를 반복 인코딩하지 마세요.

보존을 고려한 프롬프트 작성

좋은 프롬프트는 Veo에게 무엇이 발생해야 하고 무엇이 안정적으로 유지되어야 하는지를 명확히 알려줍니다. 다음 재사용 가능한 순서를 사용하세요:

중간 추적 샷. 은발의 라이더가 샤프란색 자켓을 입고 매트 코발트색 오토바이를 타고 해안가 젖은 도로를 일출 때 달립니다. 그녀의 얼굴, 짧은 보브 실루엣, 앰버 비저 안경, 자켓 패널, 오토바이 본체 기하학, 바퀴 수, 코발트 마감을 유지하세요. 바다 물보라가 자연스럽게 움직이고, 카메라는 회전 없이 평행하게 추적합니다. 원생 바람 소리, 타이어 소리, 멀리서 들리는 파도 소리만 포함; 대사, 텍스트, 로고는 없음.가시적 특징(예: 외형, 색상, 형태 등)을 기준으로 참조 이미지를 명명하고, 파일명을 기준으로 하지 마십시오. 8초 분량의 촬영 구간당 하나의 주요 액션과 하나의 카메라 동작만을 지정하십시오. “고정 카메라”와 “빠른 오르빗”처럼 모순되는 명령은 어떤 참조 이미지로도 해결할 수 없는 조정 문제를 유발합니다. 이미지-비디오 프롬프팅 가이드에서는 재사용 가능한 간결한 ‘주제-액션-카메라-보존’ 패턴을 제공합니다.

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 가이드에서 표준화된 작업 레코드가 공급업체별 UI 메모리보다 더 신뢰할 수 있는 이유를 설명합니다.

출력 결과 폴링, 다운로드 및 저장

Veo 비디오 생성은 비동기 방식입니다. 초기 호출은 완료된 MP4 파일이 아니라 장시간 실행되는 작업(Operation)을 반환합니다. 적절한 간격으로 작업 이름을 통해 폴링하고, 사전에 정의된 시간 제한에 도달하면 중단하십시오. 또한 작업 ID를 영구 저장하여 워커 재시작 시 중복 작업 제출이 아니라 이어서 진행할 수 있도록 하십시오.

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은 현재 생성된 비디오를 서버에 2일간 보관하므로, 즉시 사용자가 관리하는 저장소로 다운로드하십시오. 파일이 존재하며, 크기가 0보다 크고, 비디오 형식으로 디코딩되며, 예상 지속 시간과 일치함을 확인하십시오. 검토용 포스터 프레임을 저장하되, 포스터 프레임을 전체 동작의 정확성 증거로 간주해서는 안 됩니다.

Veo 3.1 시네마틱 비디오 예시 — 전체 클립 검사를 위한 용도

정체성, 환경, 카메라, 오디오의 연속성을 확인하려면 전체 클립을 반드시 재생하십시오. 움직이는 파일은 단 하나의 매력적인 프레임이 숨기는 결함을 드러냅니다.

일관성 검증 및 오류 처리

고정된 승인 그리드를 활용한 검토

각 출력물을 일반 속도로 한 번, 그리고 가장 복잡한 동작 구간 근처에서 다시 한 번 검토하십시오. 동일한 기준으로 매번 ‘통과’, ‘수정’, 또는 ‘불합격’ 여부를 기록하십시오.

대체 구성은 시간과 프레이밍을 변경하면서도 동일한 연속성 앵커를 유지합니다. 이와 같은 프레임을 사용해 자산 정체성이 장면 변경에도 살아남는지 판단하십시오.

모든 출력물에서 동일한 요소가 일관되게 소실된다면, 참조 이미지나 프롬프트 계층 구조에 문제가 있을 가능성이 높습니다. 오류가 무작위로 다양하게 발생한다면, 입력을 고정한 상태에서 재실행한 후 모든 내용을 다시 작성하기 전에 원인을 분석하십시오. 구성이 정확히 설계된 이미지에서 끝나야 한다면, referenceImages에 추가 보존 언어를 삽입하는 대신 image + lastFrame을 사용하십시오.

Seedance 제품 동작 출력 — 기하학적 정확성 및 제어된 카메라 동작 비교용

이는 다른 모델 및 촬영 유형이며, Veo 벤치마크가 아닌 실제 동작 검토 예시로 제공됩니다. 동일한 기하학 및 카메라 평가 기준을 적용하십시오.

공급업체 오류와 창의적 실패를 구분하십시오. 인증 오류, 할당량 초과, 잘못된 MIME 유형, 지원되지 않는 설정, 안전성 필터링, 타임아웃, 완료되었으나 사용 불가능한 클립 등은 각각 다른 대응이 필요합니다. 일시적인 전송 오류 또는 서비스 오류에 대해서만 자동 재시도를 허용하십시오. 거부된 프롬프트나 시각적 결과가 부적절한 경우, 인간 검토로 되돌려 보내야 하며, 무한히 반복되는 유료 루프에 진입해서는 안 됩니다.최종 내보내기 전에 AI 비디오 프레임 속도 가이드를 참조하여 배포 주기를 확인하세요. 생성된 24fps 설정과 플랫폼 배포 설정은 관련이 있지만 상호 교환 가능한 결정이 아닙니다.

이를 Seedance Agent 워크플로우에 통합하기

원시 Veo API는 개발자가 이미 애셋 저장소, 프롬프트 버전 관리, 작업 폴링, 승인 절차 및 재시도 정책을 자체적으로 운영할 때 적합합니다. 실제 작업이 단일 API 호출을 넘어서 여러 단계로 이어질 경우 — 예를 들어, 간략한 요약서를 촬영 목록으로 전환하고, 참조 역할을 할당하며, 촬영별로 지원되는 모델을 선택하고, 실제 출력물을 검토한 후 실패한 구간만 다시 실행하는 경우 — Seedance Agent가 유용합니다.

라이더 시퀀스의 경우, 에이전트는 초상화, 오토바이, 안경을 한 번만 등록하면 되며, 해안 추적 촬영과 블루아워(황혼) 엔딩을 별도의 작업으로 생성할 수 있습니다. 또한 두 작업의 보존 규칙을 일관되게 유지하고, 두 클립 모두를 승인용으로 공개할 수 있습니다. 이때 API는 여전히 생성 계층으로 기능하지만, 에이전트가 제작 상태를 관리합니다. 이를 통해 실수로 인한 중복 요청을 줄이고, 늦게 이루어진 프롬프트 편집으로 인해 기준 애셋 세트가 무의식적으로 변경되는 것을 방지할 수 있습니다.

요청 완료 수가 아닌, 승인된 초당 비용을 측정하세요. Seedance 2.5 대 Veo 3.1 비교를 활용해 정체성 안정성, 사용 가능한 엔딩, 검토 시간, 재실행 횟수 측면에서 Veo 3.1을 다른 경로와 비교하세요. 목표는 모든 촬영을 하나의 모델로 강제로 처리하는 것이 아니라, 피할 수 있는 수정 사항을 최소화하면서 일관된 시퀀스를 제공하는 데 있습니다.

결론

신뢰할 수 있는 Veo 참조 이미지 API 통합은 올바른 제어 모드 선택으로 시작합니다. 최대 세 개의 일관된 애셋 참조를 준비하고, 명확한 동작 및 보존 프롬프트를 작성한 후, 유효한 Veo 3.1 요청을 제출하세요. 장시간 실행 작업을 지속적으로 관리하고, 보관 기한 만료 전에 다운로드하며, 고정된 평가 기준으로 전체 클립을 검토하세요. 일시적인 API 재시도는 창의적 재실행과 분리하여 관리하고, 정확한 시작점과 종료점이 유연한 애셋 가이던스보다 중요할 경우 첫 프레임과 마지막 프레임 간 보간 방식으로 전환하세요. 프로젝트에 촬영 계획 수립, 공유 참조, 모델 라우팅, 승인 절차, API 호출 주변의 선택적 재실행이 필요할 경우, 워크플로우를 Seedance Agent → 로 시작하세요