제미나이 API 키 발급, 2026년 9월부터 표준키는 거부돼요 — 공식 문서가 적어 둔 이관 7단계

제미나이 API 키 발급 방법을 찾아보면 대개 클릭 순서로 끝나요. Google AI Studio 에 들어가서 키를 만들고 복사해 코드에 넣으라는 이야기죠.

그런데 2026년 9월에는 그 설명만으로 모자라요. 결론부터 적을게요. 지금 AI Studio 에서 새로 만드는 키는 예전과 다른 종류로 나오고, 예전에 만들어 둔 키는 공식 문서가 이번 달 안에 거부된다고 예고해 둔 상태예요. 원문에는 일자가 없어요. 월만 적혀 있고, 오늘은 2026년 9월 21일이라 이미 그 달 안이에요.

더 눈에 걸리는 건 이 기한이 릴리스 노트에도 지원 종료 문서에도 없다는 점이에요. 두 페이지 본문을 직접 세어 봤는데 관련 어휘가 한 번도 안 나와요. 그래서 이 글은 공식 키 문서와 구글 클라우드 인증 문서 두 곳만 열어서, 발급 클릭 순서가 아니라 내가 쓰는 키의 수명을 정리해요.

키가 두 종류로 갈렸어요

공식 문서는 제미나이 API 인증에 쓰는 키를 두 종류로 구분해요. 표준 키와 인증 키예요.

핵심은 세 번째 줄이에요. 표준 키는 주체를 식별하지 않기 때문에 IAM 으로 호출자가 그 작업을 할 자격이 있는지 검사할 방법이 없어요. 문서가 이번 전환을 보안 개선이라고 설명하는 이유가 여기예요.

인증 키는 구글 클라우드 서비스 계정에 바인딩된 키예요. 클라우드 인증 문서는 이 키가 수명이 긴 액세스 토큰과 비슷하게 동작한다고 적어요. 클라우드 인증 문서가 인증 키를 받는 API 로 예를 든 곳은 AI Platform 과 제미나이 API 예요.

한 가지 단서도 그대로 옮겨 둘게요. 같은 클라우드 문서는 클라우드 안에서 리소스를 만들고 관리하는 API 라면 인증 키를 운영 환경에 쓰지 말라고 주의를 붙여요. 초기 탐색을 빠르게 하는 용도로만 쓰라는 서술이에요. 이 주의가 겨냥한 범위는 원문이 「클라우드 안에서 리소스를 만들고 관리하는 API」로 적어 두었을 뿐, 제미나이 API 가 그 범위에 드는지는 문서가 밝히지 않아요. 같은 인증 키를 클라우드의 다른 서비스로 확장할 생각이라면 그쪽 문서를 먼저 봐야 해요.

기한은 월만 적혀 있고 일자는 없어요

전환 일정은 키 문서에 세 줄로 나와요. 그런데 세 줄의 시제가 서로 달라요.

앞 두 줄은 지난 일이고 마지막 한 줄만 미래예요. 그리고 그 한 줄에 일자가 없어요. 원문은 「On September 2026」 으로 월까지만 적고, 그 앞에 인증 키로 이관하라는 문장을 붙여 둔 게 전부예요.

그래서 이 글은 며칟날부터라는 숫자를 쓰지 않아요. 어딘가에서 구체적인 날짜를 보셨다면 그 숫자는 이 문서에 없는 값이에요. 제가 받은 판본의 최종 수정일은 2026년 9월 16일이었어요.

이 기한은 릴리스 노트에 없어요

일정 공지라면 릴리스 노트나 지원 종료 문서에 있을 것 같은데, 그렇지 않아요. 두 페이지를 받아서 본문 어휘를 직접 세어 봤어요.

