유튜브 API 키 발급방법 — 하루 검색 100회, 요금은 청구되지 않습니다

한 줄 요약

유튜브 API 키는 무료로 받고, 쓰다가 돈이 청구되는 일은 없습니다. YouTube Data API 공식 문서에는 가격표 자체가 없습니다. 접근을 조절하는 수단은 요금이 아니라 할당량(quota) 하나뿐이고, 할당량을 다 쓰면 quotaExceeded 403 오류로 막힌 뒤 태평양 시간 자정에 초기화됩니다.

구글 클라우드 콘솔에서 만든다고 해서 카드가 긁히지 않습니다. 이 점이 다른 구글 API(종량 과금)와 근본적으로 다르고, 가장 많이 오해받는 부분입니다.

발급 절차

4단계이고, 세 번째까지만 하면 키는 손에 들어옵니다. 네 번째(제한 걸기)는 건너뛰어도 동작하지만 구글이 "프로덕션 전에 하라"고 명시한 단계입니다.

2단계를 빠뜨리는 사람이 가장 많습니다. 키는 정상적으로 발급되기 때문에 다 됐다고 생각하고 호출했다가 403을 맞습니다. 이때 오류 이름이 accessNotConfigured 이고, 공식 설명은 "프로젝트가 이 API에 접근하도록 구성되지 않았습니다. 콘솔에서 API를 활성화하십시오" 입니다. 키가 틀린 게 아니라 스위치를 안 켠 것입니다.

API 키로 되는 것, OAuth가 필요한 것

여기서 갈리는 기준은 공식 문서에 한 줄로 적혀 있습니다 — 비공개 사용자 데이터(private user data)를 요청하는가. 아니면 API 키, 맞으면 OAuth 2.0입니다.

순위 추적, 경쟁 채널 분석, 영상 목록 수집처럼 남의 공개 데이터를 읽는 작업은 전부 API 키로 됩니다. OAuth를 붙이느라 고생할 필요가 없습니다. 반대로 mine=true 를 붙이는 순간 authorizationRequired 401이 납니다 — 공식 설명이 "요청이 mine 매개변수를 쓰는데 제대로 승인되지 않았습니다" 입니다.

★ 할당량 — 2026년 6월에 바뀌었습니다

이 글에서 가장 값어치 있는 부분입니다. "유튜브 API 할당량"으로 검색하면 "search.list는 100 units" 라는 설명이 거의 전부인데, 2026년 6월 1일부로 맞지 않습니다. 구글이 세분화된 할당량 체계로 전환했습니다.

무엇이 달라졌는지가 핵심입니다. 예전에는 검색 한 번에 공용 10,000에서 100씩 깎여서, 검색을 100번 하면 그날 다른 호출을 아무것도 못 했습니다. 지금은 분리되어 있어서 검색 100회를 다 써도 나머지 10,000 units가 그대로 남습니다. 하루 검색 100회라는 숫자는 우연히 같지만 동작이 완전히 다릅니다.

업로드 비용도 바뀌었습니다. 2025년 12월 4일에 영상 업로드가 약 1,600 units에서 약 100 units로 낮아졌고, 지금은 아예 전용 버킷(하루 100회)으로 빠졌습니다. "업로드 한 번에 1600 units라 하루 6개가 한계"라고 적힌 글은 전부 옛날 기준입니다.

공용 버킷에서 쓰는 주요 메서드 비용입니다.

놓치기 쉬운 규칙 세 가지입니다.

• 잘못된 요청도 최소 1 units를 씁니다. 오타 난 호출을 반복하면 그만큼 닳습니다.
• 페이지네이션은 페이지마다 따로 셉니다. 결과를 여러 페이지 받아오면 추가 페이지 요청마다 비용이 붙습니다. 자막 목록을 끝까지 훑는 식의 코드가 여기서 터집니다.
• 초기화는 태평양 시간 자정 — 한국시간으로 오후 4시 또는 5시입니다(서머타임에 따라 다름). 자정에 풀린다고 생각하고 기다리면 하루를 버립니다.

사용량은 Google API 콘솔의 Quotas 페이지에서 봅니다. 메서드별 비용은 공식 할당량 계산기 ↗에 표로 있습니다.

