Google GenAI SDK 3.0 업그레이드: v1 기본값·Node 22·httpx2 점검

SDK 교체 때 API 경로와 전송 계층을 따로 확인하는 과정을 표현한 생성형 개념 이미지. 실제 제품 화면이나 정확한 구성도는 아니다.

Gemini 연동 코드에서 패키지 버전만 올렸는데 모델을 찾지 못하거나, 기존에 잡히던 네트워크 예외가 빠져나올 수 있다. Google GenAI SDK 3.0.0에서는 API 기본 버전과 실행 환경, Python HTTP 전송 계층이 함께 달라지기 때문이다.

GitHub에는 JavaScript와 Python 3.0.0 릴리스가 2026년 11월 6일 공개됐다. JavaScript 변경로그 기준일은 6일, Python 변경로그 제목의 기준일은 5일이다. 여기서 다루는 패키지는 @google/genai와 google-genai다. JavaScript 3.0.0 릴리스 · Python 3.0.0 릴리스

핵심은 “업데이트하면 전부 v1로 바뀐다”가 아니다. 어떤 백엔드에 연결하는지와 이미 명시한 설정을 먼저 확인해야 한다. 아래 예제는 공식 릴리스와 태그 소스를 검토해 작성했으며, SDK 설치나 실제 API 호출로 실행 검증하지 않았다.

Developer API의 기본만 v1로 바뀐다

별도 API 버전을 지정하지 않은 Gemini Developer API 클라이언트는 이제 v1beta 대신 v1을 사용한다. Vertex AI/Enterprise 계열의 기본 v1beta1은 이번 변경으로 바뀌지 않는다.

특히 릴리스는 다음 별칭을 v1beta 전용으로 명시한다.

gemini-flash-latest

gemini-flash-lite-latest

gemini-pro-latest

이 별칭을 유지한 채 SDK 기본값에 의존하면 업그레이드 전후의 요청 조건이 달라진다. 대응은 사용하려는 구체적 모델 버전의 v1 지원을 확인해 선택하거나, 필요한 동안 v1beta를 명시하는 것이다. 이름을 구체적으로 바꿨다는 이유만으로 모든 모델과 기능이 v1에서 지원된다고 가정하면 안 된다. JS 릴리스의 API 버전 변경

Node.js 서버에서 기존 인증 설정을 유지하며 버전을 명시하는 예시는 다음과 같다. 키는 이미 안전한 실행 환경에 설정돼 있다고 가정하며, 이 코드는 생성 요청을 보내지 않는다.

Python에서는 HttpOptions에 지정한다.

이 예제는 Developer API용이다. 환경변수의 백엔드 선택값에 영향받지 않도록 enterprise를 false로 명시했다. 기존 Vertex 프로젝트·리전·인증 설정을 무조건 이 형태로 교체하지 않는다. 브라우저 배포 코드에 키를 넣는 예제로도 사용하면 안 된다. JS 초기화와 키 보안 · Python 클라이언트와 API 선택

환경변수보다 코드의 명시값이 우선한다

코드에 API 버전을 지정하지 않았다면 다음 환경변수로 beta 기본을 선택할 수 있다.

이 환경변수의 beta 값은 백엔드에 따라 Developer API에서는 v1beta, Vertex/Enterprise에서는 v1beta1로 해석된다. JavaScript의 환경변수 방식은 Node.js 실행 환경에 대한 설명이다.

코드의 명시적인 버전 설정이 환경변수보다 우선한다. 따라서 운영 환경에 위 값을 넣었는데 요청이 그대로라면 클라이언트 생성 코드와 공통 래퍼를 먼저 확인한다. JS에서 apiVersion과 httpOptions.apiVersion을 동시에 설정하지 말고 한 곳으로 정리하면 충돌을 줄일 수 있다. JS 버전 선택 코드 · Python 버전 선택 코드

v1beta를 명시하는 조치는 호환성 검토 시간을 확보하는 방법이다. 모델의 장기 제공이나 모든 이전 동작을 보장하는 설정은 아니다.

