Gemini Omni 1.1 Flash API 사용법

Gemini Omni 1.1 Flash 동영상 생성 API 사용 가이드

Gemini Omni 1.1 Flash는 텍스트 모델에서 사용하는 generateContent 엔드포인트가 아니라 Google의 Interactions API를 통해 gemini-omni-1.1-flash 모델 ID로 호출합니다. Gemini 텍스트 스니펫에서 모델 이름만 바꾸면 404 오류가 발생합니다.

지금 Apidog를 사용해 보세요

이 가이드에서는 빈 터미널에서 동영상 생성 요청을 테스트하는 방법을 다룹니다. API 키 발급, curl 및 Python을 사용한 첫 호출, 지원 및 미지원 매개변수, 대용량 응답 처리, 반복 가능한 API 테스트 저장까지 단계별로 살펴봅니다.

이 모델은 2026년 8월 27일 GA(정식 출시)되었습니다. 함께 출시된 기능은 Gemini Omni 1.1 Flash의 새로운 기능에서 확인할 수 있습니다.

시작하기 전에 필요한 것

• AI Studio에 로그인할 Google 계정
• Google AI Studio에서 발급받은 Gemini API 키
• 활성화된 결제 계정 Omni에는 텍스트 모델의 무료 이용과 달리 무료 등급이 없습니다. 첫 요청부터 비용이 발생합니다.
• HTTP 요청을 보낼 방법: curl, Python SDK 또는 API 클라이언트

API 키는 소스 코드에 직접 입력하지 말고 환경 변수로 저장하세요.

export GEMINI_API_KEY="your_key_here"

공식 SDK는 이 환경 변수를 자동으로 읽으므로 비밀 정보가 저장소에 노출되지 않습니다.

첫 번째 동영상 생성 호출

엔드포인트는 /v1beta/interactions이며, POST 요청을 보냅니다.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-1.1-flash",
    "input": "A marble rolling fast on a chain reaction style track, continuous smooth shot."
  }'

최소 요청에는 model과 input 두 필드만 필요합니다. 응답은 생성된 동영상을 output_video.data에 base64 형식으로 담아 반환합니다.

Python에서는 먼저 SDK를 설치합니다.

pip install google-genai

그다음 다음 코드를 실행하세요.

import base64
from google import genai

client = genai.Client()  # reads GEMINI_API_KEY from the environment

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A marble rolling fast on a chain reaction style track, continuous smooth shot.",
)

with open("marble.mp4", "wb") as f:
    f.write(base64.b64decode(interaction.output_video.data))

JavaScript에서는 @google/genai를 사용해 동일한 형식으로 호출할 수 있습니다.

import { GoogleGenAI } from '@google/genai';
import * as fs from 'fs';

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: 'gemini-omni-1.1-flash',
  input: 'A marble rolling fast on a chain reaction style track, continuous smooth shot.',
});

if (interaction.output_video?.data) {
  fs.writeFileSync('marble.mp4', Buffer.from(interaction.output_video.data, 'base64'));
}

동영상 생성에는 시간이 걸립니다. 지연 시간은 길이, 해상도, 현재 API 부하에 따라 달라지므로, 충분히 긴 클라이언트 시간 초과를 설정하세요.

해상도 및 종횡비 제어

출력 형식은 response_format에서 지정합니다.

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A drone shot of a mountain landscape at sunrise.",
    response_format={
        "type": "video",
        "aspect_ratio": "16:9",
        "resolution": "1080p",
    },
)

지원되는 값은 다음과 같습니다.

필드	값	기본값
type	video	video
aspect_ratio	16:9, 9:16	16:9
resolution	360p, 720p, 1080p, 4k	720p
delivery	인라인 base64, uri	인라인

개발 초기에는 360p를 사용하세요. 720p보다 최대 60% 빠르게 생성되고 비용은 1/3에 불과합니다. 따라서 테스트 프롬프트 15회를 예전 720p 테스트 5회와 비슷한 비용으로 실행할 수 있습니다.

보관할 영상은 더 높은 해상도로 다시 렌더링하세요. 1080p와 4k는 생성된 프레임을 업스케일한 결과이며, 기본 렌더링이 아닙니다. 자세한 티어별 초당 비용은 Gemini Omni 1.1 Flash 가격 분석을 참고하세요.

