이제 Interactions API가 정식 버전으로 출시되었습니다. 이 API를 사용하여 모든 최신 기능과 모델에 액세스하는 것이 좋습니다.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

동영상 이해

동영상 생성에 대해 알아보려면 Gemini Omni Flash 가이드를 참고하세요.

Gemini 모델은 동영상을 처리할 수 있으므로 과거에는 도메인별 모델이 필요했던 많은 최첨단 개발자 사용 사례를 지원합니다. Gemini의 비전 기능에는 동영상에서 정보를 설명, 분할, 추출하고, 동영상 콘텐츠에 관한 질문에 답변하고, 동영상 내의 특정 타임스탬프를 참조하는 기능이 포함됩니다.

다음과 같은 방법으로 Gemini에 동영상을 입력으로 제공할 수 있습니다.

입력 방법	최대 크기	권장 사용 사례
File API	20GB (유료) / 2GB (무료)	대용량 파일 (100MB 이상), 긴 동영상 (10분 이상), 재사용 가능한 파일
Cloud Storage 등록	2GB (파일당, 스토리지 한도 없음)	대용량 파일 (100MB 이상), 긴 동영상 (10분 이상), 영구적이고 재사용 가능한 파일
인라인 데이터	100MB 미만	소용량 파일(100MB 미만), 짧은 길이(1분 미만), 일회성 입력
YouTube URL	해당 사항 없음	공개 YouTube 동영상

참고: File API는 대부분의 사용 사례, 특히 100MB보다 큰 파일의 경우 또는 여러 요청에서 파일을 재사용하려는 경우에 권장됩니다.

외부 URL 또는 Google Cloud에 저장된 파일 사용과 같은 다른 파일 입력 방법에 대해 알아보려면 파일 입력 방법 가이드를 참고하세요.

동영상 파일 업로드

다음 코드는 샘플 동영상을 다운로드하고, Files API를 사용하여 업로드하고, 처리가 완료될 때까지 기다린 후 업로드된 파일 참조를 사용하여 동영상을 요약합니다.

Python

from google import genai
import time

client = genai.Client()

myfile = client.files.upload(file="path/to/sample.mp4")

while not myfile.state or myfile.state.name != "ACTIVE":
    print("Processing video...")
    time.sleep(5)
    myfile = client.files.get(name=myfile.name)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {"type": "video", "uri": myfile.uri, "mime_type": myfile.mime_type},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
    ]
)

print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

async function main() {
  const myfile = await ai.files.upload({
    file: "path/to/sample.mp4",
    config: { mimeType: "video/mp4" },
  });

  let getFile = await ai.files.get({ name: myfile.name });
  while (getFile.state === 'PROCESSING') {
      getFile = await ai.files.get({ name: myfile.name });
      console.log(`current file status: ${getFile.state}`);
      console.log('File is still processing, retrying in 5 seconds');

      await new Promise((resolve) => {
          setTimeout(resolve, 5000);
      });
  }
  if (getFile.state === 'FAILED') {
      throw new Error('File processing failed.');
  }

  const interaction = await ai.interactions.create({
    model: "gemini-3.8-flash",
    input: [
      { type: "video", uri: myfile.uri, mime_type: myfile.mimeType },
      { type: "text", text: "Summarize this video. Then create a quiz with an answer key based on the information in this video." }
    ],
  });
  console.log(interaction.output_text);
}

await main();

자바

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

REST

VIDEO_PATH="path/to/sample.mp4"
MIME_TYPE=$(file -b --mime-type "${VIDEO_PATH}")
NUM_BYTES=$(wc -c < "${VIDEO_PATH}")
DISPLAY_NAME=VIDEO

tmp_header_file=upload-header.tmp

echo "Starting file upload..."
curl "https://generativelanguage.googleapis.com/upload/v1beta/files" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -D ${tmp_header_file} \
  -H "X-Goog-Upload-Protocol: resumable" \
  -H "X-Goog-Upload-Command: start" \
  -H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
  -H "Content-Type: application/json" \
  -d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null

upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"

echo "Uploading video data..."
curl "${upload_url}" \
  -H "Content-Length: ${NUM_BYTES}" \
  -H "X-Goog-Upload-Offset: 0" \
  -H "X-Goog-Upload-Command: upload, finalize" \
  --data-binary "@${VIDEO_PATH}" 2> /dev/null > file_info.json