할당량을 늘리려면 — 돈이 아니라 감사입니다

기본 할당량보다 더 필요하면 결제가 아니라 규정 준수 감사(Compliance Audit)를 먼저 통과해야 합니다. 공식 문구가 "추가 할당량을 요청하려면 먼저 감사를 완료해 프로젝트가 YouTube API 서비스 약관을 준수함을 보여야 한다" 입니다.

최근 12개월 안에 감사를 통과했다면 같은 양식을 다시 내서 추가 증량을 요청합니다. 소요 기간은 공식 문서에 숫자로 나와 있지 않습니다. "가능한 한 빨리 연락하겠다"는 표현이 전부라, 다른 글에 적힌 "2~4주"는 근거 없는 추정입니다.

OAuth를 붙일 때 걸리는 것들

공개 데이터만 읽을 거면 이 절은 건너뛰셔도 됩니다. 업로드나 내 채널 관리를 하려면 세 가지를 미리 알고 시작하는 편이 낫습니다.

① 콘솔 메뉴가 바뀌었습니다

예전 블로그의 API 및 서비스 → OAuth 동의 화면 경로 스크린샷은 이제 맞지 않습니다. 현재는 Google Auth Platform 아래로 옮겨졌고 네 페이지로 쪼개졌습니다 — Branding(앱 이름·지원 이메일), Audience(내부/외부·테스트 사용자), Data Access(범위 추가), Clients(클라이언트 ID 생성). OAuth 클라이언트는 Clients → Create client 에서 만듭니다.

② 테스트 모드는 7일마다 풀립니다

이걸 모르면 "왜 자꾸 로그인이 풀리지" 하면서 몇 주를 헤맵니다. 공식 문서가 명확합니다 — 외부 사용자 유형에 게시 상태가 '테스트'인 프로젝트는 리프레시 토큰이 7일 후 만료됩니다. 이름·이메일·프로필만 요청하는 경우는 예외지만 유튜브 범위는 여기 해당하지 않습니다. 계속 돌려야 하는 자동화라면 앱을 프로덕션으로 게시해야 합니다.

테스트 모드에는 테스트 사용자 100명 제한도 있습니다. 리프레시 토큰이 죽는 다른 사유도 공식 목록에 있습니다 — 사용자가 액세스를 취소했거나, 6개월간 사용하지 않았거나, 계정당 허용 토큰 수를 넘긴 경우입니다.

③ 개인용이면 인증 심사는 안 받아도 됩니다

사용자 100명 미만의 개인용 앱은 인증 심사 대상이 아닙니다. 개발·테스트·스테이징 단계의 앱도 마찬가지입니다. 대신 "확인되지 않은 앱" 경고 화면을 매번 지나가야 하고, 테스트 모드면 위의 7일 문제가 따라옵니다. 공개 앱으로 배포하면서 사용자 데이터에 접근한다면 그때 심사를 받습니다.

오류가 나면 — 403의 이름부터 봅니다

유튜브 API는 대부분의 문제가 403으로 나옵니다. 그래서 HTTP 코드만 보면 구분이 안 됩니다. 응답 본문의 오류 이름(reason)을 보면 원인이 한 번에 갈립니다.

accessNotConfigured 와 keyInvalid 를 구분하는 게 가장 중요합니다. 둘 다 403이지만 전자는 키는 맞는데 API를 안 켠 것이고 후자는 키가 틀린 것입니다. 키를 다시 발급받으며 시간을 버리는 경우가 대부분 전자입니다.

참고로 accessNotConfigured 에는 다른 원인도 두 개 있습니다 — 프로젝트가 악용으로 차단됐거나 삭제 예정으로 표시된 경우입니다. API를 분명히 켰는데도 같은 오류가 계속 나면 프로젝트 상태를 확인해 보세요.

키 제한 — 하나만 고를 수 있습니다

구글은 클라이언트 제한과 API 제한을 둘 다 걸라고 권장하고, 키 생성 절차에도 "최소 하나의 제한을 추가하라"가 들어 있습니다.

