Gemini Omni 1.2 Flash API로 영상 생성부터 다운로드·검증까지

완전한 Python 예제로 Gemini Omni 1.2 Flash 영상을 생성하고 파일 대기, 다운로드 복구, 미디어 검증을 수행합니다. 참조·편집·연장 제한도 확인하세요.

주황색 프레임을 중심으로 필름을 정렬하는 수동 필름 접합기. 영상 편집과 완성된 결과 전달을 표현한 평면 그림.

Google Interactions API에서 gemini-omni-1.2-flash를 호출하고 영상 출력을 요청한 뒤, 상호작용 완료·영상 파일 준비·다운로드한 미디어의 검수 통과를 각각 확인하세요. API 응답이 완료됐다고 해서 재생 가능한 영상을 이미 저장한 것은 아닙니다. 파일이 처리 중인데 다시 생성하면 불필요한 작업과 비용이 생길 수 있습니다.

이 글은 작은 텍스트 기반 영상 요청으로 전체 과정을 설명합니다. 다운로드 가능한 Python 실행 프로그램, 복구 명령, 로컬 미디어 검사기를 제공하고, 참조 자료·편집·연장을 사용할 때 바뀌는 설정을 다룹니다. 공식 문서 확인일은 2026년 11월 15일입니다. 링크한 Google 공식 문서는 영문입니다.

이 가이드는 Ofox가 발행합니다. 근거는 합성 응답과 실제 Google SDK로 수행한 헬퍼 및 실행 프로그램 오프라인 테스트 24개, 그리고 직접 FFmpeg로 만든 파일을 이용한 로컬 미디어 검사 10개입니다. 실제 Omni 생성, 모델 품질 비교, 지연 시간 측정, 청구액 검증은 하지 않았습니다. 제공 프로그램은 오프라인으로 검증한 연동 템플릿이지, 실제 Google 호출이 처음부터 끝까지 성공했다는 증거가 아닙니다. 합성 테스트 영상을 Omni 결과물로 제시하지도 않습니다.

먼저 모델과 API 경로를 선택하기

현재 Google 모델 사양은 gemini-omni-1.2-flash의 입력으로 텍스트·이미지·영상을, 출력으로 영상과 네이티브 오디오를 명시합니다. 텍스트 전용 Gemini 모델이나 이전 Veo 요청 형식으로 바꾸지 마세요. 기존 Veo 3.1 API 가이드 (영문)는 다른 모델의 연동 방식입니다.

모델 접근 권한과 필요한 결제 또는 이용 한도 설정을 갖춘 Google 프로젝트가 필요합니다. 키는 Google API 키 문서에 따라 발급·관리하세요. 소비자용 앱 구독만으로 API 프로젝트에서 호출할 수 있다고 판단하면 안 됩니다. 평소 사용하는 비밀 정보 관리 방식으로 GEMINI_API_KEY를 설정하고, 프롬프트나 공개 오류 로그에는 넣지 마세요.

이 글의 엔드포인트는 https://generativelanguage.googleapis.com/v1beta/interactions입니다. Ofox에는 별도의 영상 작업 API, 작업 생성, 상태 조회, 인증 문서가 있습니다. Ofox가 지원하는 영상 모델을 쓸 때 유용하지만 아래 Google 요청과 서로 바꿔 쓸 수는 없습니다. 이 글은 Ofox의 Omni 지원을 확인한 자료가 아니며 Ofox Omni 가격도 제시하지 않습니다.

Google 영문 문서에 나온 Gemini Omni 1.2 Flash 영상 기능과 1.1 전환 일정.

Google 영문 공식 문서의 실제 화면이며 계정 정보는 잘라냈습니다. 제품 설명을 보여주는 화면으로, 생성 결과나 Ofox 연동 실험 화면이 아닙니다.

Google이 공지한 gemini-omni-1.1-flash의 1.2 전환일은 2026년 12월 3일입니다. 이 글의 검증 시점에는 아직 미래입니다. 예제는 향후 별칭 변경에 기대지 않고 1.2 ID를 직접 지정합니다. 모델 문서에서 gemini-omni-flash-preview는 종료된 버전으로 표시됩니다.

예제 패키지를 설치하고 오프라인 테스트하기