file_uri=$(jq -r ".file.uri" file_info.json)
file_name=$(jq -r ".file.name" file_info.json)
echo file_uri=$file_uri

echo "File uploaded successfully. File URI: ${file_uri}"

# Polling loop
echo "Waiting for file to be processed..."
while true; do
  curl -s "https://generativelanguage.googleapis.com/v1beta/${file_name}" \
    -H "x-goog-api-key: $GEMINI_API_KEY" > file_status.json
  state=$(jq -r ".state" file_status.json)
  echo "Current state: $state"
  if [ "$state" == "ACTIVE" ]; then
    break
  elif [ "$state" == "FAILED" ]; then
    echo "File processing failed."
    exit 1
  fi
  sleep 5
done

echo "Generating content from video..."
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "video", "uri": "'${file_uri}'", "mime_type": "'${MIME_TYPE}'"},
        {"type": "text", "text": "Summarize this video. Then create a quiz with an answer key based on the information in this video."}
      ]
    }' 2> /dev/null > response.json

jq ".steps[].content[0].text" response.json

파일, 텍스트 프롬프트, 시스템 안내 등을 포함한 총 요청 크기가 20MB보다 크거나, 동영상 길이가 길거나, 여러 프롬프트에서 동일한 동영상을 사용하려는 경우 항상 Files API를 사용하세요. File API는 동영상 파일 형식을 직접 허용합니다.

미디어 파일 작업에 대해 자세히 알아보려면 Files API를 참고하세요.

동영상 데이터 인라인 전달

File API를 사용하여 동영상 파일을 업로드하는 대신 요청에서 더 작은 동영상을 직접 전달할 수 있습니다. 이는 총 요청 크기가 20MB 미만인 짧은 동영상에 적합합니다.

다음은 인라인 동영상 데이터를 제공하는 예입니다.

Python

from google import genai
import base64

video_file_name = "/path/to/your/video.mp4"
video_bytes = open(video_file_name, 'rb').read()

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "data": base64.b64encode(video_bytes).decode('utf-8'),
            "mime_type": "video/mp4"
        }
    ]
)
print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";
import * as fs from "node:fs";

const ai = new GoogleGenAI({});
const base64VideoFile = fs.readFileSync("path/to/small-sample.mp4", {
  encoding: "base64",
});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      data: base64VideoFile,
      mime_type: "video/mp4",
    }
  ],
});
console.log(interaction.output_text);

자바

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

REST

VIDEO_PATH=/path/to/your/video.mp4

if [[ "$(base64 --version 2>&1)" = *"FreeBSD"* ]]; then
  B64FLAGS="--input"
else
  B64FLAGS="-w0"
fi

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "data": "'$(base64 $B64FLAGS $VIDEO_PATH)'",
          "mime_type": "video/mp4"
        }
      ]
    }' 2> /dev/null

YouTube URL 전달

다음과 같이 요청의 일부로 YouTube URL을 Gemini API에 직접 전달할 수 있습니다.

Python

from google import genai

client = genai.Client()
interaction = client.interactions.create(
    model='gemini-3.8-flash',
    input=[
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
            "type": "video",
            "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    { type: "text", text: "Please summarize the video in 3 sentences." },
    {
      type: "video",
      uri: "https://www.youtube.com/watch?v=9hE5-98ZeCg",
    }
  ],
});
console.log(interaction.output_text);

자바

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-3.8-flash",
      "input": [
        {"type": "text", "text": "Please summarize the video in 3 sentences."},
        {
          "type": "video",
          "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg"
        }
      ]
    }' 2> /dev/null

제한사항:

무료 등급의 경우 하루에 8시간 이상의 YouTube 동영상을 업로드할 수 없습니다.
유료 등급의 경우 동영상 길이에 따라 제한이 없습니다.
Gemini 2.5 이전 모델의 경우 요청당 동영상 1개만 업로드할 수 있습니다. Gemini 2.5 이상 모델의 경우 요청당 최대 10개의 동영상을 업로드할 수 있습니다.
비공개 또는 일부 공개 동영상이 아닌 공개 동영상만 업로드할 수 있습니다.

에이전트형 동영상 이해

기본적으로 동영상 입력은 정적 처리 (1FPS로 프레임 추출)를 사용합니다. Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite 모델은 모델이 동영상 타임라인을 동적으로 탐색하고, 프롬프트에 따라 선택적으로 트랜스크립트를 검사하고, 즉석에서 프레임 속도와 해상도를 적응적으로 조정하는 에이전트형 동영상 이해도 지원합니다.

