이제 Gemini 1.5 Pro 2M 컨텍스트 윈도우, 코드 실행 기능, Gemma 2를 사용할 수 있습니다. 자세히 알아보기

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

미디어 파일로 메시지 표시

Gemini API는 텍스트, 이미지, 오디오, 동영상 데이터의 프롬프팅(멀티모달 프롬프팅이라고도 함)을 지원합니다. 즉, 이러한 유형의 미디어 파일을 프롬프트에 포함할 수 있습니다. 작은 파일의 경우 프롬프트를 제공할 때 Gemini 모델이 로컬 파일을 직접 가리킬 수 있습니다 대용량 파일을 프롬프트에 포함하기 전에 File API를 사용하여 업로드하세요.

File API를 사용하면 프로젝트당 파일을 20GB까지 저장할 수 있으며 각 파일의 크기는 2GB를 넘지 않아야 합니다. 파일은 48시간 동안 저장되며 이 기간 내에 생성을 위해 API 키를 사용하여 액세스할 수 있으며 API에서 다운로드할 수 없습니다. Files API는 Gemini API가 제공되는 모든 리전에서 무료로 사용할 수 있습니다.

File API는 model.generateContent 또는 model.streamGenerateContent로 콘텐츠를 생성하는 데 사용할 수 있는 입력을 처리합니다. 유효한 파일 형식 (MIME 유형)과 지원되는 모델에 관한 자세한 내용은 지원되는 파일 형식을 참조하세요.

이 가이드에서는 File API를 사용하여 미디어 파일을 업로드하고 Gemini API에 대한 GenerateContent 호출에 포함하는 방법을 보여줍니다. 자세한 내용은 코드 샘플을 참고하세요.

시작하기 전에: 프로젝트 및 API 키 설정

Gemini API (또는 File API)를 호출하기 전에 프로젝트를 설정하고 API 키를 구성해야 합니다.

펼쳐서 프로젝트 및 API 키를 설정하는 방법 보기

Python SDK 설치 및 패키지 가져오기

Gemini API용 Python SDK는 google-generativeai 패키지에 포함되어 있습니다.

pip를 사용하여 종속 항목을 설치합니다.
```
pip install -q -U google-generativeai
```

필요한 패키지를 가져옵니다.

import google.generativeai as genai
from IPython.display import Markdown

API 키 보호 및 구성

Gemini API 및 File API를 호출하려면 API 키가 필요합니다. 아직 키가 없다면 Google AI Studio에서 키를 만듭니다.

API 키 가져오기

GOOGLE_API_KEY라는 Colab 보안 비밀에 API 키를 저장합니다. Colab 보안 비밀에 익숙하지 않은 경우 인증 빠른 시작을 참고하세요.

from google.colab import userdata
GOOGLE_API_KEY=userdata.get('GOOGLE_API_KEY')

genai.configure(api_key=GOOGLE_API_KEY)

이미지로 메시지 표시

이 튜토리얼에서는 File API를 사용하여 샘플 이미지를 업로드한 다음 이를 사용하여 콘텐츠를 생성합니다.

이미지 파일 업로드

자체 파일을 업로드하는 방법을 알아보려면 부록 섹션을 참조하세요.

업로드할 샘플 이미지를 준비합니다.

  curl -o image.jpg https://storage.googleapis.com/generativeai-downloads/images/jetpack.jpg

다른 API 호출을 통해 액세스할 수 있도록 media.upload를 사용하여 해당 파일을 업로드합니다.

sample_file = genai.upload_file(path="image.jpg",
                            display_name="Sample drawing")

print(f"Uploaded file '{sample_file.display_name}' as: {sample_file.uri}")

response는 업로드된 이미지가 지정된 display_name로 저장되고 Gemini API 호출에서 파일을 참조하는 uri가 있음을 보여줍니다. 업로드된 파일이 URI에 매핑되는 방식을 추적하려면 response를 사용합니다.

사용 사례에 따라 URI를 dict 또는 데이터베이스와 같은 구조에 저장할 수 있습니다.

이미지 파일의 메타데이터 가져오기

파일을 업로드한 후 API가 파일을 성공적으로 저장했는지 확인하고 SDK를 통해 files.get를 호출하여 파일의 메타데이터를 가져올 수 있습니다.

이 메서드를 사용하면 API 키에 연결된 Google Cloud 프로젝트와 연결된 업로드된 파일의 메타데이터를 가져올 수 있습니다. name (및 더 나아가 uri)만 고유합니다. 고유성을 직접 관리하는 경우에만 display_name를 사용하여 파일을 식별합니다.