Omni 영상 예제 패키지를 다운로드하고 압축을 푼 뒤 omni-video-kit 디렉터리로 이동하세요. 실제 호출용 프로그램, 결과 처리 헬퍼, 미디어 검사기, 테스트 모듈 두 개, 영문 README가 들어 있습니다. 흩어진 코드 조각으로 핵심 프로그램을 조립할 필요가 없습니다.

Python 3.11 이상과 격리된 환경을 사용합니다.

python -m venv .venv
source .venv/bin/activate
python -m pip install 'google-genai==3.3.0' httpx
python -m unittest test_video_result.py test_runner_offline.py -v

Windows PowerShell에서는 .venv\Scripts\Activate.ps1로 활성화합니다. 패키지 설치는 레지스트리에 접속합니다. 테스트 자체는 합성 데이터와 모의 서비스 호출을 사용하고, 실행 프로그램 테스트는 네트워크 연결도 차단하므로 Google 키가 필요 없습니다. 예상 결과는 테스트 24개 통과입니다.

헬퍼 테스트는 완료·미완료 상호작용, URI 검증, 파일 처리 상태, 횟수가 제한된 폴링을 확인합니다. 실행 프로그램 테스트는 설치된 SDK의 실제 요청 직렬화, GET 복구, 타임아웃과 서비스 오류, 부분 다운로드 보존, 동시에 생성된 출력 파일의 덮어쓰기 방지를 확인합니다. 특히 모의 503이나 타임아웃에서 생성 POST가 한 번만 발생하고 자동 재전송되지 않는지 검사합니다.

미디어 검사기는 별도 단계입니다. 신뢰할 수 있는 패키지 관리자나 공식 배포처에서 ffmpeg와 ffprobe를 설치하고 실제 호출 전에 두 명령이 실행되는지 확인하세요. 검사에는 생성 패턴과 음, 무음 트랙, 손상 파일, 의도적으로 서로 다른 트랙 길이를 사용했습니다. 이 테스트가 확인하는 것은 검사기이며 모델의 출력 품질이 아닙니다.

설정을 명시해 짧은 영상 하나 생성하기

처음에는 대상 하나, 움직임 하나, 고정 카메라로 시작하면 지시를 따르는지 판단하기 쉽습니다. 프로그램의 영문 프롬프트는 다음 뜻입니다.

초록색 잎 한 장이 고요한 연못 위를 왼쪽에서 오른쪽으로 떠간다. 고정된 와이드 샷, 부드러운 햇빛. 조용하고 자연스러운 물소리만 있고 말소리·음악·텍스트는 없다.

목표는 자연스러운 물소리가 포함된 3초, 가로형, 720p 영상입니다. 요청 목표이지 실제로 관찰한 생성 결과는 아닙니다. 완전한 실행 프로그램 안의 생성 호출은 다음과 같습니다.

interaction = client.interactions.create(
    model="gemini-omni-1.2-flash",
    input=(
        "A single green leaf drifts across a still pond from left to right. "
        "Fixed wide shot, soft daylight. Quiet natural water sounds, "
        "no speech, no music, no text."
    ),
    response_format={
        "type": "video",
        "delivery": "uri",
        "duration": "3s",
        "resolution": "720p",
        "aspect_ratio": "16:9"
    },
    store=True,
    timeout=180,
    automatic_continuation=False
)

이 발췌문은 run_live.py의 클라이언트와 복구 처리를 전제로 하므로 실행할 때는 전체 스크립트를 쓰세요. HTTP 타임아웃을 설정하고 retry_options.attempts=1로 SDK 자동 재시도를 끕니다. 요청을 보내기 전에 로컬 복구 기록도 예약합니다. 서버의 처리 결과를 모르는 상태에서 중복 생성을 줄이는 장치이며, 모든 인프라에서 정확히 한 번 실행됨을 보장하지는 않습니다.

자신의 Google 프로젝트 키를 설정한 다음 아래 명령을 실행하면 실제 요청이 발생하고 이용 한도나 비용이 소모될 수 있습니다.

python run_live.py --create --out leaf.mp4