지원되지 않는 매개변수

다음 매개변수는 지원되지 않습니다.

• 시스템 지침
• temperature
• top_p
• 정지 시퀀스
• 부정 프롬프트 필드

장면에서 제외할 내용이 있다면 프롬프트에 직접 작성하세요. 문서에는 다음과 같은 예시가 있습니다.

움직임에 대한 가이드로만 그림을 사용하고, 최종 동영상에는 그림을 표시하지 마십시오.

이미지 입력, 키프레임 및 참조 동영상

미디어를 포함하려면 문자열 대신 목록을 전달하세요. 이미지를 동영상으로 변환하는 예시는 다음과 같습니다.

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "image", "data": base64_image, "mime_type": "image/jpeg"},
        {"type": "text", "text": "turn this into realistic footage, using the drawing only as a guide for movement, do not show the drawing in the final video"},
    ],
)

이미지 두 개를 전달하면 첫 번째 이미지는 시작 프레임, 두 번째 이미지는 마지막 프레임이 됩니다. 모델은 두 프레임 사이의 움직임을 생성합니다.

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input=[
        {"type": "image", "data": first_frame_b64, "mime_type": "image/jpeg"},
        {"type": "image", "data": last_frame_b64, "mime_type": "image/jpeg"},
        {"type": "text", "text": "A smooth cinematic transition from a lush green forest at sunrise to a snowy forest under a starry night sky."},
    ],
)

참조 동영상도 Files API를 통해 사용할 수 있습니다. 각 3초 길이의 클립 3개로 제한되며, 클립의 오디오는 무시됩니다. 모델은 움직임과 형태를 분석하는 데 동영상을 사용합니다.

다중 턴 편집

Omni는 일반적인 텍스트-투-비디오 엔드포인트와 달리 이전 상호작용을 기반으로 대화식 편집을 지원합니다. 첫 생성 후 previous_interaction_id에 이전 상호작용 ID를 전달하세요.

res1 = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A woman playing violin outdoors.",
)

res2 = client.interactions.create(
    model="gemini-omni-1.1-flash",
    previous_interaction_id=res1.id,
    input="Make the violin invisible.",
)

동영상을 다시 업로드하거나 장면을 다시 설명할 필요가 없습니다. 같은 메커니즘으로 장면을 확장할 수도 있습니다. 자세한 내용은 40초 장면 확장 가이드를 참고하세요.

4MB를 초과하는 동영상 처리

4MB보다 큰 파일은 인라인 base64 대신 URI로 반환됩니다. 파일을 다운로드하기 전에 처리가 완료될 때까지 기다려야 합니다.

이는 1080p에서 자주 발생하는 문제입니다. 핸들러가 output_video.data만 읽으면 값이 없어 자동으로 실패를 보고할 수 있습니다. output_video.uri를 사용하고 Files API를 폴링하세요.

import time
from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-omni-1.1-flash",
    input="A beautiful sunset.",
    response_format={"type": "video", "delivery": "uri"},
)

video_output = interaction.output_video
file_name = video_output.uri.split("/")[-1]

while True:
    f_info = client.files.get(name=f"files/{file_name}")
    if f_info.state.name == "ACTIVE":
        break
    if f_info.state.name == "FAILED":
        raise RuntimeError("Generation failed.")
    time.sleep(5)

video_bytes = client.files.download(file=video_output.uri)

with open("output.mp4", "wb") as f:
    f.write(video_bytes)

응답 핸들러는 처음부터 data와 uri 두 가지 응답 형태를 모두 처리하도록 구현하세요.

Apidog에서 요청 테스트하기

API 호출이 작동한 뒤에는 재현 가능한 테스트 환경을 구축해야 합니다. 동영상 생성 엔드포인트는 비용이 높고 느리며 비결정적이므로, 쉘 히스토리의 임시 curl 명령만으로는 동작 변경을 추적하기 어렵습니다.

Apidog에 다음과 같이 요청을 저장하세요.