모델의 지원 종료는 표로 날짜까지 추적되는데 키 종류의 기한은 키 문서 한 곳에만 있어요. 모델 종료 일정을 따라가는 습관으로 이 변경을 잡아내기 어려운 구조예요. 모델 쪽 목록과 실제 종료일이 어긋나는 문제는 제미나이 모델 지원 종료 확인 쪽에 따로 정리해 두었어요.

한 가지 더 시행 중인 항목이 있어요. 2026년 5월 7일부터 장기간 쓰지 않은 제한 없는 키는 차단돼요. 차단된 키에는 AI Studio 에서 Blocked 태그가 붙고, 새 키를 만들거나 기존의 제한된 키를 써야 해요. 오래 방치한 프로젝트의 키가 어제까지 됐는데 오늘 안 되는 상황이라면 이쪽일 수 있어요.

제한 없는 키는 어디서 태어났을까요

여기가 이 글에서 가장 실용적인 자리일 거예요. 제한 없는 키의 거부는 이미 시행 중인데, 왜 멀쩡히 쓰던 키가 제한 없는 상태였을까요. 클라우드 문서에 답이 있어요.

• 콘솔에서 만들면: API 제한을 최소 한 개 넣어야 키가 만들어져요.
• gcloud CLI 나 REST API 로 만들면: 제한을 직접 지정하지 않는 한 제한 없는 상태로 생성돼요.

즉 사람이 화면에서 만든 키보다 스크립트로 발급한 키가 제한 없는 상태일 확률이 높아요. 그래서 스크립트로 발급한 키가 이 거부에 걸릴 조건을 갖추기 쉬워요.

제한은 두 계열이에요. API 제한은 그 키로 부를 수 있는 API 를 한정하고, 애플리케이션 제한은 그 키를 쓸 수 있는 웹사이트나 IP 또는 앱을 한정해요. 문서는 둘을 함께 걸라고 권해요. 명령줄에서 API 제한을 지정하려면 gcloud 는 --api-target 플래그를 쓰고, REST 로 만들 때는 요청 본문의 restrictions 안에 apiTargets 배열을 넣어요. 그리고 API 제한에 지정할 API 는 그 프로젝트에서 미리 사용 설정돼 있어야 해요.

키 관리 전반의 기본 수칙은 AI API 키 안전하게 관리하는 법 쪽에 정리되어 있어요. 이 글은 그중에서 제미나이 키의 종류와 기한만 다뤄요.

공식 이관 7단계

문서에 적힌 절차는 일곱 단계예요. 순서를 줄이지 않고 그대로 옮길게요.

1. AI Studio 의 API Keys 페이지를 열어요.
2. Key Type 열을 보고 Standard 로 표시된 키를 찾아요.
3. Create API key 를 눌러 새 키를 만들어요. AI Studio 의 새 키는 전부 인증 키로 생성돼요.
4. 새로 만든 인증 키를 복사해요.
5. 코드와 환경변수, 그리고 배포 설정을 새 키로 바꿔요.
6. 애플리케이션이 정상 동작하는지 시험해요.
7. 확인이 끝난 뒤에 옛 키를 삭제하거나 폐기해요.

실무에서 사고가 나는 자리는 여섯째와 일곱째 사이예요. 같은 문서의 유출 대응 절은 새 키가 완전히 살아난 뒤에 옛 키를 지우라고 적어요. 새 키가 어느 배포 환경에서 아직 안 먹고 있는데 옛 키를 먼저 지우면 그 자리에서 멈춰요. 두 단계를 같은 날 붙여서 하지 않는 편이 안전해요.

키가 안 보여서 2단계에서 막히는 경우도 있어요. 기존에 구글 클라우드 계정이 있던 분은 AI Studio 가 기본 프로젝트를 만들어 주지 않아요. 대시보드의 Projects 에서 프로젝트를 가져와야 목록에 나와요. 반대로 완전히 새 사용자라면 약관 동의 후에 기본 프로젝트와 키가 자동으로 만들어져요.

당장 못 바꿀 때: 제한을 걸어 살리는 두 방법