store=True는 나중에 결과를 조회하고 후속 편집 대화에서 사용하기 위해 의도적으로 선택했습니다. Omni 공식 가이드에는 저장을 끄는 동기식 일회성 생성도 있지만, 그 경우 previous_interaction_id로 후속 편집을 할 수 없습니다. 복구를 전제로 한 예제에 그 설정을 무조건 적용하지 마세요.

URI 전달 방식이면 큰 영상을 JSON 응답 안에 담지 않아도 됩니다. 그렇다고 모든 생성을 백그라운드 작업으로 해야 하는 것은 아닙니다. 생성 모드, 상호작용 완료, 파일 준비는 각각 다른 문제입니다. 다음 절은 대기할 때마다 새로 생성하는 대신 프로그램이 처리하는 상태를 구분합니다.

상호작용 완료, 파일 준비, 다운로드 복구 구분하기

응답이 도착하면 프로그램은 leaf.mp4.interaction.json을 저장하고 상호작용 ID와 상태를 출력합니다. 이 기록에는 콘텐츠나 미디어 데이터가 포함될 수 있으므로 비공개로 보관하세요. 기록이 생겼다고 영상이 완료됐다는 뜻은 아닙니다.

단계프로그램 확인 사항보관할 내용 또는 다음 행동
생성은 제출했지만 결과 불명ID를 받지 못해도 대기 기록이 남음다시 생성하기 전에 계정·서비스 기록 확인
상호작용 응답 도착completed, 보고된 오류 없음, 영상 출력 존재ID와 응답 보관
URI로 영상 전달예상한 Google 파일 리소스에 해당해당 파일 폴링, URI를 새 작업 ID로 해석하지 않기
파일 처리PROCESSING, ACTIVE, FAILED처리 중 대기, ACTIVE일 때 다운로드, 실패·미지 상태에서 중단
다운로드 전송새 .part 파일에 바이트 기록실패 시 부분 파일 보존, 완성본으로 취급하지 않기
로컬 저장 확정비어 있지 않고 기존 출력을 대체하지 않음사용 전 미디어 및 콘텐츠 검수

헬퍼는 문서에 해당하는 HTTPS Google 파일 출처와 경로 형태만 허용합니다. /v1beta/files/...:download?alt=media 같은 URI를 Files API가 요구하는 files/... 이름으로 정규화합니다. 인증 정보가 들어 있거나 다른 출처를 가리키는 URL은 거부하며, 응답의 임의 링크를 가져오지 않습니다. 인증은 SDK가 처리하므로 복사한 다운로드 URL에 키를 넣으면 안 됩니다.

예제는 파일 준비 상태를 최대 60회, 5초 간격으로 확인합니다. HTTP 타임아웃은 180초입니다. 이는 폴링 횟수와 개별 요청 제한이지, 전체 작업이 5분 안에 끝난다는 보장이나 생성 지연 시간 약속이 아닙니다. 전송 오류는 그대로 전달하고 새 생성을 시작하지 않습니다. 현재 프로그램은 SDK의 첫 번째 영상 출력을 선택하므로 여러 출력이 필요하면 수정하고 테스트하세요.

기존 상호작용을 복구하려면 실제 반환된 ID를 사용합니다.

python run_live.py --resume YOUR_INTERACTION_ID --out recovered-leaf.mp4

생성 POST가 아니라 조회 GET입니다. 미완료 상호작용을 계속 자동 폴링하지는 않습니다. 저장된 상태를 확인하고 적절한 시점에 다시 조회하세요. 첫 요청이 ID를 받기 전에 타임아웃되면 이 스크립트로 알 수 없는 서버 작업을 찾아낼 수 없습니다. 대기 기록은 같은 출력 이름의 재생성을 막습니다. 새 파일명으로 보호 장치를 우회하지 말고 원래 요청을 조사하세요.

기존 출력이나 .part가 있으면 제출 전에 멈춥니다. 다운로드 실패 시 부분 파일과 복구 기록이 남을 수 있습니다. 존재를 아는 기존 상호작용을 복구할 때는 위와 같이 새로운 출력 이름을 사용합니다. 최종 저장은 같은 디렉터리에 하드 링크를 만든 후 .part를 지워서 동시에 만들어진 출력을 덮어쓰지 않습니다. 파일시스템이 이를 지원하지 않으면 완성된 부분 파일을 보존하고 로컬 저장 문제를 해결하세요. 파일시스템 오류 때문에 다시 생성할 필요는 없습니다.