JavaScript는 Node.js와 결과 타입을 함께 확인한다

@google/genai 3.0.0의 최소 Node.js 버전은 22다. 개발자의 터미널만 확인해서는 부족하다. CI 이미지, 운영 컨테이너, 서버리스 런타임이 각각 어떤 버전을 실행하는지 확인해야 한다. 패키지 설치 단계의 engine 경고를 무시해 지원 범위를 충족한 것으로 처리하지 않는다. v3.0.0 package.json

Interactions의 CodeExecutionResultStep.result도 문자열만 온다고 가정하면 안 된다. 타입이 Array<Content> | string으로 넓어졌으므로 문자열 처리 전에 분기해야 한다. 텍스트 결과의 JSON 자체는 계속 문자열이라는 점과, 이제 다른 형태도 표현한다는 점을 구분한다. JS 3.0.0 결과 타입 변경

프로젝트의 타입 검사와 실제 저장 포맷 검사를 따로 수행하는 편이 좋다. 타입 단언으로 오류만 없애면 로그·DB·후속 도구에서 배열을 잘못 처리하는 문제는 남을 수 있다.

Python은 httpx2 전환을 별도 변경으로 다룬다

Python SDK의 기본 HTTP 클라이언트는 httpx에서 httpx2로 바뀌고, httpx는 기본 설치에서 빠졌다. 기존 httpx를 유지하려면 extra 설치와 선택 설정을 함께 해야 한다. 다음은 별도 검증 환경에서 선택적으로 실행할 전환 예시이며 이 글에서 실행한 명령이 아니다.

extra 설치만으로 기본 전송 계층이 httpx로 돌아간다고 판단하지 않는다. 직접 클라이언트를 주입하거나 자동 선택을 사용하는 코드도 있으므로 실제 선택 경로를 확인한다. Python HTTP 클라이언트 안내

httpx2로 옮길 때는 import 수정뿐 아니라 다음을 검토한다.

Timeout·Limits·사용자 정의 transport와 Auth 객체가 선택한 패키지의 타입인지.

SDK 밖으로 전달되는 전송 예외를 올바른 패키지의 예외 클래스로 잡는지.

동기·비동기 경로가 같은 설정을 사용하고 있는지.

프록시와 사설 CA가 실제 배포 환경에서 동작하는지.

릴리스가 제안하는 import httpx2 as httpx는 일반적인 이행 방법이지 모든 사용자 정의 객체의 호환성 보증은 아니다. Python 3.0.0 전송 계층 마이그레이션

별도 SSL context나 SSL_CERT_FILE·SSL_CERT_DIR 설정이 없는 기본 httpx2 경로에서는 OS 인증서 신뢰 저장소를 사용한다. TLS 실패를 검증 비활성화로 덮지 말고, 신뢰하는 CA와 프록시 설정을 확인한다. 이 설명을 사용자가 주입한 다른 HTTP 클라이언트까지 일반화해서는 안 된다. v3.0.0 SSL 처리 코드

영상 생성은 v1beta 복원과 별개다

이번 릴리스의 GenerateVideos 변경을 놓치면 API 버전만 되돌리며 재시도할 수 있다. Python v3.0.0 소스는 동기·비동기 영상 생성에서 Gemini Developer API 모드를 요청 전에 거부하며, Vertex/Enterprise 분기는 유지한다. 따라서 v1beta 지정만으로 이 SDK 경로의 영상 생성 제한을 해결할 수는 없다. Python 영상 생성 검사

JavaScript에도 Developer API의 GenerateVideos를 비활성화하는 변경이 들어 있다. 이것을 Google의 모든 영상 생성 서비스가 종료됐다는 뜻으로 확대하면 안 된다. 사용 중인 백엔드와 메서드를 확인하고, 다른 서비스로 옮길 경우 인증·과금·리전·데이터 처리 조건을 별도로 검토한다. JS GenerateVideos 변경