Gemini 3.5 I/O 2026 신기능 7가지 — API 파라미터 변경과 마이그레이션 실무 가이드

2026.08.17 · 21분 읽기

목차

Gemini 3.5 I/O 2026은 단순 버전업이 아니다. API 파라미터 구조 자체가 바뀐 breaking change가 여럿 포함되어 있다. temperature, top_p, top_k 파라미터가 통째로 제거되었고, thinking_budget은 thinking_level로 대체되었다. 기존 Gemini 2.x 코드를 그대로 실행하면 에러가 발생하는 구간이 존재한다.

이 글에서는 2026년 5월 19일 GA 출시된 Gemini 3.5 Flash(모델 ID: gemini-3.5-flash)의 핵심 변경 사항과 지원 종료 타임라인, 실무 마이그레이션 체크리스트를 다룬다.

Gemini 3.5 Flash 핵심 스펙 — 이전 버전과 무엇이 다른가

Gemini 3.5 Flash는 1M 토큰 입력, 65k 토큰 출력을 지원한다. 에이전트 및 코딩 작업에서 프론티어 성능을 제공하는 모델로 포지셔닝되었으며, 2026년 5월 19일 GA로 출시된 상태다.

가장 큰 변경은 기본 thinking effort가 high에서 medium으로 바뀐 것이다. 이전 Gemini 2.x 시리즈에서 thinking 기능을 사용하던 코드가 있다면, 동일한 프롬프트를 보내도 응답 품질이나 지연 시간이 달라질 수 있다. Google은 medium이 대부분의 작업에서 속도와 비용 효율이 가장 좋다고 Gemini 3.5 신기능 안내 페이지에서 명시하고 있다.

thinking effort 기본값 변경
Gemini 3.5 Flash의 기본 thinking effort는 `medium`이다. 이전 버전에서 `high`가 기본이었던 환경에서 마이그레이션하면 응답 깊이가 달라질 수 있다. 정밀 추론이 필요한 작업에는 명시적으로 `high`를 지정해야 한다.
thinking level은 `minimal`, `low`, `medium`(기본값), `high` 4단계를 제공하는 방식이다. 이전의 `thinking_budget` 수치 기반 제어와 달리 레벨 기반으로 바뀐 셈이다.
항목 Gemini 2.0 Flash Gemini 2.5 Flash Gemini 3.5 Flash
최대 입력 토큰 — — 1M
최대 출력 토큰 — — 65k
thinking 제어 thinking_budget (수치) thinking_budget (수치) thinking_level (4단계)
기본 thinking high high medium
상태 2026-06-01 종료 2026-10-16 종료 예정 GA (현행)

Gemini 3.5 I/O 2026 신기능 정리 — API 파라미터 구조 변화

이번 변경에서 실무 영향이 가장 큰 부분은 API 파라미터 구조다. Gemini 3.x 모델부터 temperature, top_p, top_k 파라미터가 제거(no longer recommended)되었다. 그리고 thinking_budget 파라미터는 thinking_level로 대체되었다.

temperature, top_p, top_k 제거의 의미

기존에 temperature=0.7, top_p=0.9 같은 값을 지정해서 생성 다양성을 제어하던 패턴이 Gemini 3.5 Flash에서는 더 이상 권장되지 않는다. 이 파라미터들을 요청에 포함해도 모델이 무시할 수 있으며, 향후 에러를 반환할 가능성도 배제할 수 없는 상황이다.

대규모 서비스에서 temperature를 세밀하게 조정해 A/B 테스트를 운영하던 환경이라면, 이 변경이 직접적으로 영향을 미치게 된다. 스타트업처럼 빠르게 프로토타이핑하는 환경에서도 마찬가지인데, temperature 튜닝 없이 일관된 출력을 얻으려면 프롬프트 자체의 지시 강도를 조절하는 방향으로 전환해야 하는 것이다.

thinking_budget에서 thinking_level로

thinking_budget이 숫자 기반이었던 반면, thinking_level은 minimal, low, medium, high 4개 문자열 값 중 하나를 선택하는 구조다. 기존 코드에서 thinking_budget: 1024 같은 수치를 넘기던 로직은 thinking_level: "medium" 형태로 변경해야 한다.

파라미터 구조 변화를 코드 수준에서 비교하면 다음과 같다.

# Gemini 2.x 코드 (deprecated 파라미터 포함)
response = model.generate_content(
    prompt,
    generation_config={
        "temperature": 0.7,
        "top_p": 0.9,
        "top_k": 40,
        "thinking_budget": 1024,
    }
)
# Gemini 3.5 Flash 마이그레이션 후
response = model.generate_content(
    prompt,
    generation_config={
        "thinking_level": "medium",
        "max_output_tokens": 8192,
    }
)

