Gemini 3 개발자 가이드

Gemini 3 개발자 가이드 (Gemini 3 developer guide)

사용 중단 공지: 이 페이지는 더 이상 사용되지 않으며(deprecated) 제거될 예정이에요. 마이그레이션 지침, 프롬프팅 모범 사례, 모든 Gemini 3.x 모델의 업데이트된 기능 개요를 포함한 최신 개발자 가이드는 What's new in Gemini 3.5 Flash 가이드를 참고하세요.

Gemini 3는 최첨단 추론의 기반 위에 구축된 현재까지 가장 지능적인 모델 제품군이에요. 에이전틱 워크플로우, 자율 코딩, 복잡한 멀티모달 작업을 마스터해 어떤 아이디어든 실현하도록 설계되었어요. 이 가이드는 Gemini 3 모델 제품군의 핵심 기능과 이를 최대한 활용하는 방법을 다룰게요.

Gemini 3 앱 컬렉션을 살펴보고 모델이 고급 추론, 자율 코딩, 복잡한 멀티모달 작업을 어떻게 처리하는지 확인해 보세요.

몇 줄의 코드로 시작해 보세요.

출처: 원문

본문

Gemini 3 시리즈 소개

Gemini 3.1 Pro는 모달리티 전반에서 폭넓은 세계 지식과 고급 추론이 필요한 복잡한 작업에 가장 적합해요.

Gemini 3 Flash는 Flash의 속도와 가격으로 Pro 수준의 지능을 제공하는 최신 3 시리즈 모델이에요.

Nano Banana Pro(Gemini 3 Pro Image라고도 함)는 최고 품질의 이미지 생성 모델이고, Nano Banana 2(Gemini 3.1 Flash Image라고도 함)는 대용량·고효율·저가격에 해당하는 모델이에요.

Gemini 3.1 Flash-Lite는 비용 효율적 모델과 대용량 작업을 위해 설계된 작업용(workhorse) 모델이에요.

모델 ID	컨텍스트 윈도우 (입력 / 출력)	지식 기준 시점	가격 (입력 / 출력)*
gemini-3.1-flash-lite	1M / 64k	2025년 1월	$0.25 (텍스트, 이미지, 영상), $0.50 (오디오) / $1.50
gemini-3.1-flash-image-preview	128k / 32k	2025년 1월	$0.25 (텍스트 입력) / $0.067 (이미지 출력)**
gemini-3.1-pro-preview	1M / 64k	2025년 1월	$2 / $12 (<20만 토큰) $4 / $18 (>20만 토큰)
gemini-3-flash-preview	1M / 64k	2025년 1월	$0.50 / $3
gemini-3-pro-image-preview	65k / 32k	2025년 1월	$2 (텍스트 입력) / $0.134 (이미지 출력)**

달리 명시되지 않는 한 가격은 1백만 토큰당 가격이에요. ** 이미지 가격은 해상도에 따라 달라요. 자세한 내용은 가격 페이지를 참고하세요.

자세한 한도, 가격 및 추가 정보는 모델 페이지를 참고하세요.

Gemini 3의 새로운 API 기능 (New API features in Gemini 3)

Gemini 3는 개발자에게 지연 시간, 비용, 멀티모달 충실도에 대한 더 많은 제어권을 주기 위해 설계된 새로운 파라미터를 도입해요.

Thinking 수준 (Thinking level)

Gemini 3 시리즈 모델은 프롬프트를 추론하기 위해 기본적으로 동적 thinking을 사용해요. thinking_level 파라미터를 사용할 수 있으며, 이는 모델이 응답을 생성하기 전에 내부 추론 과정의 최대 깊이를 제어해요. Gemini 3는 이러한 수준을 엄격한 토큰 보장이 아니라 상대적인 thinking 허용량으로 취급해요.

thinking_level을 지정하지 않으면 Gemini 3는 기본적으로 high로 설정돼요. 복잡한 추론이 필요하지 않을 때 더 빠르고 저지연 응답을 원한다면 모델의 thinking 수준을 low로 제한할 수 있어요.

