Gemini 3 Pro Preview를 찾을 수 없음: 종료 후 오류 빠르게 해결하기 (2026)

gemini-3-pro-preview not found 또는 404 NOT_FOUND가 보인다면 먼저 이 사실부터 확인해야 합니다. Google은 Gemini 3 Pro Preview를 2026년 3월 9일에 종료했습니다. 그래서 예전 모델 ID는 더 이상 유효한 호출 대상이 아닙니다. 직접적인 대체 모델은 gemini-3.1-pro-preview입니다. 이미 모델 이름을 바꿨는데 Vertex AI에서 계속 실패한다면, 다음으로 확인할 것은 API 키가 아니라 location입니다. Google은 현재 gemini-3.1-pro-preview를 Vertex AI에서 global endpoint 전용으로 안내하고 있습니다.

이 글은 세 가지를 분리해서 설명합니다. 종료된 옛 모델, 올바른 대체 모델, 그리고 rename 이후에도 남는 설정 문제입니다. 시간이 없으면 아래 빠른 해결 표와 마이그레이션 체크리스트부터 보세요.

빠른 해결 표

핵심은 이 문제가 이제 모델 라이프사이클 변경이라는 점입니다.

왜 지금 gemini-3-pro-preview를 찾을 수 없나

공식 문서는 분산돼 있지만 흐름은 명확합니다.

현재 models 페이지에는 Gemini 3 Pro Preview가 2026년 3월 9일에 종료됐고 Gemini 3.1 Pro Preview로 마이그레이션하라는 경고가 직접 표시됩니다.

중요한 점은 프로젝트, API 키, AI Studio 기록이 삭제된 것이 아니라는 점입니다. Google은 공식 포럼 답변에서 프로젝트와 저장된 프롬프트는 남아 있지만, 옛 모델을 가리키는 참조가 오류를 낸다고 설명했습니다.

올바른 대체 모델: gemini-3.1-pro-preview vs gemini-2.5-pro

많은 페이지가 단순히 "3.1로 바꾸라"고만 말합니다. 하지만 실제 결정은 조금 더 현실적입니다.

실무적으로는 이렇게 판단하면 됩니다.

• Gemini 3 Pro 계열을 계속 타고 싶다면 gemini-3.1-pro-preview
• 우선 안정적으로 돌아가는 Pro 모델이 필요하다면 gemini-2.5-pro

더 넓은 비교는 Gemini 3.1 Pro vs Gemini 2.5 Pro를 참고하세요.

비슷한 모델 이름을 혼동하지 말 것

가장 흔한 실수는 이름이 비슷한 다른 모델로 잘못 바꾸는 것입니다.

텍스트/코딩/분석 워크플로를 gemini-3-pro-image-preview로 바꾸는 것은 올바른 치환이 아닙니다.

환경별 수정 포인트

Gemini API / SDK

python

model = "gemini-3-pro-preview"

# 직접 후속 모델
model = "gemini-3.1-pro-preview"

# 더 안정적인 fallback
model = "gemini-2.5-pro"

AI Studio

오래된 프롬프트가 갑자기 실패하더라도 프로젝트가 사라졌다고 가정할 필요는 없습니다. 저장된 프롬프트가 옛 모델을 참조하는지 먼저 확인하세요.

Vertex AI

현재 Vertex AI용 Gemini 3 가이드는 gemini-3.1-pro-preview에 대해 global endpoint 사용을 요구합니다.

bash
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_GENAI_USE_VERTEXAI=True

Wrapper와 숨겨진 default

• .env
• wrapper 기본값
• CI/CD secrets
• 저장된 프롬프트
• 테스트 fixture
• 관리자 설정

bash
rg "gemini-3-pro-preview"

실제 프로젝트용 마이그레이션 체크리스트

이 순서를 지키는 이유는 종료된 모델 문제와 rename 이후의 다른 오류를 분리하기 위해서입니다. 먼저 오래된 모델 ID를 제거하고, 그다음 숨은 참조를 없애고, 그다음 Vertex global 설정을 확인해야 합니다. 이 과정을 건너뛰고 곧바로 복잡한 프롬프트나 wrapper 동작을 의심하면, 실제로는 마이그레이션이 덜 끝난 상태인데도 모델 자체가 불안정하다고 오해하기 쉽습니다.

실제 운영에서는 소스 코드만 보는 것으로 충분하지 않을 때가 많습니다. 메인 API 경로는 이미 새 모델로 바뀌었더라도, 예약 실행되는 배치 작업, 내부 노트북, 평가 잡, 관리자 패널의 수동 실행 기능이 여전히 gemini-3-pro-preview를 보내는 경우가 흔합니다. 이런 상태에서는 장애가 간헐적으로 되살아나는 것처럼 보이지만, 사실은 서로 다른 실행 경로가 각자 오래된 설정을 유지하고 있는 것입니다.

바로 쓸 수 있는 마이그레이션 예제

Python

python
from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-3.1-pro-preview",
    contents="TLS handshake를 쉽게 설명해 주세요."
)

print(response.text)

Node.js

javascript
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-3.1-pro-preview",
  contents: "TLS handshake를 쉽게 설명해 주세요."
});

console.log(response.text);

curl

bash
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          { "text": "TLS handshake를 쉽게 설명해 주세요." }
        ]
      }
    ]
  }'

Troubleshooting: 모델명을 바꾼 뒤에도 실패하면 무엇을 볼까

rename 이후에도 실패한다면, 모든 문제를 같은 not found 오류로 보지 마세요. 대부분은 이미 다른 진단 분기로 넘어간 상태입니다.

1. endpoint / location 문제

Vertex AI라면 여전히 1순위입니다. global인지 확인하세요.

2. 옛 참조가 어딘가에 남아 있음

