Gemini Omni 1.1 Flash API 사용법

Gemini Omni 1.1 Flash는 텍스트 모델에 사용하는 generateContent 엔드포인트가 아니라 Google의 Interactions API를 통해 gemini-omni-1.1-flash 모델 ID로 호출합니다. 이것이 사람들이 처음 혼동하는 부분입니다. Gemini 텍스트 스니펫을 복사하여 모델 이름을 바꾸면 404 오류가 발생합니다.

이 가이드는 빈 터미널에서 테스트된 동영상 생성 요청까지 진행하는 방법을 안내합니다. 키를 얻고, curl 및 Python에서 첫 호출을 하고, 존재하는 매개변수(및 놀랍게도 존재하지 않는 목록)를 배우고, 큰 응답을 처리하며, 이 모든 것을 반복 가능한 테스트로 저장하는 방법을 알게 될 것입니다.

이 모델은 2026년 8월 27일에 GA(정식 출시)되었습니다. 함께 출시된 기능에 대해서는 Gemini Omni 1.1 Flash의 새로운 기능을 참조하십시오.

시작하기 전에 필요한 것

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

키를 소스 코드에 붙여넣지 말고 환경 변수로 저장하십시오.

export GEMINI_API_KEY="your_key_here"

공식 SDK는 해당 변수를 자체적으로 읽으므로, 비밀 정보가 저장소에 노출되지 않습니다.

첫 번째 동영상 생성 호출

엔드포인트는 /v1beta/interactions에 대한 POST 요청입니다. curl에서의 예시는 다음과 같습니다.

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."
  }'

모델과 입력, 두 가지 필드가 있습니다. 이것이 전체 최소 요청입니다. 응답은 생성된 동영상을 output_video.data에 base64로 담아 반환합니다.

Python에서는 pip install google-genai 명령어로 SDK를 설치한 후 다음을 따르십시오.

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번의 테스트 프롬프트 시도가 예전 5번 시도와 같은 비용이 듭니다. 보관할 영상은 더 높은 해상도로 다시 렌더링하십시오. 1080p와 4k는 생성된 프레임의 업스케일이며, 기본 렌더링이 아닙니다. 가격 분석은 각 티어별 초당 실제 비용을 보여줍니다.

존재하지 않는 매개변수

이 목록은 위 목록보다 더 중요합니다. 그렇지 않으면 오후 시간을 낭비하게 될 것입니다.

시스템 지침 없음
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를 일반 텍스트-투-비디오 엔드포인트와 차별화하는 점입니다. 한 번 생성한 다음, 이전 상호작용 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를 읽지만 아무것도 찾지 못하고 자동적으로 실패를 보고합니다.

명시적으로 URI 전달을 요청하고 폴링하십시오.

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)

응답 핸들러를 처음부터 두 가지 형태를 모두 수락하도록 작성하십시오. 해상도에 따라 어떤 형태를 받게 될지 달라집니다.

Apidog에서 요청 테스트

호출이 작동하면 문제가 달라집니다. 이제 중요 경로에 비싸고 느리며 비결정적인 엔드포인트가 있고, 이것이 동작을 변경할 때를 알아야 합니다. 쉘 히스토리의 즉석 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는 요청을 만들고, 전송하며, 설정한 표준에 따라 응답을 유지하는 곳입니다. 비용을 늘리기 전에 이러한 제어 시스템을 갖추고 싶다면 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 가이드에 해당 통합의 세부 정보가 있습니다.

전체 통합은 두 개의 필수 필드와 두 가지 전달 형태를 모두 처리하는 응답 핸들러로 구성됩니다. 먼저 360p 호출을 작동시킨 다음, 어설션과 함께 저장하고, 시스템이 안정되었다고 판단되면 해상도를 높이십시오. 매개변수 목록이 변경될 수 있으므로 공식 Omni 문서를 참조하십시오.