Thinking 수준	Gemini 3.1 Pro	Gemini 3.1 Flash-Lite	Gemini 3 Flash	설명
`minimal`	미지원	지원 (기본값)	지원	대부분의 쿼리에서 "생각 안 함" 설정과 일치해요. 모델은 복잡한 코딩 작업에서 아주 최소한으로만 생각할 수 있어요. 채팅 또는 고처리량 애플리케이션에서 지연 시간을 최소화해요. 참고로 `minimal`은 thinking이 꺼진 것을 보장하지는 않아요.
`low`	지원	지원	지원	지연 시간과 비용을 최소화해요. 간단한 지시 따르기, 채팅, 고처리량 애플리케이션에 가장 적합해요.
`medium`	지원	지원	지원	대부분의 작업에 균형 잡힌 thinking을 제공해요.
`high`	지원 (기본값, 동적)	지원 (동적)	지원 (기본값, 동적)	추론 깊이를 최대화해요. 모델이 첫 번째(비 thinking) 출력 토큰에 도달하는 데 훨씬 더 오래 걸릴 수 있지만, 출력은 더 신중하게 추론된 결과일 거예요.

중요: 동일한 요청에서 thinking_level과 레거시 thinking_budget 파라미터를 함께 사용할 수 없어요. 그렇게 하면 400 오류가 반환돼요.

미디어 해상도 (Media resolution)

Gemini 3는 media_resolution 파라미터를 사용해 멀티모달 비전 처리에 대한 세밀한 제어를 도입해요. 더 높은 해상도는 미세한 텍스트를 읽거나 작은 세부 사항을 식별하는 모델의 능력을 향상시키지만, 토큰 사용량과 지연 시간이 증가해요. media_resolution 파라미터는 입력 이미지 또는 비디오 프레임당 할당되는 최대 토큰 수를 결정해요.

이제 개별 미디어 파트별로 또는 전역적으로(generation_config 사용, 울트라 하이에는 전역 미지원) media_resolution_low, media_resolution_medium, media_resolution_high, media_resolution_ultra_high로 해상도를 설정할 수 있어요. 지정하지 않으면 모델은 미디어 유형에 따라 최적의 기본값을 사용해요.

권장 설정 (Recommended settings)

미디어 유형	권장 설정	최대 토큰	사용 지침
이미지	`media_resolution_high`	1120	최대 품질을 보장하기 위해 대부분의 이미지 분석 작업에 권장돼요.
PDF	`media_resolution_medium`	560	문서 이해에 최적이에요. 품질은 일반적으로 `medium`에서 포화됩니다. 일반 문서의 경우 `high`로 올려도 OCR 결과가 거의 개선되지 않아요.
비디오 (일반)	`media_resolution_low` (또는 `media_resolution_medium`)	70 (프레임당)	참고: 비디오의 경우 `low`와 `medium` 설정은 컨텍스트 사용을 최적화하기 위해 동일하게(70 토큰) 처리돼요. 이는 대부분의 동작 인식 및 설명 작업에 충분해요.
비디오 (텍스트 중심)	`media_resolution_high`	280 (프레임당)	비디오 프레임 내 조밀한 텍스트(OCR) 또는 작은 세부 사항 읽기가 포함된 사용 사례에만 필요해요.

참고: media_resolution 파라미터는 입력 유형에 따라 다른 토큰 수에 매핑돼요. 이미지는 선형적으로 확장되지만(media_resolution_low: 280, media_resolution_medium: 560, media_resolution_high: 1120), 비디오는 더 공격적으로 압축돼요. 비디오의 경우 media_resolution_low와 media_resolution_medium 모두 프레임당 70 토큰으로 제한되고, media_resolution_high는 280 토큰으로 제한돼요. 전체 세부 사항은 미디어 해상도 페이지를 참고하세요.

Temperature

모든 Gemini 3 모델에서 temperature 파라미터를 기본값인 1.0으로 유지하는 것을 강력히 권장해요.

이전 모델은 창의성과 결정론을 제어하기 위해 temperature를 조정하는 것이 유익한 경우가 많았지만, Gemini 3의 추론 능력은 기본 설정에 최적화되어 있어요. temperature를 변경하면(1.0 미만으로 설정) 특히 복잡한 수학 또는 추론 작업에서 루프나 성능 저하 같은 예상치 못한 동작이 발생할 수 있어요.

생각 서명 (Thought signatures)

Gemini 3는 생각 서명을 사용해 API 호출 간 추론 컨텍스트를 유지해요. 이러한 서명은 모델의 내부 생각 과정을 암호화한 표현이에요. 모델이 추론 능력을 유지하도록 하려면 수신한 서명을 요청에서 받은 그대로 정확히 모델에 다시 반환해야 해요.

함수 호출(엄격): API는 "현재 턴"에 대해 엄격한 검증을 적용해요. 서명이 없으면 400 오류가 발생해요.