기한 전까지 코드를 못 고치는 상황이라면 제한을 걸어 두는 선택지가 있어요. 문서는 방법을 두 가지로 나눠 적어요.

첫째, 제미나이 API 전용으로 제한하는 방법이에요. 그 키를 제미나이 API 에만 쓰고 있다면 AI Studio 안에서 끝나요. API Keys 페이지에서 Unrestricted 라벨이 붙은 키를 찾아 라벨에 마우스를 올리면 제한 추가 항목이 나오고, 제미나이 API 전용으로 제한하는 선택지를 고른 뒤 확정하면 돼요. 이 조작에는 apikeys.keys.update 권한이 필요하고, API Keys Admin 이나 편집자 역할에 들어 있어요.

둘째, 다른 구글 API 와 같이 쓰는 키라면 클라우드 콘솔에서 제한해요. 여기에 문서가 붙인 주의가 중요해요. 이 방식으로 제한을 적용하면 그 키의 제미나이 API 요청은 실패해요. 제한 목록에서 Generative Language API 를 고르지 말라는 안내와 같은 뜻이에요. 그래서 제미나이용 키는 AI Studio 에서 따로 만들어 쓰라고 이어 적어요.

그리고 하나를 분명히 해 둘게요. 제한을 거는 것이 지금 시행 중인 거부를 피하게 해 주는 건 맞아요. 다만 문서는 제한이 걸린 표준 키가 9월 이후에 어떻게 되는지를 적지 않아요. 「제한이 적용된 표준 키는 계속 동작한다」와 「표준 키의 요청을 거부한다」를 각각 적어 둘 뿐 둘의 관계를 설명하지 않아요. 예고된 거부의 대상이 제한 여부가 아니라 표준 키라는 종류로 적혀 있으니, 제한은 시간을 버는 수단으로만 보고 종류를 바꾸는 쪽을 준비하는 편이 안전해요.

Create API key 가 잠겨 있을 때

권한 부족으로 버튼이 눌리지 않고 안내 문구가 뜨는 경우가 있어요. 문서가 나열한 필요 권한은 다섯 개예요.

뒤 두 개가 이번 전환의 흔적이에요. 키를 만드는 일이 서비스 계정을 만들고 그 계정에 키를 묶는 일로 바뀌었다는 뜻이죠. 예전 표준 키 시절에는 필요하지 않았던 권한이에요.

조직 정책도 한 겹 있어요. 서비스 계정에 키를 바인딩하는 행위는 기본 조직 정책 제약인 constraints/iam.managed.disableServiceAccountApiKeyCreation 으로 막혀 있어요. 그런데 제미나이 API 전용으로만 제한한 인증 키는 기본 허용이라 이 제약을 바꿀 필요가 없어요.

이 두 문장을 이으면 현실적인 결론이 나와요. 제약을 바꾸려면 조직 리소스가 있어야 하고, 조직에 속하지 않은 프로젝트는 지원되지 않아요. 그런데 키 문서는 관리 권한을 못 얻을 때 조직에 속하지 않은 새 프로젝트를 만들라고 안내해요. 그 길이 성립하는 것은 제미나이 전용 인증 키가 기본 허용이기 때문이에요. 같은 우회로로 다른 클라우드 서비스용 인증 키를 만들려고 하면 막혀요.

키를 바꾼 뒤 조용히 어긋나는 자리

이관 자체는 끝났는데 옛 키가 계속 쓰이는 경우가 있어요. 문서에 원인이 적혀 있어요.

환경변수는 GEMINI_API_KEY 와 GOOGLE_API_KEY 둘 다 인식돼요. 그리고 둘 다 설정돼 있으면 GOOGLE_API_KEY 가 우선해요. 새 인증 키를 GEMINI_API_KEY 에 넣었는데 옛 표준 키가 GOOGLE_API_KEY 에 남아 있으면, 코드는 새 키를 쓰는 것처럼 보이는데 실제로는 옛 키로 나가요. 이관을 마친 뒤에 두 변수를 모두 확인해야 하는 이유예요.