파일을 검사한 뒤 영상을 보고 소리 듣기

파일 저장이 완료됐다는 메시지가 나오면 로컬 미디어를 검사합니다.

python verify_video.py leaf.mp4 --seconds 3 --require-audio

검사기는 비어 있지 않은 파일, 유효한 크기의 일반 영상 스트림, 양수 길이, 요청한 경우 오디오 스트림을 요구합니다. 컨테이너와 각 일반 영상 트랙 길이를 이 예제에서 선택한 0.25초 허용 오차로 확인한 뒤 FFmpeg로 영상과 오디오를 디코딩합니다. 트랙 길이 메타데이터가 없으면 컨테이너 길이를 대신 쓰지 않고 엄격 검사에서 실패시킵니다.

3초짜리 컨테이너 안에 영상은 1초, 오디오는 3초만 있을 수 있기 때문에 트랙 확인이 중요합니다. 컨테이너만 검사하면 짧은 화면을 놓칩니다. 오디오 스트림이 있어도 전부 무음일 수 있습니다. 검사기가 확인하는 것은 스트림 존재이지 들리는 소리, 동기화, 예술적 품질이 아닙니다.

잎 예제는 별도로 다음을 보고 들어 검수하세요.

검수 질문확인할 내용실패했을 때
대상이 맞는가?연못 위 초록 잎 한 장이며 무관한 대상이 없는가대상 조건 하나를 바꾸고 새 시도 기록
움직임이 맞는가?잎은 왼쪽에서 오른쪽, 카메라는 고정인가대상 움직임과 카메라 움직임을 구분해 지정
영상이 이어지는가?예상 밖 컷, 깜빡임, 갑작스러운 종료가 없는가편집·재생성 전에 시작·중간·끝 비교
소리가 쓸 만한가?물소리가 들리며 불필요한 말·음악은 없는가직접 듣기. 오디오 트랙 존재만으로 통과시키지 않기
목적에 맞는가?구도, 대상 식별, 불필요한 텍스트 부재가 적절한가메타데이터 외에 실제 사용 화면에서도 확인

실제 잎 영상을 생성하거나 점수를 매기지는 않았습니다. 허가된 실제 실행에서 사용할 검수 기준입니다. 요청 프롬프트, 정확한 설정, 실제 결과를 함께 보관하면 다음 시도와 비교할 수 있습니다. 디코딩 성공은 기술적 단계일 뿐 모델이 창작 요구를 따랐다는 근거는 아닙니다.

참조·편집·연장 설정을 작업별로 선택하기

모델 사양과 작업별 Omni 제한은 모드에 따라 다릅니다. 새 영상의 최대 길이를 모든 작업에 적용하지 마세요.

작업문서상 제한실제 적용
새 영상정수 초 기준 3~15초, 기본 10초재현할 예제에서는 길이를 명시
첫 프레임과 마지막 프레임3~10초두 끝 프레임으로 15초 보간은 불가
이미지 참조각 길이에서 최대 6장이미지마다 역할을 명확히 설명
새 생성의 영상 참조출력 310초는 최대 3개, 1115초는 1개; 각 참조는 최대 3초참조 개수와 출력 길이를 따로 계산
편집 입력 영상최대 15초부적절한 입력은 먼저 자르거나 분할
연장매회 3~10초 추가, 총 30초까지; 마지막 10초를 문맥으로 사용총길이를 기록하고 중요한 이전 정보를 다시 설명
해상도360p, 720p, 1080p, 4k; 기본 720pGoogle은 1080p·4K를 업스케일로 명시하므로 네이티브 촬영이라고 쓰지 않기

이미지에서 무엇을 유지할지, 영상이 새 장면에 어떤 영향을 줄지 자연어로 설명하세요. 영상 참조의 오디오는 무시되며, 영상 참조는 편집·연장이 아니라 새 생성용입니다. 네이티브 오디오 출력이 업로드 오디오 입력이나 음성 참조 지원을 의미하지는 않습니다. 목소리 편집도 지원하지 않습니다.