참고: Gemini 3 Flash에서 thinking 수준이 minimal로 설정된 경우에도 생각 서명의 순환은 필수예요.

텍스트/채팅: 검증이 엄격하게 적용되지는 않지만, 서명을 생략하면 모델의 추론과 답변 품질이 저하돼요.
이미지 생성/편집(엄격): API는 thoughtSignature를 포함한 모든 Model 파트에 대해 엄격한 검증을 적용해요. 서명이 없으면 400 오류가 발생해요.

성공: 공식 SDK(Python, Node, Java)와 표준 채팅 기록을 사용하면 생각 서명이 자동으로 처리돼요. 이러한 필드를 수동으로 관리할 필요가 없어요.

함수 호출 (엄격 검증)

Gemini가 functionCall을 생성하면 다음 턴에서 도구의 출력을 올바르게 처리하기 위해 thoughtSignature에 의존해요. "현재 턴"에는 마지막 표준 User text 메시지 이후 발생한 모든 Model(functionCall) 및 User(functionResponse) 단계가 포함돼요.

단일 함수 호출: functionCall 파트에 서명이 포함되어 있어요. 이를 반환해야 해요.
병렬 함수 호출: 목록의 첫 번째 functionCall 파트에만 서명이 포함돼요. 수신한 정확한 순서대로 파트를 반환해야 해요.
다단계(순차): 모델이 도구를 호출하고 결과를 받은 후 (같은 턴 내에서) 다른 도구를 호출하면 두 함수 호출 모두 서명을 가져요. 기록의 모든 누적 서명을 반환해야 해요.

텍스트 및 스트리밍

표준 채팅 또는 텍스트 생성에서는 서명의 존재가 보장되지 않아요.

비스트리밍: 응답의 최종 콘텐츠 파트에 thoughtSignature가 포함될 수 있지만 항상 있는 것은 아니에요. 반환되면 최상의 성능을 유지하기 위해 다시 보내야 해요.
스트리밍: 서명이 생성되면 빈 텍스트 파트를 포함하는 최종 청크에 도착할 수 있어요. 텍스트 필드가 비어 있더라도 스트림 파서가 서명을 확인하도록 보장하세요.

이미지 생성 및 편집

gemini-3-pro-image-preview와 gemini-3.1-flash-image-preview의 경우 생각 서명은 대화형 편집에 중요해요. 이미지 수정을 요청하면 모델은 이전 턴의 thoughtSignature에 의존해 원본 이미지의 구성과 논리를 이해해요.

편집: 서명은 응답의 thoughts 다음의 첫 번째 파트(text 또는 inlineData)와 이후의 모든 inlineData 파트에서 보장돼요. 오류를 피하려면 이러한 모든 서명을 반환해야 해요.

코드 예시

다른 모델에서 마이그레이션하기

다른 모델(예: Gemini 2.5)에서 대화 트레이스를 전송하거나 Gemini 3에서 생성되지 않은 사용자 정의 함수 호출을 주입하는 경우 유효한 서명이 없을 거예요.

이러한 특정 시나리오에서 엄격한 검증을 우회하려면 특정 더미 문자열로 필드를 채우세요: "thoughtSignature": "context_engineering_is_the_way_to_go"

도구와 함께하는 구조화된 출력 (Structured Outputs with tools)

Gemini 3 모델은 구조화된 출력을 Google 검색 기반 그라운딩, URL 컨텍스트, 코드 실행, 함수 호출 같은 내장 도구와 결합할 수 있어요.

이미지 생성 (Image generation)

Gemini 3.1 Flash Image와 Gemini 3 Pro Image는 텍스트 프롬프트에서 이미지를 생성하고 편집할 수 있어요. 프롬프트를 "생각"하기 위해 추론을 사용하고, 고품질 이미지를 생성하기 전에 Google 검색 그라운딩을 사용해 날씨 예보나 주식 차트 같은 실시간 데이터를 검색할 수 있어요.

새롭고 개선된 기능:

4K 및 텍스트 렌더링: 최대 2K 및 4K 해상도로 선명하고 읽기 쉬운 텍스트와 다이어그램 생성.
그라운딩 생성: google_search 도구를 사용해 사실을 검증하고 실제 정보를 기반으로 이미지를 생성. Gemini 3.1 Flash Image에서는 Google Image 검색 기반 그라운딩 사용 가능.
대화형 편집: 변경을 요청하기만 하면 되는 다중 턴 이미지 편집(예: "배경을 노을로 바꿔 줘"). 이 워크플로우는 턴 간 시각적 컨텍스트를 보존하기 위해 생각 서명에 의존해요.