제거된 파라미터를 그대로 두면 현재는 무시되지만, 향후 API 버전에서 에러를 반환할 수 있다. 마이그레이션 시 generation_config 객체를 일괄 점검하는 것이 안전하다.

파라미터별 변경 유형을 정리하면 다음과 같다.

파라미터 Gemini 2.x Gemini 3.5 Flash 변경 유형
temperature 0.0~2.0 수치 지정 제거됨 Breaking
top_p 0.0~1.0 수치 지정 제거됨 Breaking
top_k 정수 지정 제거됨 Breaking
thinking_budget 정수 (토큰 수) 제거됨 Breaking
thinking_level 미지원 minimal/low/medium/high 신규
thinking_level 선택 기준
단순 분류·요약 작업에는 `minimal`이나 `low`가 적합하다. 코드 생성·수학 추론처럼 단계적 사고가 필요한 작업에는 `high`를 지정한다. 대부분의 범용 작업에서는 기본값 `medium`이 속도와 품질 균형이 가장 좋다고 공식 문서에 명시되어 있다.
## Gemini 3.5 Flash 지원 기능과 미지원 기능

Gemini 3.5 Flash는 Text, Image, Video, Audio, PDF 입력을 모두 지원한다. 지원 기능과 미지원 기능은 아래 표로 구분된다.

지원 기능 전체 목록

기능 지원 여부 비고
Batch API ✅ 대량 처리용
Caching ✅ 반복 요청 비용 절감
Code execution ✅ 코드 실행 결과 반환
File search ✅ 업로드 파일 내 검색
Flex inference ✅ 유연한 추론 모드
Function calling ✅ 구조 변경됨 (아래 별도 섹션)
Grounding with Google Maps ✅ 위치 기반 정보
Search grounding ✅ 웹 검색 기반 응답
Structured outputs ✅ JSON 스키마 강제
Thinking ✅ 4단계 레벨
URL context ✅ URL 내용 참조

미지원 기능

Computer Use, Image generation, Audio generation, Live API는 Gemini 3.5 Flash에서 지원하지 않는다. Gemini 3.5 Flash 모델 상세 페이지에서 전체 지원 매트릭스를 확인할 수 있다.

Live API가 미지원이라는 점은 실시간 스트리밍 대화 서비스를 구축하려는 경우 주의가 필요한 부분이다. Image generation이 빠진 것도 멀티모달 파이프라인 설계 시 별도 모델을 조합해야 한다는 의미가 된다.

멀티모달 입력은 지원, 멀티모달 출력은 제한적
Gemini 3.5 Flash는 Text, Image, Video, Audio, PDF를 모두 **입력**으로 받을 수 있지만, **출력**에서 이미지나 오디오를 생성하는 기능은 없다. 입력과 출력의 모달리티가 비대칭인 구조이므로, 이미지 생성이 필요한 파이프라인에서는 별도 모델과 조합해야 한다.
## Gemini 2.x 모델 지원 종료 타임라인

Gemini 3.5 I/O 2026 신기능 정리에서 빠질 수 없는 부분이 기존 모델의 지원 종료 일정이다. 이미 종료된 모델과 종료 예정 모델을 구분해서 파악해야 마이그레이션 우선순위를 정할 수 있다.

이미 종료된 모델 (2026-06-01)

2026년 6월 1일부로 다음 4개 모델이 종료되었다:

  • gemini-2.0-flash
  • gemini-2.0-flash-001
  • gemini-2.0-flash-lite
  • gemini-2.0-flash-lite-001

이 모델들을 API 요청에 지정하면 현재 시점에서 에러가 반환된다. 아직 코드를 변경하지 않았다면 즉시 대응이 필요하다.

종료 예정 모델

모델 종료일 마이그레이션 대상
gemini-2.5-flash 2026-10-16 gemini-3.5-flash 또는 gemini-3.1-flash-lite
gemini-3-flash-preview 미정 gemini-3.5-flash (권장)

gemini-2.5-flash는 2026년 10월 16일까지 시간이 있지만, API 파라미터 구조가 3.x에서 크게 바뀌었으므로 일찍 전환하는 편이 낫다. gemini-3-flash-preview는 종료일이 미정이나 프리뷰 모델 특성상 언제든 중단될 수 있으므로 gemini-3.5-flash로의 전환이 권장되는 상태다.