저장 프롬프트, framework default, queue payload, 오래된 템플릿에 흔히 남습니다.

3. 잘못된 모델 계열로 변경함

이미지 모델로 바꾸면 텍스트 Pro 대체가 아닙니다.

4. 이제는 다른 종류의 오류를 보고 있음

• 404 NOT_FOUND: path 또는 surface 문제
• 400 INVALID_ARGUMENT: body 또는 parameter 문제
• 503 UNAVAILABLE: 일시적 과부하

rename 후 오류 종류가 바뀌었다면 오히려 진전일 수 있습니다. 더 넓은 진단은 Gemini API 오류 가이드를 참고하세요.

또 하나 중요한 점은, 라이프사이클 변경이 일어난 뒤에는 예전에 잘 돌아가던 설정을 기준선으로 삼지 말아야 한다는 것입니다. 이런 상황에서는 오래된 샘플 코드보다 현재의 models 페이지, deprecations, Vertex AI 가이드가 더 믿을 수 있는 기준입니다. 그래야 rename 이후 드러난 2차 문제를 종료 문제와 혼동하지 않을 수 있습니다.

그리고 실무에서는 메인 코드만 고치고 끝내면 안 됩니다. 프롬프트 템플릿, 평가 잡, 내부 위키, 관리자 패널의 기본값처럼 코드 밖에 남아 있는 gemini-3-pro-preview 참조가 있으면 며칠 뒤 다른 경로로 같은 장애가 다시 들어옵니다. 이번 마이그레이션의 목표는 한 파일을 고치는 것이 아니라, 시스템 전체에서 옛 모델을 더 이상 선택 가능한 옵션으로 두지 않는 것입니다.

규모가 있는 프로젝트라면, 마이그레이션 기간 동안 허용된 모델 목록을 한 군데에서 강제로 관리하는 것도 효과적입니다. 그러면 오래된 잡이나 내부 도구가 여전히 gemini-3-pro-preview를 보내더라도, 외부 API에서 모호한 오류로 터지기 전에 내부에서 먼저 차단하고 위치를 추적할 수 있습니다. 이런 종류의 종료 이슈에서는 코드 수정 자체보다도, 남아 있는 경로를 빠르게 드러내는 운영 장치가 더 큰 차이를 만듭니다.

shutdown 문제가 실제로 끝났는지 빠르게 확인하려면, 같은 surface를 향해 최소 요청 하나만 먼저 보내 보는 것이 좋습니다. 그 간단한 테스트가 gemini-3.1-pro-preview나 gemini-2.5-pro에서 성공하는데 실제 애플리케이션만 계속 실패한다면, 원인은 새 모델 부재가 아니라 wrapper, endpoint, 저장된 프롬프트, 또는 남아 있는 환경 설정일 가능성이 훨씬 큽니다.

3.1 Pro Preview로 바로 올려야 하나

Gemini 3 Pro Preview를 쓰던 이유가 최신 Gemini 3 Pro 경로를 유지하려는 것이었다면 gemini-3.1-pro-preview가 맞는 선택입니다. 하지만 모든 팀이 즉시 이를 default로 삼아야 하는 것은 아닙니다.

안정성이 더 중요하다면 gemini-2.5-pro가 더 보수적인 선택입니다. 3.1로 올린 뒤 timeout이나 overload가 걱정되면 추가로 Gemini 3.1 Pro timeout fix도 참고하세요.

여기서 기억해야 할 점은, 공식 후속 모델과 운영상 가장 안전한 선택이 항상 같지는 않다는 것입니다. Google은 3.1 Preview를 직접 대체 모델로 제시하지만, 팀의 배포 리스크나 변경 허용 범위에 따라서는 2.5 Pro가 더 현실적인 선택일 수 있습니다. 이 글은 그 차이를 숨기지 않고, 왜 두 경로가 모두 유효한지 설명하는 데 목적이 있습니다.

현장에서는 이 결정을 두 단계로 나누는 편이 더 안전합니다. 먼저 gemini-2.5-pro 같은 안정 경로로 장애를 멈추고, 그다음 gemini-3.1-pro-preview를 실제 트래픽과 프롬프트에서 비교 평가해 default 승격 여부를 결정합니다. 이렇게 하면 긴급 복구와 새 preview 채택을 한 번에 묶지 않게 되어 운영 부담이 줄어듭니다.

FAQ

Gemini 3 Pro Preview는 완전히 종료됐나요?
네. 공식 deprecations 페이지는 2026년 3월 9일 종료라고 명시합니다.

gemini-3.1-pro-preview가 공식 대체 모델인가요?
네. deprecations와 release notes 모두 그렇게 안내합니다.

AI Studio 프로젝트나 프롬프트가 삭제됐나요?
아니요. 프로젝트와 프롬프트는 남고, 옛 모델을 가리키는 참조가 오류를 냅니다.

Vertex AI가 rename 후에도 실패하는 이유는 뭔가요?
가장 흔한 원인은 location입니다. 현재 문서는 global을 요구합니다.

gemini-3-pro-image-preview로 바꾸면 되나요?
이미지 워크플로가 아니라면 안 됩니다.

preview를 피하고 싶다면요?
gemini-2.5-pro를 더 안정적인 fallback으로 선택하세요.

결론

gemini-3-pro-preview not found는 더 이상 애매한 문제가 아닙니다. 2026년 3월 9일 이후 이전 모델은 종료 상태입니다. Gemini 3 Pro의 후속 경로를 유지하려면 gemini-3.1-pro-preview, 안정성을 우선하려면 gemini-2.5-pro를 선택하세요. 그리고 Vertex AI가 rename 후에도 실패하면 가장 먼저 GOOGLE_CLOUD_LOCATION=global을 확인해야 합니다.