종횡비, 편집 워크플로우, 구성 옵션에 대한 자세한 내용은 이미지 생성 가이드를 참고하세요.

예시 응답 (Example Response)

이미지와 함께하는 코드 실행 (Code Execution with images)

Gemini 3 Flash는 비전을 정적인 흘낏 봄이 아니라 적극적인 조사로 취급할 수 있어요. 추론을 코드 실행과 결합하여 모델이 계획을 세우고, 확대, 크롭, 주석 달기 또는 이미지를 단계별로 조작하는 Python 코드를 작성하고 실행해 답변을 시각적으로 근거 지을 수 있어요.

사용 사례 (Use cases):

확대 및 검사: 모델은 세부 사항이 너무 작을 때(예: 먼 계기판이나 일련번호 읽기) 암묵적으로 감지하고 해당 영역을 더 높은 해상도로 크롭하고 다시 검사하는 코드를 작성해요.
시각적 수학 및 플로팅: 모델은 코드를 사용해 다단계 계산을 실행할 수 있어요(예: 영수증의 항목 합산, 추출된 데이터로 Matplotlib 차트 생성).
이미지 주석: 모델은 "이 항목을 어디에 두어야 하나요?" 같은 공간적 질문에 답하기 위해 화살표, 경계 상자 또는 기타 주석을 이미지에 직접 그릴 수 있어요.

시각적 thinking을 활성화하려면 코드 실행을 도구로 구성해 주세요. 모델은 필요할 때 이미지를 조작하기 위해 자동으로 코드를 사용할 거예요.

이미지와 함께하는 코드 실행에 대한 자세한 내용은 코드 실행을 참고하세요.

멀티모달 함수 응답 (Multimodal function responses)

멀티모달 함수 호출을 사용하면 멀티모달 객체를 포함하는 함수 응답을 가질 수 있어, 모델의 함수 호출 기능 활용을 개선할 수 있어요. 표준 함수 호출은 텍스트 기반 함수 응답만 지원해요.

내장 도구와 함수 호출 결합하기

Gemini 3는 동일한 API 호출에서 내장 도구(Google 검색, URL 컨텍스트, 더 보기 같은)와 사용자 정의 함수 호출 도구를 함께 사용할 수 있어 더 복잡한 워크플로우가 가능해요. 도구 조합 페이지에서 자세히 알아보세요.

Gemini 2.5에서 마이그레이션하기 (Migrating from Gemini 2.5)

Gemini 3는 현재까지 가장 강력한 모델 제품군이며 Gemini 2.5에 비해 단계적인 개선을 제공해요. 마이그레이션할 때 다음을 고려하세요.

Thinking: 이전에 Gemini 2.5가 추론하도록 강제하기 위해 복잡한 프롬프트 엔지니어링(chain of thought 같은)을 사용했다면, thinking_level: "high"와 간소화된 프롬프트로 Gemini 3를 시도해 보세요.
Temperature 설정: 기존 코드가 temperature를 명시적으로 설정한다면(특히 결정적 출력을 위해 낮은 값으로), 이 파라미터를 제거하고 Gemini 3 기본값인 1.0을 사용해 복잡한 작업에서 잠재적인 루프 문제나 성능 저하를 피하는 것을 권장해요.
PDF 및 문서 이해: 조밀한 문서 파싱에 특정 동작에 의존했다면, 계속 정확성을 보장하기 위해 새로운 media_resolution_high 설정을 테스트해 보세요.
토큰 소비: Gemini 3 기본값으로 마이그레이션하면 PDF의 토큰 사용량은 증가하지만 비디오의 토큰 사용량은 감소할 수 있어요. 더 높은 기본 해상도 때문에 요청이 이제 컨텍스트 윈도우를 초과하면 미디어 해상도를 명시적으로 낮추는 것을 권장해요.
이미지 분할: 이미지 분할 기능(객체에 대한 픽셀 수준 마스크 반환)은 Gemini 3 Pro 또는 Gemini 3 Flash에서 지원되지 않아요. 기본 이미지 분할이 필요한 워크로드에는 생각을 끈 상태의 Gemini 2.5 Flash를 계속 사용하는 것을 권장해요.
컴퓨터 사용: Gemini 3 Pro와 Gemini 3 Flash는 컴퓨터 사용을 지원해요. 2.5 시리즈와 달리 컴퓨터 사용 도구에 접근하기 위해 별도의 모델을 사용할 필요가 없어요.
도구 지원: Gemini 3 모델에서 내장 도구를 함수 호출과 결합하는 것이 이제 지원돼요. Maps 그라운딩도 이제 Gemini 3 모델에서 지원돼요.
후보 수: Gemini 3 모델은 candidateCount > 1을 지원하지 않아요. 이 파라미터를 1보다 큰 값으로 설정하면 400 오류가 반환돼요.