Google은 여러 영상 사이를 참조하거나 추론하는 기능도 지원하지 않으며, 다중 영상 프롬프트가 성능 저하나 예상 밖 결과를 낼 수 있다고 설명합니다. 참조 개수 제한을 충족한다고 신뢰할 수 있는 영상 간 추론이 보장되지는 않습니다.

첫 이미지 참조 시도에서는 오래된 제어 태그 대신 명확한 역할을 지정하세요.

Create a 5-second landscape shot.
Use the attached image as the appearance reference for the green leaf.
Keep its shape and color consistent.
The leaf drifts from left to right across still water.
Keep the camera fixed, with soft daylight and gentle water sounds.
Do not add speech, music, captions or extra leaves.

이 템플릿은 5초 가로 영상, 첨부 이미지 속 잎의 모양과 색 유지, 오른쪽 이동, 고정 카메라, 햇빛·물소리, 말·음악·자막·추가 잎 제외를 요청합니다. 다만 문서의 미디어 입력 형식에 맞춰 실제 이미지를 첨부해야 합니다. 텍스트에서 이미지를 언급한다고 파일이 업로드되지는 않습니다. 소재 사용 권리와 해당 계정의 작업 지원도 확인하세요. Google은 video_config.task를 강제하기 전에 명확한 자연어 역할을 먼저 시도하라고 권장합니다. 해당 설정은 허용되는 미디어 조합을 더 제한할 수 있습니다.

다음은 이미 생성해서 저장한 영상을 편집하는 독립 예제입니다. edit_saved_video.py로 저장하고 실제 이전 ID를 OMNI_PREVIOUS_INTERACTION_ID에서 읽습니다. 별도의 비용이 발생할 수 있는 작업이며, 오프라인 테스트나 다운로드 복구 명령이 아닙니다.

import os
from pathlib import Path
from google import genai

client = genai.Client(
    api_key=os.environ["GEMINI_API_KEY"],
    http_options={"timeout": 180000, "retry_options": {"attempts": 1}}
)
try:
    edit = client.interactions.create(
        model="gemini-omni-1.2-flash",
        previous_interaction_id=os.environ["OMNI_PREVIOUS_INTERACTION_ID"],
        input="Make the daylight warmer. Keep the leaf, its motion and the camera framing unchanged.",
        response_format={"type": "video", "delivery": "uri"},
        store=True,
        timeout=180,
        automatic_continuation=False
    )
    Path("edit-interaction.json").write_text(edit.model_dump_json(indent=2))
    print(edit.id, edit.status)
finally:
    client.close()

같은 활성 환경과 패키지 디렉터리에서 GEMINI_API_KEY를 유지하고 편집할 저장된 생성 ID를 설정합니다. macOS 또는 Linux에서는 다음과 같습니다.

export OMNI_PREVIOUS_INTERACTION_ID='YOUR_STORED_GENERATION_ID'
python edit_saved_video.py

Windows PowerShell에서는 $env:OMNI_PREVIOUS_INTERACTION_ID = 'YOUR_STORED_GENERATION_ID'를 설정한 뒤 python edit_saved_video.py를 실행하세요. 자리표시자는 실제 생성 상호작용 ID로 바꿔야 하며 Files API 리소스 이름을 넣으면 안 됩니다. edit-interaction.json은 비공개로 보관하고 재실행 전에 각 시도 기록을 남기세요.

응답이 성공적으로 반환되면 새 ID를 run_live.py --resume에 넣고 새로운 파일명으로 가져온 뒤 미디어·화면 검수를 반복합니다. 최초 생성용 전체 프로그램과 달리 이 짧은 편집 예제는 POST 전에 대기 기록을 예약하지 않습니다. ID 없이 타임아웃되면 다시 실행하기 전에 계정 기록을 조사하고, 편집이 없었다고 단정하지 마세요. 이 편집 호출과 실제 연장은 글을 위해 실행하지 않았습니다.