file = genai.get_file(name=sample_file.name)
print(f"Retrieved file '{file.display_name}' as: {sample_file.uri}")

업로드된 이미지 파일을 사용하여 콘텐츠 생성

이미지를 업로드한 후 응답에서 uri를 참조하는 GenerateContent 요청을 할 수 있습니다 (파일을 업로드하거나 파일의 메타데이터를 직접 가져와).

이 예에서는 텍스트로 시작하고 그 뒤에 업로드된 파일에 대한 URI 참조가 오는 프롬프트를 만듭니다.

# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")

response = model.generate_content([sample_file, "Describe the image with a creative description."])

Markdown(">" + response.text)

이미지 파일 삭제

파일은 48시간 후 자동으로 삭제됩니다. SDK를 통해 files.delete를 사용하여 수동으로 삭제할 수도 있습니다.

genai.delete_file(sample_file.name)
print(f'Deleted {sample_file.display_name}.')

동영상으로 메시지 표시

이 튜토리얼에서는 File API를 사용하여 샘플 동영상을 업로드한 다음 이를 사용하여 콘텐츠를 생성합니다.

동영상 파일 업로드

Gemini API는 동영상 파일 형식을 직접 허용합니다. 이 예에서는 단편 영화 'Big Buck Bunny'를 사용합니다.

'Big Buck Bunny'는 (c) 저작권 2008, Blender Foundation / www.bigbuckbunny.org이며 크리에이티브 커먼즈 저작자 표시 3.0 라이선스에 따라 사용이 허가되었습니다.

자체 파일을 업로드하는 방법을 알아보려면 부록 섹션을 참조하세요.

업로드할 샘플 동영상 파일을 준비합니다.

wget https://download.blender.org/peach/bigbuckbunny_movies/BigBuckBunny_320x180.mp4

다른 API 호출을 통해 액세스할 수 있도록 media.upload를 사용하여 해당 파일을 업로드합니다.

video_file_name = "BigBuckBunny_320x180.mp4"

print(f"Uploading file...")
video_file = genai.upload_file(path=video_file_name)
print(f"Completed upload: {video_file.uri}")

동영상 파일의 업로드 상태 확인

API가 SDK를 통해 files.get 메서드를 호출하여 동영상 파일을 성공적으로 업로드했는지 확인합니다.

동영상 파일에는 File API의 State 필드가 있습니다. 동영상이 업로드되면 추론할 준비가 될 때까지 PROCESSING 상태가 됩니다. 모델 추론에는 ACTIVE 파일만 사용할 수 있습니다.

import time

while video_file.state.name == "PROCESSING":
    print('.', end='')
    time.sleep(10)
    video_file = genai.get_file(video_file.name)

if video_file.state.name == "FAILED":
  raise ValueError(video_file.state.name)

동영상 파일의 메타데이터 가져오기

SDK를 통해 files.get 메서드를 호출하여 언제든지 업로드된 동영상 파일의 메타데이터를 가져올 수 있습니다.

file = genai.get_file(name=video_file.name)
print(f"Retrieved file '{file.display_name}' as: {video_file.uri}")

업로드된 동영상 파일을 사용하여 콘텐츠 생성

동영상을 업로드한 후 응답에서 uri를 참조하는 GenerateContent 요청을 할 수 있습니다 (파일을 업로드하거나 파일의 메타데이터를 직접 가져와).

동영상에서 추론을 실행하기 전에 동영상 파일의 업로드 상태를 확인해야 합니다 (위 섹션).

# Create the prompt.
prompt = "Describe this video."

# The Gemini 1.5 models are versatile and work with multimodal prompts
model = genai.GenerativeModel(model_name="models/gemini-1.5-flash")

# Make the LLM request.
print("Making LLM inference request...")
response = model.generate_content([video_file, prompt],
                                  request_options={"timeout": 600})
print(response.text)

동영상 파일 삭제

파일은 48시간 후 자동으로 삭제됩니다. SDK를 통해 files.delete를 사용하여 수동으로 삭제할 수도 있습니다.

genai.delete_file(file_response.name)
print(f'Deleted file {file_response.uri}')

지원되는 파일 형식