모드	설명	지원되는 모델
정적 (기본값)	고정된 속도 (1FPS)로 프레임을 추출하고 단일 패스에서 컨텍스트에 배치합니다. 짧은 클립에 적합합니다.	모든 Gemini 모델
에이전트형	모델은 동영상 타임라인을 동적으로 탐색하며 프롬프트에 따라 필요한 콘텐츠만 로드합니다. 긴 형식 콘텐츠에서 최대 88% 더 토큰 효율적이고 품질이 약 7% 더 높습니다.	Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite

처리 모드 선택

일반적인 가이드라인으로, 특히 응답 품질 또는 토큰 효율성을 최적화할 때는 에이전트형 모드로 시작하세요.

에이전트형: 긴 형식 동영상 또는 특정 순간을 타겟팅하는 쿼리. 모델은 컨텍스트 윈도우를 채우지 않고 타임라인을 동적으로 탐색하여 컨텍스트와 관련된 정보를 타겟팅합니다.
정적: 짧은 클립 (5분 미만)에 대한 지연 시간에 민감한 쿼리 또는 전체 클립에서 프레임 수준의 정밀도가 필요한 경우.

참고: 에이전트형 처리에 시간이 더 오래 걸리는 긴 동영상 또는 복잡한 프롬프트의 경우 스트리밍 (stream=True) 또는 백그라운드 실행(background=True)을 사용하세요. 이렇게 하면 연결이 활성 상태로 유지되고, 중간 추론 단계가 표시되며, 연결 또는 인증 시간 초과가 방지됩니다.

처리 모드 설정

Python

import time
from google import genai

client = genai.Client()

# Upload a long video
video_file = client.files.upload(file="path/to/lecture.mp4")

while video_file.state.name == "PROCESSING":
    time.sleep(2)
    video_file = client.files.get(name=video_file.name)

# Use agentic processing
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": "agentic"
        },
        {"type": "text", "text": "What are the three main arguments presented?"}
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

// Upload a long video
let videoFile = await ai.files.upload({
  file: "path/to/lecture.mp4",
  config: { mimeType: "video/mp4" }
});

while (videoFile.state === "PROCESSING") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  videoFile = await ai.files.get({ name: videoFile.name });
}

// Use agentic processing
const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: "agentic"
    },
    { type: "text", text: "What are the three main arguments presented?" }
  ]
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {"type": "text", "text": "What are the three main arguments presented?"}
    ]
  }' 2> /dev/null

참고: 에이전트형 처리가 사용되었는지 확인하려면 interaction.steps를 검사하세요. processing_call 및 processing_result가 있으면 모델이 동영상을 동적으로 탐색했음을 나타냅니다.

응답 단계

에이전트형 처리는 steps 배열에 두 가지 새로운 단계 유형을 추가합니다.

processing_call: 모델이 id로 식별되는 동영상 세그먼트 또는 오디오 트랜스크립트를 요청했습니다.
processing_result: call_id로 연결된 로드의 결과입니다.

이러한 단계는 thought 단계 (요약이 사용 설정된 경우)와 번갈아 표시되며 최종 model_output 단계 앞에 표시됩니다. UI에 진행률 추적을 표시하는 데 사용할 수 있지만 응답은 필요하지 않습니다.

다음 예는 번갈아 표시되는 처리 단계가 포함된 응답 페이로드를 보여줍니다.

{
  "steps": [
    {
      "type": "thought",
      "signature": "sig_thought_1",
      "summary": [
        {
          "type": "text",
          "text": "Inspecting transcript for key discussion topics..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_01",
      "signature": "sig_call_01"
    },
    {
      "type": "processing_result",
      "call_id": "call_01",
      "signature": "sig_result_01"
    },
    {
      "type": "thought",
      "signature": "sig_thought_2",
      "summary": [
        {
          "type": "text",
          "text": "Loading visual frames to verify slide content..."
        }
      ]
    },
    {
      "type": "processing_call",
      "id": "call_02",
      "signature": "sig_call_02"
    },
    {
      "type": "processing_result",
      "call_id": "call_02",
      "signature": "sig_result_02"
    },
    {
      "type": "thought",
      "signature": "sig_thought_3",
      "summary": [
        {
          "type": "text",
          "text": "Synthesizing answer from gathered evidence..."
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The three main arguments presented in the lecture are..."
        }
      ]
    }
  ]
}

동영상 간 처리 모드 혼합

동일한 요청에서 각 동영상에 대해 서로 다른 처리 모드를 설정할 수 있습니다.

Python

from google import genai

client = genai.Client()

lecture = client.files.upload(file="path/to/long-lecture.mp4")
experiment = client.files.upload(file="path/to/short-experiment.mp4")

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": lecture.uri,
            "mime_type": lecture.mime_type,
            "processing": "agentic"  # Use agentic video understanding
        },
        {
            "type": "video",
            "uri": experiment.uri,
            "mime_type": experiment.mime_type,
            "processing": "static"  # Use static processing
        },
        {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ]
)
print(interaction.output_text)