업로드 영상의 편집·연장은 EEA, 스위스, 영국에서 지역 제한이 있으며 모델이 생성한 영상의 처리와 다릅니다. 연장은 끝에만 추가할 수 있고 중간 삽입이나 앞쪽 추가는 불가합니다. 이미 말소리가 있는 업로드 영상에 대사를 추가하는 작업도 제한됩니다. 이전에 생성한 영상의 여러 턴 음성 연장은 별도로 문서화돼 있습니다. “영상 편집 지원”을 모든 작업의 허용으로 해석하지 말고 구체적인 작업 제한을 확인하세요.

실패한 단계에서 원인 찾기

정확한 모델, 엔드포인트, SDK 버전, 비밀 정보를 제거한 오류 본문, 존재하는 상호작용 ID나 파일 식별자를 모읍니다. 기존 Gemini 4 API 오류 가이드는 인증, 접근 권한, 요청 형식, 할당량을 구분하는 방법을 설명합니다. 모델 예제는 Argon이므로 여기서는 Omni ID와 영상 요청 형식을 유지하세요.

증상확인할 단계다음 행동
HTTP 200인데 파서에서 영상이 없음응답 형식 또는 미완료 상호작용SDK의 output_video는 편의 속성이고 REST 영상 콘텐츠는 steps 안에 있음
첫·마지막 프레임 요청에서 길이 오류작업별 파라미터 제한같은 요청을 반복하지 말고 해당 모드의 길이로 변경
생성 설정이 거부됨미지원 파라미터시스템 지시, temperature, top_p, 종료 시퀀스, 별도 부정 프롬프트 필드를 제거하고 일반 프롬프트에 조건 작성
상호작용 완료, 파일은 처리 중파일 준비 상태새로 생성하지 말고 같은 리소스 확인
파일이 FAILED 또는 알 수 없는 상태서비스 처리 또는 스키마 변경증거를 보존하고 중단. 처리 중이 아니라는 이유만으로 성공 처리하지 않기
클라이언트 타임아웃, 생성 결과 불명전송과 서버 실행의 구분대기 기록을 보존하고 다음 POST 전에 조사
다운로드 성공, 검사 실패바이트·트랙·로컬 도구파일과 검사 출력을 살핀 뒤 재조회·재생성 결정
업로드 영상 작업 불가지역·입력 유형·정책인증 정보를 무작정 바꾸지 말고 계정과 작업 제한 확인

안전 필터가 거부하면 서비스가 허용하는 범위 안에서 요청을 수정하세요. 차단된 프롬프트를 그대로 재전송하는 방식은 적절하지 않습니다. 임시 URL이나 인증 정보가 있는 URL을 공개 예제로 쓰지 마세요. Ofox의 별도 계약을 쓰는 애플리케이션은 영상 오류 코드와 일반 재시도 가이드를 참고하되, Google 오류 계약을 대체하는 자료로 쓰면 안 됩니다.

사용을 확대하기 전에 작업 기록 남기기

실제 시도마다 모델 ID, 프롬프트 버전, 참조 자료, 길이, 해상도, 화면비, 저장 선택, 상호작용 ID, 파일 리소스, 로컬 출력 해시와 검수 결과를 보관하세요. 공유 보고서에서 비밀 정보와 비공개 콘텐츠는 제외합니다. 기존 작업을 조회한 GET과 새 작업을 만든 POST를 구분해야 디버깅과 비용 분석이 정확해집니다.

지출을 예상하기 전에 정확한 모드와 해상도에 맞는 Google의 현재 Omni 요금을 확인하세요. 이 글에는 실측 생성 청구액이나 Ofox 요금이 없습니다. 사용량을 아는 실패 시도·편집·연장을 각각 기록하고, 알 수 없는 사용량은 0으로 대체하지 마세요. 짧은 초안도 이후 여러 번 유료 수정하면 총비용이 커질 수 있습니다. 단일 요청보다 최종 검수를 통과하기까지의 전체 작업을 비교하세요.

먼저 작은 예제 하나를 검수 통과시킨 뒤 이미지 참조, 다른 화면비, 저장 영상 편집, 연장을 하나씩 더하세요. 비교를 위해 이전의 정상 설정을 남겨두세요. 실제 계정에서 필요한 영상을 생성·조회·검증할 수 있을 때 사용 규모를 늘립니다. 최종 산출물은 사용할 수 있는 영상과 검수 기록이지, 생성이 끝났다는 모델 메시지만은 아닙니다.