• 프로젝트 및 환경 생성 GEMINI_API_KEY와 MODEL_ID를 환경 변수로 저장합니다. 키가 요청 본문이나 저장된 설정에 직접 들어가지 않도록 하세요.
• 요청 추가 https://generativelanguage.googleapis.com/v1beta/interactions로 POST 요청을 만들고 model과 input을 포함한 JSON 본문을 사용합니다. 모델은 {{MODEL_ID}} 변수로 참조하세요.
• 시간 초과 연장 동영상 생성은 텍스트 완성보다 오래 걸리므로 기본 클라이언트 시간 초과를 늘립니다.
• 어설션 추가 상태 코드, output_video 존재 여부, 해상도에 따른 응답 형태를 검증하세요. 이를 통해 인라인 응답과 URI 응답의 전환을 감지할 수 있습니다.
• 작업 유형별 요청 복제 텍스트-투-비디오, 이미지-투-비디오, 장면 확장 각각에 대해 저장된 요청을 만드세요. Google이 Omni 1.2를 출시하면 세 요청을 실행해 변경 사항을 빠르게 확인할 수 있습니다.

Apidog는 동영상을 생성하는 AI 프레임워크가 아닙니다. 요청을 만들고 전송하며, 설정한 기준에 따라 응답을 검증하고 보관하는 테스트 도구입니다. 비용을 늘리기 전에 이러한 제어 시스템을 구축하려면 Apidog 다운로드를 이용하세요.

일반적인 오류와 해결 방법

• 엔드포인트에서 404 오류 /v1beta/models/gemini-omni-1.1-flash:generateContent를 호출하고 있을 가능성이 큽니다. Omni는 요청 본문에 모델을 포함한 /v1beta/interactions를 사용합니다.
• output_video.data가 비어 있음 동영상이 4MB를 초과해 URI로 반환된 경우입니다. output_video.uri를 읽고 Files API로 다운로드하세요.
• 모델을 찾을 수 없음 구성에 gemini-omni-flash-preview가 남아 있는지 확인하세요. 해당 엔드포인트는 2026년 9월 30일에 사용 중지됩니다.
• 업로드한 동영상 편집 실패 EEA, 스위스, 영국에서는 업로드한 동영상 편집을 사용할 수 없습니다. 모델이 생성한 동영상은 해당 지역에서도 작동합니다.
• 확장 요청 거부 입력 동영상은 최대 10초로 제한됩니다. 확장은 끝부분에만 추가할 수 있으며, 업로드한 동영상을 확장할 때는 대화를 추가할 수 없습니다.

FAQ

Gemini Omni는 어떤 엔드포인트를 사용하나요?

요청 본문에 gemini-omni-1.1-flash를 포함하고 다음 엔드포인트로 POST 요청을 보냅니다.

https://generativelanguage.googleapis.com/v1beta/interactions

Gemini Omni API에 무료 등급이 있나요?

아니요. 모든 생성에는 요금이 부과됩니다. 무료 AI Studio 사용 경로를 제공하는 것은 텍스트 모델입니다.

temperature 또는 부정 프롬프트를 설정할 수 있나요?

아니요. 시스템 지침, temperature, top_p, 정지 시퀀스, 부정 프롬프트는 지원되지 않습니다. 제외할 내용은 프롬프트 텍스트에 포함하세요.

세로 동영상은 어떻게 생성하나요?

response_format에서 aspect_ratio를 9:16으로 설정하세요.

생성된 동영상에 워터마크가 있나요?

예. 모든 출력물에는 시청자에게는 보이지 않지만 프로그래밍 방식으로 감지할 수 있는 SynthID가 포함됩니다.

Veo API와 어떻게 다른가요?

엔드포인트, 가격, 강점이 다릅니다. Omni 1.1 Flash와 Veo 3.1 비교에서 장단점을 확인하고, 통합 세부 사항은 Veo 3.1 API 가이드를 참고하세요.

마무리

전체 통합에는 다음이 필요합니다.

1. model과 input 두 필드를 사용한 Interactions API 호출
2. 인라인 base64와 URI 두 가지 전달 형태를 처리하는 응답 핸들러

먼저 360p 호출을 구현하고, Apidog에 어설션과 함께 저장하세요. 시스템이 안정된 뒤 해상도를 높이는 것이 좋습니다. 매개변수 목록은 변경될 수 있으므로 최신 내용은 공식 Omni 문서를 확인하세요.