JavaScript

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

const ai = new GoogleGenAI({});

const lecture = await ai.files.upload({
  file: "path/to/long-lecture.mp4",
  config: { mimeType: "video/mp4" }
});
const experiment = await ai.files.upload({
  file: "path/to/short-experiment.mp4",
  config: { mimeType: "video/mp4" }
});

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: lecture.uri,
      mime_type: lecture.mimeType,
      processing: "agentic" // Use agentic video understanding
    },
    {
      type: "video",
      uri: experiment.uri,
      mime_type: experiment.mimeType,
      processing: "static" // Use static processing
    },
    { type: "text", text: "Compare the lecture content with the experiment results." }
  ]
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${lecture_uri}'",
        "mime_type": "video/mp4",
        "processing": "agentic"
      },
      {
        "type": "video",
        "uri": "'${experiment_uri}'",
        "mime_type": "video/mp4",
        "processing": "static"
      },
      {"type": "text", "text": "Compare the lecture content with the experiment results."}
    ]
  }' 2> /dev/null

멀티턴 동영상 대화

동영상 컨텍스트는 대화의 턴 간에 유지됩니다. 에이전트형 처리를 사용하는 경우:

상태 저장 모드 (previous_interaction_id 사용): 서버가 동영상 컨텍스트를 보관합니다. 추가 처리가 필요하지 않습니다.
스테이트리스 모드 (step_list 사용): 스테이트리스 모드에서 응답에는 동영상 컨텍스트를 인코딩하는 processing_call 및 processing_result 단계가 포함됩니다. 동영상 컨텍스트를 유지하려면 다음 요청의 step_list에 응답의 모든 단계를 포함해야 합니다. 현재는 이를 생략해도 API 오류가 반환되지 않지만 동영상 컨텍스트가 손실되어 후속 질문에 대한 응답 품질이 크게 저하됩니다. 후속 요청에서 전송된 반환된 단계는 입력 토큰 수에 영향을 미칩니다.

콘텐츠의 타임스탬프 참조

MM:SS 형식의 타임스탬프를 사용하여 동영상 내의 특정 시점에 관한 질문을 할 수 있습니다.

Python

prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?"

JavaScript

const prompt = "What are the examples given at 00:05 and 00:10 supposed to show us?";

자바

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

REST

PROMPT="What are the examples given at 00:05 and 00:10 supposed to show us?"

동영상에서 세부적인 유용한 정보 추출

Gemini 모델은 오디오 및 시각적 스트림 모두에서 정보를 처리하여 동영상 콘텐츠를 이해하는 강력한 기능을 제공합니다. 이를 통해 동영상에서 발생하는 상황에 관한 설명을 생성하고 콘텐츠에 관한 질문에 답변하는 등 다양한 세부정보를 추출할 수 있습니다.

시각적 설명의 경우 모델은 초당 1프레임 (FPS)의 속도로 동영상을 샘플링합니다. 이 기본 샘플링 속도는 대부분의 콘텐츠에 적합하지만, 동작이 빠르거나 장면이 빠르게 바뀌는 동영상에서는 세부정보가 누락될 수 있습니다.

Python

prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

JavaScript

const prompt = "Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments.";

자바

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.Content;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.interactions.TextContent;
import com.google.genai.gaos.models.interactions.VideoContent;
import com.google.genai.gaos.models.interactions.VideoContentMimeType;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;
import java.util.Arrays;
import java.util.List;

Client client = new Client();

Content textContent = TextContent.builder().text("Summarize the key events in this video.").build();
Content videoContent =
    VideoContent.builder()
        .uri("gs://cloud-samples-data/generative-ai/video/pixel8.mp4")
        .mimeType(VideoContentMimeType.VIDEO_MP4)
        .build();