확인 방법에도 함정이 하나 있어요. 문서의 주석에 따르면 인증 키로 인증된 요청은 구글 클라우드 서비스 계정 사용량 지표에 기록되지 않아요. 그러니 서비스 계정 지표가 비어 있다고 새 키가 안 먹는다고 판단하면 안 돼요. 판정은 실제 호출의 응답으로 해야 해요. 호출이 실패할 때 무엇부터 보는지는 Gemini AI Studio 오류 해결법 쪽에 정리되어 있어요.

목록 화면의 한도도 알아 둘 만해요. 문서가 적은 제한은 세 가지예요.

그리고 표시 조건이 따로 있어요. AI Studio 는 제한이 없거나 제미나이 API 전용으로 제한된 키만 보여줘요. 다른 제한이 걸린 키는 목록에 아예 안 나와요. 그래서 Key Type 열에 Standard 가 하나도 없다고 이관이 끝난 게 아니에요. 다른 제한이 걸린 옛 표준 키가 남아 있을 수 있고, 그건 클라우드 콘솔의 사용자 인증 정보 페이지에서 봐야 해요.

이 글이 확인하지 못한 것

정직하게 적어 둘게요.

• 거부 일자는 없어요. 원문이 월까지만 적어 두었고, 저는 그 월이 오늘을 포함한다는 것까지만 사실로 쓸 수 있어요.
• 키 문자열 형식이 없어진다는 서술은 두 문서에 없어요. 끊기는 것은 문자열의 모양이 아니라 표준 키라는 종류예요. 문서가 정리한 키 구성요소는 문자열과 키 ID, 표시 이름, 바인딩된 서비스 계정 넷이고, 이 중 서비스 계정 이메일이 인증 키에만 붙어요.
• 제한된 표준 키의 최종 처리는 명시가 없어요. 문서는 제한이 적용된 표준 키가 계속 동작한다고 적고, 9월 줄은 표준 키 전체를 적어요. 두 문장의 관계를 문서가 설명하지 않아요. 안전한 쪽은 종류를 바꾸는 것이에요.
• 무료 한도나 요금, 호출 실패 코드는 이 글의 범위가 아니에요. 여기서 다룬 것은 키의 종류와 수명 하나예요.

실무 판정 순서

정리하면 이래요.

1. AI Studio 의 Key Type 열부터 보세요. Standard 가 보이면 그 키가 이관 대상이에요.
2. 열에 Standard 가 없어도 끝이 아니에요. AI Studio 는 제미나이 전용이거나 제한 없는 키만 보여주니, 다른 제한이 걸린 옛 키는 클라우드 콘솔에서 확인하세요.
3. 새 키를 만들고 코드와 환경변수, 배포 설정을 바꾸세요. AI Studio 의 새 키는 전부 인증 키로 나와요.
4. 두 환경변수를 함께 확인하세요. 둘 다 설정돼 있으면 GOOGLE_API_KEY 가 이겨요.
5. 정상 동작을 확인한 다음에 옛 키를 지우세요. 같은 날 붙여서 하지 마세요.

그리고 하지 말아야 할 것이 하나 있어요. 제한을 걸어 둔 것을 이관을 마친 것으로 세는 일이에요. 제한은 지금 시행 중인 거부를 피하게 해 주지만, 예고된 거부의 기준은 제한 여부가 아니라 키의 종류예요.

이 글의 모든 일정과 권한 목록은 2026년 9월 21일에 공식 키 문서와 구글 클라우드 인증 문서를 직접 받아 확인한 값이에요. 제가 받은 키 문서 판본의 최종 수정일은 2026년 9월 16일이었어요. 문서가 갱신되면 일자가 채워질 수 있으니, 이관 전에 키 문서를 한 번 더 열어 보시는 편이 좋아요.