gemini-2.0-flash 계열은 이미 종료
2026년 6월 1일 이후 `gemini-2.0-flash`, `gemini-2.0-flash-001`, `gemini-2.0-flash-lite`, `gemini-2.0-flash-lite-001`은 사용 불가다. 해당 모델 ID가 환경 변수나 설정 파일에 하드코딩되어 있다면 즉시 변경해야 한다. [Gemini API 지원 종료 안내 페이지](https://ai.google.dev/gemini-api/docs/deprecations)에서 전체 타임라인을 확인할 수 있다.
## Gemini 3.5 Flash Function Calling 변경 사항

Function calling 방식도 Gemini 3.x부터 변경되었다. 모든 FunctionResponse에 id와 name을 매칭하여 포함해야 하며, 호출당 정확히 하나의 응답을 반환해야 한다.

기존 방식과의 차이

이전 Gemini 2.x에서는 FunctionResponse에 name만 포함하면 되는 경우가 있었으나, 3.x부터는 id 필드가 필수가 된 것이다. 모델이 function call을 요청할 때 반환하는 id 값을 그대로 FunctionResponse에 담아 보내야 한다.

"호출당 정확히 하나의 응답"이라는 제약도 중요하다. 하나의 function call 요청에 대해 여러 개의 응답을 묶어 보내거나, 응답을 생략하는 패턴은 에러를 유발하게 되는 것이다.

2.x와 3.x의 FunctionResponse 처리 요건을 비교하면 다음과 같다.

항목 Gemini 2.x Gemini 3.x
FunctionResponse id 필드 선택 사항 필수
FunctionResponse name 필드 필수 필수 (id와 매칭)
응답 개수 1개 이상 허용 호출당 정확히 1개
병렬 호출 처리 통합 응답 허용 각각 개별 매칭 필수

대응 방법

Function calling을 사용하는 서비스라면 다음 항목을 점검해야 한다:

  • FunctionResponse 객체에 id 필드가 포함되어 있는지 확인
  • FunctionResponse 객체에 name 필드가 모델 요청의 function name과 일치하는지 확인
  • 하나의 function call에 대해 정확히 하나의 FunctionResponse를 반환하는지 확인
  • 병렬 function call이 있을 경우 각각에 대해 개별 응답을 매칭하는 로직이 있는지 확인

이 변경은 function calling 기반 에이전트 시스템에서 특히 영향이 크다. 에이전트가 복수의 도구를 병렬로 호출하는 패턴이라면, 각 호출의 id를 추적하고 매칭하는 로직을 반드시 검증해야 하는 부분이기도 하다.

LangChain, LlamaIndex 같은 에이전트 프레임워크를 사용하는 경우, 프레임워크 자체의 Gemini 3.x 지원 여부를 먼저 확인해야 한다. 프레임워크가 FunctionResponse 구조를 추상화하고 있다면 프레임워크 버전 업데이트로 해결되는 경우도 있지만, 직접 API를 호출하는 구조라면 id 매칭 로직을 반드시 직접 추가해야 한다.

Gemini 3.5 Flash 마이그레이션 체크리스트

앞서 정리한 변경 사항을 기반으로 마이그레이션 시 확인할 항목을 체크리스트로 정리한다. 대규모 환경이든 소규모 프로젝트든 아래 항목을 순서대로 점검하면 된다.

모델 ID 변경

  • [ ] 환경 변수, 설정 파일, 코드 내 하드코딩된 모델 ID를 gemini-3.5-flash로 변경
  • [ ] gemini-2.0-flash, gemini-2.0-flash-001, gemini-2.0-flash-lite, gemini-2.0-flash-lite-001 → 이미 종료. 즉시 교체
  • [ ] gemini-2.5-flash → 2026-10-16 종료 예정. 조기 전환 권장
  • [ ] gemini-3-flash-preview → gemini-3.5-flash로 전환 권장

API 파라미터 정리

  • [ ] temperature 파라미터 제거 또는 주석 처리
  • [ ] top_p 파라미터 제거 또는 주석 처리
  • [ ] top_k 파라미터 제거 또는 주석 처리
  • [ ] thinking_budget → thinking_level로 변경 (값: minimal, low, medium, high)
  • [ ] 기본 thinking effort가 medium임을 인지하고, 필요 시 명시적으로 high 지정

Function Calling 점검

  • [ ] 모든 FunctionResponse에 id 필드 포함 여부 확인
  • [ ] 모든 FunctionResponse에 name 필드 매칭 확인
  • [ ] 호출당 1개 응답 반환 규칙 준수 확인
  • [ ] 병렬 호출 시 id 추적 로직 검증

출력 토큰 확인

  • [ ] 기존 max_output_tokens 설정이 65k 이하인지 확인 (Gemini 3.5 Flash 최대 출력 65k)
  • [ ] 긴 출력을 기대하는 작업에서 출력 잘림 여부 테스트
마이그레이션 자동화 팁
환경 변수로 모델 ID를 관리하는 구조라면 `GEMINI_MODEL=gemini-3.5-flash` 한 줄 변경으로 모델 전환이 가능하다. 단, API 파라미터 구조 변경(temperature 제거, thinking_level 전환)은 코드 수정이 필요하므로 환경 변수만으로는 해결되지 않는다.
## Gemini 3.5 I/O 2026 신기능 도입 시 주의사항

마이그레이션 체크리스트를 완료한 뒤에도 알아야 할 실무 주의사항이 있다. 특히 공식 문서에 명시되지 않은 부분은 별도로 인지하고 있어야 한다.

공식 문서에 명시되지 않은 부분

Gemini 3.5 Flash의 가격(pricing) 정보가 공식 문서에 명시되어 있지 않다. 비용 추정이 필요한 프로젝트라면 Google Cloud 콘솔의 과금 대시보드를 직접 확인하거나, 소량 테스트 후 실제 과금 내역을 기반으로 추산해야 하는 상황이다.

Gemini 3.5 Pro 출시 일정은 "다음 달"로만 언급되어 정확한 날짜가 공개되지 않은 상태다. Pro 모델을 대기하며 마이그레이션을 미루는 것보다 Flash 기준으로 먼저 전환하고, Pro 출시 시 업그레이드하는 전략이 현실적인 편이다.

한국어 공식 마이그레이션 가이드는 존재하지 않으며, 영문 문서만 제공되는 상태다. Gemini API 변경 이력 페이지에서 버전별 변경 내역을 영문으로 확인할 수 있다.

SDK 버전 호환성도 주의 사항 중 하나다. Google AI Python SDK는 Gemini 3.x의 새로운 파라미터 구조를 최신 버전에서만 완전히 지원한다. thinking_level 파라미터 사용 전에 사용 중인 SDK 버전이 해당 파라미터를 지원하는지 공식 릴리즈 노트에서 확인한 뒤, 필요하면 업데이트 후 진행하는 것이 안전하다.

thinking_level 조정이 비용에 미치는 영향

thinking_level을 high로 설정하면 모델이 내부적으로 더 많은 토큰을 소비하게 된다. medium이 기본값으로 설정된 것 자체가 비용 효율을 고려한 결정이라는 점에서, 무조건 high를 사용하는 것은 비용 측면에서 불리할 수 있다. 작업 유형별로 thinking_level을 분리 적용하는 구조가 효율적이다.

thinking_level: "high" 설정 시에는 응답 지연도 함께 늘어난다는 점을 고려해야 한다. 사용자 대면 서비스라면 첫 토큰 도착 시간(TTFT)이 길어질 수 있으므로, 로딩 인디케이터나 중간 안내 메시지를 별도로 설계하는 방향이 권장된다. 배치 처리나 비동기 파이프라인에서는 이 문제가 상대적으로 덜하지만, 실시간 응답이 핵심인 챗봇이나 코파일럿 서비스에서는 minimal 또는 low를 우선 적용하고 필요한 경우에만 high로 에스컬레이션하는 설계를 검토할 만하다.

Gemini Omni, Gemini Spark 관련

Google I/O 2026에서 Gemini Omni, Gemini Spark도 언급되었으나, ai.google.dev 공식 API 문서에 아직 별도 페이지가 없다. 이 모델들에 대한 API 연동 정보는 공식 문서가 공개될 때까지 확인이 불가능한 상태다.

Vertex AI 통합

cloud.google.com 블로그에서 Vertex AI 통합 관련 내용이 언급되었으나, 구체적인 통합 API 세부사항은 JS 렌더링 방식의 문서 구조로 인해 확인이 어려운 상태다. Vertex AI 환경에서 Gemini 3.5 Flash를 사용하려면 Google Cloud 콘솔의 Model Garden에서 직접 확인하는 것이 정확하다.

Vertex AI 환경은 Google AI Studio와 인증 방식이 다르다. AI Studio는 API 키 기반인 반면, Vertex AI는 서비스 계정 인증이 필요하다. 요금 체계도 두 환경 간에 다를 수 있으므로, 기존 Vertex AI 통합 환경에서 Gemini 3.5 Flash로 전환하는 경우 Cloud 콘솔에서 요금 정책 변경 여부를 반드시 확인해야 한다.

Gemini 3.5 이후 살펴볼 기술 영역

Gemini API 마이그레이션이 완료되면 다음으로 살펴볼 영역이 몇 가지 있다. Gemini 3.5 Flash의 Structured outputs 기능을 활용한 JSON 스키마 강제 출력은 데이터 파이프라인 자동화에서 유용하게 쓰일 수 있다. Search grounding을 결합하면 RAG 없이도 실시간 웹 정보를 반영한 응답을 구성하는 것도 가능해진다. 그리고 gemini-2.5-flash의 2026년 10월 종료 전까지 Gemini 3.5 Flash와의 응답 품질 비교 테스트를 진행해두면, 실제 전환 시점에서 리스크를 줄일 수 있다. Gemini thinking level 설정을 작업 유형별로 세분화하는 것도 Gemini 3.5 I/O 2026 신기능 정리 이후의 실무 최적화 과제가 된다.

관련 글

이 글 공유하기