List<Content> contents = Arrays.asList(textContent, videoContent);

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.ofContent(contents))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

REST

PROMPT="Describe the key events in this video, providing both audio and visual details. Include timestamps for salient moments."

동영상 처리 맞춤설정

클리핑 간격을 설정하거나 커스텀 프레임 속도 샘플링을 제공하여 Gemini API에서 동영상 처리를 맞춤설정할 수 있습니다. 이러한 맞춤설정 옵션 은 "static" 모드에서 동영상을 처리할 때만 지원됩니다.

클리핑 간격 설정

processing 구성 객체에서 start_offset 및 end_offset을 지정하여 동영상을 클립할 수 있습니다.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "start_offset": 1200,
                "end_offset": 1500,
            },
        },
        {"type": "text", "text": "Summarize this section of the video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        start_offset: 1200,
        end_offset: 1500,
      },
    },
    { type: "text", text: "Summarize this section of the video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "start_offset": 1200,
          "end_offset": 1500
        }
      },
      {"type": "text", "text": "Summarize this section of the video."}
    ]
  }' 2> /dev/null

커스텀 프레임 속도 설정

processing 구성 객체에서 fps 인수를 전달하여 커스텀 프레임 속도 샘플링을 설정할 수 있습니다.

Python

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "video",
            "uri": video_file.uri,
            "mime_type": video_file.mime_type,
            "processing": {
                "type": "static",
                "fps": 0.5,  # Sample 1 frame every 2 seconds
            },
        },
        {"type": "text", "text": "Describe the scene changes in this video."},
    ],
)
print(interaction.output_text)

JavaScript

const interaction = await ai.interactions.create({
  model: "gemini-3.8-flash",
  input: [
    {
      type: "video",
      uri: videoFile.uri,
      mime_type: videoFile.mimeType,
      processing: {
        type: "static",
        fps: 0.5, // Sample 1 frame every 2 seconds
      },
    },
    { type: "text", text: "Describe the scene changes in this video." },
  ],
});
console.log(interaction.output_text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gemini-3.8-flash",
    "input": [
      {
        "type": "video",
        "uri": "'${file_uri}'",
        "mime_type": "video/mp4",
        "processing": {
          "type": "static",
          "fps": 0.5
        }
      },
      {"type": "text", "text": "Describe the scene changes in this video."}
    ]
  }' 2> /dev/null

지원되는 동영상 형식

Gemini는 다음과 같은 동영상 형식 MIME 유형을 지원합니다.

video/mp4
video/mpeg
video/mov
video/avi
video/x-flv
video/mpg
video/webm
video/wmv
video/3gpp

동영상에 대한 기술 세부정보

지원되는 모델 및 컨텍스트: 모든 Gemini 모델은 동영상 데이터를 처리할 수 있습니다.
- 1M 컨텍스트 윈도우 모델은 기본적으로 최대 3시간 길이의 동영상(낮은 미디어 해상도) 또는 최대 1시간 길이의 동영상(높은 미디어 해상도)을 처리할 수 있습니다.
처리 모드: Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite, 및 이후 모델은 두 가지 동영상 처리 모드를 지원합니다.
- 정적: 프레임이 1FPS로 추출되어 컨텍스트에 배치됩니다 (모든 모델의 기본값 ). 오디오는 1Kbps (단일 채널)로 처리됩니다. 타임스탬프는 매초마다 추가됩니다. 짧은 클립에 적합하거나 모든 프레임이 중요한 경우 (예: 프레임별 검사). 빠른 액션 시퀀스는 1FPS 샘플링 속도로 인해 세부정보가 손실될 수 있습니다.
- 에이전트형: 모델은 동영상을 동적으로 탐색하며 필요에 따라 트랜스크립트 또는 프레임 또는 오디오를 로드합니다. 생성이 시작되기 전에 내부 추론 및 도구 왕복으로 인해 탐색으로 인해 짧은 클립 (5분 미만)에서 첫 번째 토큰까지의 시간(TTFT)이 약간 증가할 수 있지만 긴 형식 콘텐츠의 경우 최대 88% 더 적은 토큰을 사용합니다. 토큰 비용과 응답 품질을 최적화하는 데 긴 형식 동영상에 가장 적합합니다. Gemini 3.8 Flash, 3.7 Flash, 3.6 Flash, 3.5 Flash Lite에서 지원됩니다. 자세한 내용은 에이전트형 동영상 이해를 참고하세요.
토큰 계산 (정적 모드): 동영상의 각 초는 다음과 같이 토큰화됩니다.
- 개별 프레임 (1FPS로 샘플링됨):
  - media_resolution이 낮음으로 설정되면 프레임이 프레임당 66개 토큰으로 토큰화됩니다.
  - 그렇지 않으면 프레임이 프레임당 258개의 토큰으로 토큰화됩니다.