Gemini 모델은 다양한 파일 형식을 이용한 프롬프팅을 지원합니다. 이 섹션에서는 특히 이미지, 오디오, 동영상, 일반 텍스트 파일을 프롬프트에 사용하기 위해 일반 미디어 형식을 사용할 때 고려해야 할 사항을 설명합니다. 다음 표와 같이 특정 모델 버전에서만 메시지를 표시하는 데 미디어 파일을 사용할 수 있습니다.

모델	이미지	오디오	동영상	일반 텍스트
Gemini 1.5 Pro (버전 008 이상)	✔ (최대 3,600개의 이미지 파일)	✔	✔	✔

이미지 형식

Gemini 1.5 모델의 프롬프트에 이미지 데이터를 사용할 수 있습니다. 프롬프트에 이미지를 사용하는 경우 다음과 같은 제한사항 및 요구사항이 적용됩니다.

이미지는 다음 이미지 데이터 MIME 유형 중 하나여야 합니다.
- PNG - image/png
- JPEG - image/jpeg
- WEBP - image/webp
- HEIC - image/heic
- HEIF - image/heif
Gemini 1.5 모델의 경우 최대 3,600개의 이미지
이미지의 픽셀 수에는 특별한 제한이 없습니다. 그러나 더 큰 이미지는 원래 가로세로 비율을 유지하면서 최대 해상도 3072 x 3072에 맞게 축소됩니다.

오디오 형식

Gemini 1.5 모델의 프롬프트에 오디오 데이터를 사용할 수 있습니다. 프롬프트에 오디오를 사용하는 경우 다음과 같은 제한사항 및 요구사항이 적용됩니다.

오디오 데이터는 다음과 같은 일반적인 오디오 형식 MIME 유형으로 지원됩니다.
- WAV - 오디오/wav
- MP3 - 오디오/mp3
- AIFF - 오디오/AIFF
- AAC - 오디오/aac
- OGG Vorbis - 오디오/ogg
- FLAC - 오디오/flac
단일 프롬프트에서 지원되는 최대 오디오 데이터 길이는 9.5시간입니다.
오디오 파일은 데이터 해상도 16Kbps까지 리샘플링되며 여러 오디오 채널이 단일 채널로 결합됩니다.
단일 프롬프트의 오디오 파일 수에는 특별한 제한이 없습니다. 하지만 단일 프롬프트에 포함된 모든 오디오 파일의 총 길이는 9.5시간을 초과할 수 없습니다.

동영상 형식

Gemini 1.5 모델의 프롬프트에 동영상 데이터를 사용할 수 있습니다.

동영상 데이터는 다음과 같은 일반적인 동영상 형식 MIME 유형으로 지원됩니다.
- video/mp4
- video/mpeg
- 동영상/mov
- 동영상/avi
- video/x-flv
- 동영상/mpg
- 동영상/webm
- 동영상/wmv
- 동영상/3gpp
File API 서비스는 초당 1프레임 (FPS) 속도로 동영상을 이미지로 샘플링하며 최상의 추론 품질을 제공하기 위해 변경될 수 있습니다. 개별 이미지는 해상도와 품질에 관계없이 최대 258개의 토큰을 사용합니다.

일반 텍스트 형식

File API는 다음 MIME 유형의 일반 텍스트 파일 업로드를 지원합니다.

text/plain
text/html
text/css
text/javascript
application/x-javascript
텍스트/x-typescript
애플리케이션/x-typescript
text/csv
텍스트/마크다운
텍스트/x-python
application/x-python-code
application/json
text/xml
애플리케이션/rtf
텍스트/rtf

MIME 유형이 목록에 없는 일반 텍스트 파일의 경우 위의 MIME 유형 중 하나를 직접 지정해 볼 수 있습니다.

부록: Colab에 파일 업로드하기

이 노트북은 인터넷에서 다운로드한 파일에 File API를 사용합니다. Colab에서 실행 중이고 자체 파일을 사용하려면 먼저 Colab 인스턴스에 파일을 업로드해야 합니다.

먼저 왼쪽 사이드바에서 파일을 클릭한 다음 업로드 버튼을 클릭합니다.

다음으로 이 파일을 File API에 업로드합니다. 아래 코드 셀의 양식에 업로드한 파일의 이름을 입력하고 적절한 파일 표시 이름을 입력한 후 셀을 실행합니다.

my_filename = "gemini_logo.png" # @param {type:"string"}
my_file_display_name = "Gemini Logo" # @param {type:"string"}

my_file = genai.upload_file(path=my_filename,
                            display_name=my_file_display_name)
print(f"Uploaded file '{my_file.display_name}' as: {my_file.uri}")