OpenAI 호환성 (OpenAI compatibility)

OpenAI 호환성 레이어를 사용하는 사용자의 경우, 표준 파라미터(OpenAI의 reasoning_effort)가 Gemini(thinking_level)에 해당하는 값으로 자동 매핑돼요.

프롬프팅 모범 사례 (Prompting best practices)

Gemini 3는 추론 모델이므로 프롬프트 방식도 달라져요.

정확한 지침: 입력 프롬프트를 간결하게 작성하세요. Gemini 3는 직접적이고 명확한 지침에 가장 잘 응답해요. 이전 모델에 사용되던 장황하거나 과도하게 복잡한 프롬프트 엔지니어링 기법을 과도하게 분석할 수 있어요.
출력 장황도: 기본적으로 Gemini 3는 덜 장황하며 직접적이고 효율적인 답변을 제공하는 것을 선호해요. 사용 사례가 더 대화적이거나 "수다스러운" 페르소나를 요구한다면 프롬프트에서 모델을 명시적으로 조종해야 해요(예: "친절하고 말 많은 어시스턴트처럼 설명해 줘").
컨텍스트 관리: 대규모 데이터셋(예: 전체 책, 코드베이스, 긴 영상)으로 작업할 때는 특정 지침이나 질문을 데이터 컨텍스트 뒤의 프롬프트 끝에 배치하세요. "위 정보를 바탕으로..." 같은 문구로 질문을 시작해 모델의 추론을 제공된 데이터에 고정시키세요.

프롬프트 설계 전략에 대해 자세히 알아보려면 프롬프트 엔지니어링 가이드를 참고하세요.

FAQ

Gemini 3의 지식 기준 시점은 언제인가요? Gemini 3 모델은 2025년 1월의 지식 기준 시점을 가져요. 더 최근 정보는 검색 그라운딩 도구를 사용하세요.
컨텍스트 윈도우 한도는 어떻게 되나요? Gemini 3 모델은 1백만 토큰 입력 컨텍스트 윈도우와 최대 64k 토큰 출력을 지원해요.
Gemini 3 무료 등급이 있나요? Gemini 3 Flash gemini-3-flash-preview와 3.1 Flash-Lite gemini-3.1-flash-lite는 Gemini API에 무료 등급이 있어요. Google AI Studio에서 Gemini 3.1 Pro와 3 Flash를 무료로 시도할 수 있지만, Gemini API에는 gemini-3.1-pro-preview용 무료 등급이 없어요.
기존 thinking_budget 코드는 여전히 작동하나요? 네, thinking_budget은 하위 호환성을 위해 여전히 지원되지만, 더 예측 가능한 성능을 위해 thinking_level로 마이그레이션하는 것을 권장해요. 동일한 요청에서 둘 다 사용하지 마세요.
Gemini 3는 Batch API를 지원하나요? 네, Gemini 3는 Batch API를 지원해요.
컨텍스트 캐싱이 지원되나요? 네, Gemini 3에서 컨텍스트 캐싱이 지원돼요.
Gemini 3에서 지원되는 도구는 무엇인가요? Gemini 3는 Google 검색, Google Maps 기반 그라운딩, 파일 검색, 코드 실행, URL 컨텍스트를 지원해요. 또한 자체 사용자 정의 도구를 위한 표준 함수 호출과 내장 도구와의 조합도 지원해요.
gemini-3.1-pro-preview-customtools란 무엇인가요? gemini-3.1-pro-preview를 사용 중이고 모델이 bash 명령을 선호해 사용자 정의 도구를 무시한다면 대신 gemini-3.1-pro-preview-customtools 모델을 시도해 보세요. 자세한 내용은 여기를 참고하세요.

다음 단계 (Next steps)

Gemini 3 Cookbook으로 시작하기
thinking 수준 및 thinking budget에서 thinking 수준으로 마이그레이션하는 방법에 대한 전용 Cookbook 가이드 확인하기

Gemini 3 개발자 가이드