함정이 하나 있습니다 — 클라이언트 제한은 키 하나당 한 종류만 걸 수 있습니다. 웹과 안드로이드를 같이 쓰려면 키를 따로 만들어야 합니다. 그리고 API 제한을 안 걸면 그 키가 API 키를 받는 다른 모든 구글 API에 열려 있습니다.

서버에서 호출할 때는 키를 URL 쿼리 파라미터로 넘기지 마세요. 공식 권장이 명시적입니다 — URL에 키가 들어가면 URL 스캔으로 탈취될 수 있으니 x-goog-api-key 헤더나 클라이언트 라이브러리를 쓰라는 것입니다.

프론트엔드에 키를 넣으면 안 되는 이유

API 키는 "누가" 호출했는지 증명하지 못합니다. 공식 문서의 표현으로는 표준 API 키는 주체(principal)를 인증하지 않으며, 주체가 없으니 IAM으로 권한을 확인할 수도 없습니다. 키는 프로젝트 식별과 할당량 집계용일 뿐입니다.

그래서 탈취당하면 남이 내 할당량을 태웁니다. 유튜브 API는 과금이 없으니 요금 폭탄은 안 맞지만, 대신 내 서비스가 하루 종일 403으로 죽습니다. 이쪽이 더 골치 아플 수도 있습니다.

공식 권장 구조는 백엔드 프록시입니다 — "클라이언트는 서버로 요청을 보내고, 서버가 자격증명을 붙여 요청을 발행해야 한다"가 원문입니다. 프론트는 내 서버를 부르고, 서버가 키를 붙여 유튜브를 부른 뒤 결과만 돌려줍니다.

정말 브라우저에서 직접 호출해야 한다면 차선책은 HTTP 리퍼러 제한 + API 제한 조합입니다. 다만 리퍼러 헤더는 위조가 가능해서, 공식 문서도 이걸 완전한 보호라고 하지 않고 "유출된 키의 피해를 줄이는 것" 이라고만 표현합니다.

나머지 관리 원칙은 제미나이 쪽과 같습니다 — 깃에 올리지 않기, 안 쓰는 키는 삭제하기, 팀원마다 다른 키 쓰기, 주기적으로 교체하기. 교체할 때 새 키를 먼저 적용하고 나서 옛 키를 지우는 순서도 같습니다.

이 글을 쓰면서

처음에는 "할당량 10,000이 왜 빨리 닳는가"를 주제로 잡고 있었습니다. 검색 한 번에 100 units가 깎이니 100번이면 끝난다는, 흔히 아는 그 이야기입니다. 공식 문서를 열어보니 그 전제가 몇 달 전에 사라져 있었습니다.

2026년 6월 1일부로 search.list 와 videos.insert 가 각자의 버킷으로 빠졌습니다. 검색을 아무리 써도 다른 호출용 10,000은 멀쩡합니다. 제약의 성격이 "총량을 나눠 쓰는 것"에서 "항목마다 따로 정해진 것"으로 바뀐 셈인데, 한국어로 이걸 설명하는 글을 찾지 못했습니다.

업로드 비용도 마찬가지였습니다. 1,600 units라는 숫자가 워낙 유명해서 "하루 6개가 한계"라는 계산이 여기저기 있는데, 2025년 12월에 약 100으로 내려갔고 지금은 아예 하루 100회짜리 별도 버킷입니다. 재미있는 건 구글 자신의 페이지 요약 위젯에도 1600이라는 옛 숫자가 아직 남아 있다는 점입니다. 본문과 요약이 서로 다른 말을 하고 있어서, 어느 쪽을 봤느냐로 글이 갈립니다.

그래서 이 글은 발급 절차를 표 하나로 끝내고 할당량에 자리를 크게 줬습니다. 키를 받는 건 5분이면 되지만, 틀린 할당량 계산으로 설계하면 며칠을 버리기 때문입니다.

같은 구글이지만 제미나이 API는 정반대입니다 — 제미나이 쪽은 한도를 아예 공개하지 않고 종량 과금이 붙습니다. 두 개를 같이 쓸 계획이라면 그 차이를 먼저 보시는 게 좋습니다.