이미지, 영상, 음성

모델 하나로 세 가지 감각 다루기

Gemini 2.5 Flash와 Pro는 같은 대화에서 텍스트, 이미지, 영상, 음성을 받아. 모델이나 엔드포인트를 바꿀 필요 없이 contents에 알맞은 Part 형식을 넣으면 돼.

미디어를 첨부하는 두 가지 방법

인라인 바이트 — 파일을 base64로 인코딩해 요청에 함께 보내. 전체 요청 크기가 20MB 이하인 작은 파일에 알맞아.
File API — client.files.upload로 먼저 올리고 반환된 파일 URI를 참조해. 큰 파일에는 필수고 영상에도 반드시 써야 해.

File API로 올린 파일은 48시간 동안 유지돼. 실제 생성 호출을 만들기에는 충분한 시간이야.

토큰 비용은 글자 수가 아니라 입력 형태로 정해져

이미지: 384px 이하는 258토큰이야. 더 크면 768×768 타일마다 258토큰을 써.
영상: 초당 약 300토큰이고 최대 1시간이야. YouTube URL도 직접 지원해.
음성: 초당 32토큰이고 최대 9.5시간이야.

지원 형식

이미지: PNG, JPEG, WEBP, HEIC.
영상: MP4, MOV, AVI, FLV, MPG, WMV, 3GPP, WEBM.
음성: WAV, MP3, AIFF, AAC, OGG, FLAC.

Code

이미지 — 인라인 바이트·python

from google import genai
from google.genai import types
from pathlib import Path

client = genai.Client()
img_bytes = Path('photo.jpg').read_bytes()

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=[
        types.Part.from_bytes(data=img_bytes, mime_type='image/jpeg'),
        'Caption this image in one sentence.',
    ],
)
print(response.text)

이미지 — File API(큰 파일에 권장)·python

uploaded = client.files.upload(file='photo.jpg')

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=[uploaded, 'Describe in 3 sentences.'],
)
print(response.text)

# When done
client.files.delete(name=uploaded.name)

영상 — 처리 완료 기다리기·python

import time

uploaded = client.files.upload(
    file='lecture.mp4',
    config=types.UploadFileConfig(display_name='Lecture'),
)

# Big videos go through PROCESSING — poll until ACTIVE
while uploaded.state.name == 'PROCESSING':
    time.sleep(2.5)
    uploaded = client.files.get(name=uploaded.name)

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=[uploaded, 'Summarize the key points.'],
)

음성 — 받아쓰기·python

uploaded = client.files.upload(file='podcast.mp3')

response = client.models.generate_content(
    model='gemini-2.5-flash',
    contents=[
        'Transcribe this audio. Use proper punctuation and paragraph breaks.',
        uploaded,
    ],
)
print(response.text)

Exercise

컴퓨터에서 이미지 하나, 30초 이하의 짧은 영상 하나, 음성 클립 하나를 골라. 각각 File API로 올리고 캡션·설명·받아쓰기에 맞는 프롬프트와 함께 Flash로 보내 응답을 출력한 뒤 파일을 삭제하는 Python 스크립트 하나를 작성해. PROCESSING 지연도 감지해 보고하도록 만들어.