- 오디오: 초당 토큰 32개
- 메타데이터도 포함됩니다.
- 총계: 기본 (낮음) 미디어 해상도 동영상에서 초당 약 100개 토큰 또는 높은 미디어 해상도 동영상에서 초당 약 300개 토큰
토큰 계산 (에이전트형 모드): 토큰 사용량은 콘텐츠 복잡성과 모델의 탐색 전략에 따라 다릅니다. 동영상 탐색 중에 생성된 탐색 추론 토큰 은 추론 토큰 (total_thought_tokens)으로 계산되는 반면, 필요에 따라 로드된 프레임, 오디오, 트랜스크립트는 도구 사용 토큰 (total_tool_use_tokens)으로 계산됩니다. 에이전트형 처리는 일반적으로 모델이 프롬프트에 답변하는 데 필요한 트랜스크립트 또는 프레임 또는 오디오만 로드하므로 긴 형식 콘텐츠의 경우 정적 처리보다 총 토큰을 최대 88% 적게 사용합니다 (토큰 가이드 참고).
미디어 해상도: Gemini 3는 멀티모달 비전 처리에 대한 세밀한 제어 기능을 media_resolution 파라미터를 통해 제공합니다. media_resolution 파라미터는 입력 이미지 또는 동영상 프레임당 할당되는 최대 토큰 수 를 결정합니다. 해상도가 높을수록 모델이 작은 텍스트를 읽거나 세부 요소를 식별하는 능력을 향상시키지만, 토큰 사용량과 지연 시간이 증가합니다. media_resolution 및 processing 파라미터는 독립적입니다. 동일한 동영상 입력에 둘 다 설정할 수 있습니다.

토큰 계산에 관한 자세한 내용은 토큰 가이드를 참고하세요.

타임스탬프 형식: 프롬프트 내에서 동영상의 특정 순간을 언급할 때는 MM:SS 형식을 사용하세요 (예: 1분 15초의 경우 01:15).
프롬프트 배치: 텍스트와 단일 동영상을 결합하는 경우 input 배열의 동영상 부분 뒤에 텍스트 프롬프트를 배치합니다.
긴 요청의 시간 초과: 처리 시간이 길거나 복잡한 다단계 추론이 필요한 동영상의 경우 스트리밍(stream=True) 또는 백그라운드 실행 (background=True)을 사용하세요. 수요가 많은 경우 백엔드 재시도가 발생하는 동기식 비스트리밍 요청은 연결 또는 인증 토큰 유효성 검사 기간을 초과할 수 있으며, 이로 인해 예기치 않은 401 Unauthorized 또는 시간 초과 오류가 발생할 수 있습니다. 스트리밍은 연결을 활성 상태로 유지하고 중간 추론 및 도구 호출 진행률을 표시합니다.

다음 단계

미디어 해상도: 동영상 프레임의 해상도를 제어하여 품질과 토큰 사용량의 균형을 맞춥니다.
토큰: 정적 및 에이전트형 처리 모드 모두에서 동영상 콘텐츠가 토큰화되는 방식을 이해합니다.
시스템 안내: 시스템 안내를 사용하면 사용자가 특정 요구사항 및 사용 사례에 따라 모델의 동작을 조정할 수 있습니다.
Files API: Gemini에서 사용할 파일을 업로드하고 관리하는 방법을 자세히 알아봅니다.
파일 프롬프트 전략: Gemini API는 멀티모달 프롬프트 사용이라고도 하는 텍스트, 이미지, 오디오, 동영상 데이터로 프롬프트를 지원합니다.
안전 가이드: 생성형 AI 모델은 때때로 부정확하거나 편향되거나 불쾌감을 주는 등 예기치 않은 출력을 생성합니다. 이러한 출력으로 인한 피해 위험을 제한하려면 후처리 및 인간 평가가 필수적입니다.