유튜브 API 키 (YouTube Data API v3) 생성 및 첫 API 호출 방법

YouTube API 키는 코드가 공개 YouTube 데이터(동영상 세부정보, 채널 통계, 검색 결과, 재생목록 콘텐츠)를 읽을 수 있도록 하는 자격 증명입니다. Google 문서에서는 이를 명확하게 설명합니다. "OAuth 2.0 토큰을 제공하지 않는 요청은 API 키를 전송해야 합니다. 이 키는 프로젝트를 식별하고 API 액세스, 할당량, 보고서를 제공합니다." 키가 없으면 데이터도 없습니다.

이 가이드는 빈 Google Cloud 프로젝트에서 약 15분 만에 작동하는 요청을 만드는 방법을 안내합니다. YouTube Data API v3를 활성화하고, 키를 생성하고, 보안을 강화하고, curl 및 Python에서 API를 호출한 다음, Apidog에 키를 저장하고 호출을 반복 가능한 테스트로 저장합니다. 먼저 전반적인 내용을 알고 싶다면, 저희 YouTube Data API 개요에서 API가 제공하는 기능을 다루며, 이 게시물은 실습 부분입니다.

버튼

시작하기 전에 필요한 것

Google 계정. Cloud Console을 열고 프로젝트를 만드는 데 충분합니다.
코드 샘플용 `requests` 패키지가 포함된 curl (macOS 및 대부분의 Linux 배포판에 기본 포함) 및 Python 3.
키를 비밀로 저장하고 요청을 테스트로 저장하려면 Apidog가 필요합니다. 무료 플랜으로 여기의 모든 것을 사용할 수 있습니다.

1단계: Google Cloud 프로젝트 생성

Google Cloud Console을 열고 로그인합니다. 페이지 상단의 프로젝트 선택기를 사용하여 youtube-integration과 같은 새 프로젝트를 생성합니다. 나중에 보게 될 모든 API 키, 할당량 버킷 및 사용량 보고서는 이 프로젝트에 연결되므로, 관련 없는 도구 간에 키를 공유하는 대신 앱당 하나의 프로젝트를 유지하십시오. 앱에 이미 프로젝트가 있다면 해당 프로젝트를 사용하십시오.

2단계: YouTube Data API v3 활성화

새 프로젝트에서는 API가 기본적으로 비활성화되어 있습니다. 콘솔에서 API 및 서비스로 이동하여 API 라이브러리를 열고 "YouTube Data API v3"를 검색하여 활성화합니다. Google의 시작하기 가이드에서는 다른 방향에서 동일한 확인 방법을 설명합니다. 활성화된 API 페이지를 방문하여 API가 목록에 없으면 활성화합니다.

이 단계를 건너뛰면 첫 번째 요청이 프로젝트에서 API가 사용되지 않았거나 비활성화되었다는 403 오류와 함께 실패합니다. 이는 새 키가 "작동하지 않는" 가장 흔한 이유입니다.

3단계: API 키 생성

API 및 서비스로 이동한 다음 자격 증명을 클릭합니다. 자격 증명 생성을 클릭하고 API 키를 선택합니다. 콘솔은 즉시 키를 생성하여 대화 상자에 표시합니다. 안전한 곳에 복사해 두십시오.

키를 비밀번호처럼 다루십시오. Git 저장소, Slack 스레드 또는 클라이언트 측 JavaScript 번들에 붙여넣지 마십시오. 이미 커밋에 노출되었다면, 노출된 API 키를 찾고 수정하는 방법에 대한 저희 가이드에서 정리 방법을 다룹니다.

4단계: 키 제한

Google의 문서에서도 "제한되지 않은 API 키는 안전하지 않습니다."라고 명시하고 있습니다. 생성 직후 키 제한을 클릭하십시오. Cloud API 키 가이드에 설명된 두 가지 독립적인 제어 기능을 얻을 수 있습니다.

애플리케이션 제한은 누가 키를 제시할 수 있는지 결정합니다. 웹사이트(제한적인 와일드카드 지원이 있는 HTTP 리퍼러), IP 주소(IPv4, IPv6 또는 CIDR 범위), Android 앱(패키지 이름 및 SHA-1 인증서 지문) 또는 iOS 앱(번들 ID) 중 하나를 선택하십시오. 백엔드 서비스는 IP 주소를 사용해야 합니다. 브라우저 전용 위젯은 리퍼러를 사용해야 합니다.
API 제한은 키가 호출할 수 있는 API를 결정합니다. "키 제한"을 선택하고 YouTube Data API v3만 선택하십시오. 키가 유출되더라도 공격자는 YouTube 할당량만 얻고 다른 것은 얻지 못합니다.

변경 사항이 적용될 때까지 몇 분 정도 기다린 후 테스트하십시오. 동일한 가이드에서 권장하는 두 가지 습관: 손상된 키로 인한 피해를 제한하기 위해 주기적으로 키를 교체하고, 모든 호출자가 새 키로 전환되면 이전 키를 삭제하십시오. 다음 단계에 대한 한 가지 주의사항: 서버의 IP로 제한하는 경우, 노트북에서 curl을 실행하면 차단되므로 허용된 호스트에서 테스트하거나 별도의 개발 키를 생성하십시오.

5단계: curl 및 Python으로 첫 번째 요청 수행

모든 엔드포인트는 https://www.googleapis.com/youtube/v3/에 연결됩니다. 키를 Google 예시처럼 key 쿼리 매개변수로 전달하거나, URL 및 액세스 로그에 표시되지 않도록 x-goog-api-key 헤더로 전달할 수 있습니다. 두 방법 모두 실제 API에서 작동합니다.

가장 저렴하고 유용한 호출인 videos.list로 시작하십시오. 이 호출은 하나 이상의 동영상 ID에 대한 세부 정보를 반환하며 1 할당량 단위를 사용합니다. 아래 ID는 Google이 문서에서 사용하는 ID입니다.

export YOUTUBE_API_KEY="AIza...your-key..."

curl -s "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=7lCDEYXw3mM" \
  -H "x-goog-api-key: $YOUTUBE_API_KEY"

잘라낸 응답은 다음과 같습니다.

{
  "kind": "youtube#videoListResponse",
  "items": [
    {
      "id": "7lCDEYXw3mM",
      "snippet": { "title": "...", "channelTitle": "...", "publishedAt": "..." },
      "statistics": { "viewCount": "...", "likeCount": "..." }
    }
  ]
}

part 매개변수는 필수이며 반환되는 섹션을 제어합니다. snippet, statistics, contentDetails, status는 가장 많이 사용될 것입니다.

이제 대부분의 사람들이 찾는 호출인 검색입니다. requests를 사용하는 Python 코드입니다.

import os
import requests

API_KEY = os.environ["YOUTUBE_API_KEY"]
BASE = "https://www.googleapis.com/youtube/v3"

resp = requests.get(
    f"{BASE}/search",
    params={"part": "snippet", "q": "api testing", "type": "video", "maxResults": 10},
    headers={"x-goog-api-key": API_KEY},
    timeout=10,
)

if resp.status_code != 200:
    err = resp.json()["error"]
    raise SystemExit(f"{err['code']} {err['errors'][0]['reason']}: {err['message']}")

for item in resp.json()["items"]:
    print(item["id"]["videoId"], item["snippet"]["title"])

search.list의 경우, part는 snippet이어야 하며, maxResults는 기본적으로 5이고 0에서 50까지 허용됩니다. type은 기본적으로 video,channel,playlist이므로 동영상만 원하면 video로 설정하십시오. 검색 결과는 최상위 수준이 아닌 id 내부에 videoId를 포함합니다. 그래서 위 루프가 item["id"]["videoId"]를 읽는 이유입니다.

6단계: Apidog에 키 저장 및 요청 실행

셸 변수는 하나의 스크립트에는 작동하지만 팀에는 작동하지 않으며, 저장되고 다시 실행 가능한 검사를 제공하지 않습니다. 다음은 클라우드에 키를 저장하지 않고 Apidog에서 동일한 요청을 수행하는 방법입니다.

환경 생성. YouTube라는 환경을 생성하고, base_url을 https://www.googleapis.com/youtube/v3로 설정하고, youtube_api_key 변수를 추가합니다. 키의 경우, 공유 값은 자리 표시자로 두고 실제 키를 로컬 값 필드에 붙여넣습니다. 로컬 값은 클라이언트 캐시에 남아 팀원들과 동기화되지 않습니다. 전체 설정은 Apidog의 환경 및 비밀 변수 가이드에 있습니다.
요청 빌드. 새 요청에서 GET {{base_url}}/videos, 쿼리 매개변수 part=snippet,statistics 및 id=7lCDEYXw3mM, 그리고 {{youtube_api_key}}로 설정된 x-goog-api-key 헤더를 추가합니다. YouTube 환경을 선택하고 전송합니다. curl 호출과 동일한 JSON을 볼 수 있을 것입니다.
테스트로 전환. 요청의 후처리기에 어설션(assertions)을 추가합니다. 상태는 200이어야 하고, $.items[0].id는 7lCDEYXw3mM이어야 합니다. 요청을 저장하고 테스트 시나리오에 추가합니다. 이제 이 검사는 필요에 따라, 일정에 따라, 또는 Apidog CLI를 통해 CI에서 실행됩니다. Apidog CLI에서는 키를 저장하는 대신 런타임에 --env-var "youtube_api_key=$YOUTUBE_API_KEY"를 사용하여 키를 주입합니다.

키가 교체되거나 제한이 변경될 때 그 효과를 볼 수 있습니다. 하나의 시나리오를 다시 실행하면 모든 YouTube 호출이 여전히 작동하는지 몇 초 안에 알 수 있습니다. 함께 진행하려면 Apidog를 다운로드하십시오. 최대 4명으로 구성된 팀은 무료입니다.

할당량 및 제한

YouTube Data API는 달러로 청구하지 않고 할당량 단위로 청구하며, 이 수치는 Google의 할당량 계산기 페이지에서 가져옵니다. API를 활성화하는 모든 프로젝트는 다음 기본 할당량을 얻습니다.

버킷	일일 기본값	호출당 비용
`search.list`	100회 호출	1 단위 (자체 버킷)
`videos.insert`	100회 호출	1 단위 (자체 버킷)
기타 모든 엔드포인트 결합	10,000 단위	다양함, 아래 참조

공유 10,000단위 풀 내에서 videos.list, channels.list, playlistItems.list, commentThreads.list와 같은 목록 메소드는 각각 1단위를 사용합니다. 쓰기 작업은 더 많은 비용이 듭니다. videos.update 및 videos.delete는 50단위이고, captions.insert는 400단위입니다. 동일 페이지의 네 가지 규칙은 이를 중심으로 설계해야 하는 방법을 제시합니다.

할당량은 태평양 표준시 자정에 재설정됩니다.
잘못된 요청을 포함하여 모든 요청은 최소 1단위를 사용합니다. 잘못된 호출을 재시도하는 루프는 할당량을 낭비하게 됩니다.
페이지가 매겨진 결과의 각 추가 페이지는 첫 페이지와 동일한 비용이 듭니다.
기본 할당량은 "변경될 수 있습니다". 용량을 계획하기 전에 튜토리얼이 아닌 페이지를 확인하십시오.

이전 가이드에서는 10,000단위 풀에서 검색에 100단위를 할당했습니다. 현재 페이지에서는 search.list를 자체 버킷에 두므로, 하루에 100회 검색 한도는 여전히 유지되지만 검색이 다른 호출의 할당량을 소모하지 않습니다.

그것으로 충분하지 않다면, 할당량 및 규정 준수 감사 페이지에서 YouTube API 서비스 감사 및 할당량 연장 양식으로 안내합니다. 제출하기 전에 응답을 캐시하고, 필요한 part 값만 요청하며, ID를 하나의 videos.list 호출(id 매개변수는 쉼표로 구분된 목록을 받음)로 묶으십시오. 사용량은 Cloud Console의 할당량 페이지에 표시됩니다.

일반적인 오류 및 해결 방법

Google의 오류 참조는 API 자체의 사유 코드를 나열합니다. 아래 처음 두 줄은 잘못된 키 또는 키 없이 실제 API에 요청을 보낼 때 발생합니다.

HTTP	사유	표시될 메시지	해결책
400	`badRequest` (`API_KEY_INVALID`)	“API 키가 유효하지 않습니다. 유효한 API 키를 전달하십시오.”	오타, 삭제된 키 또는 YouTube Data API v3를 제외하는 API 제한. 키를 다시 생성하거나 편집하십시오.
403	`forbidden`	“메서드가 등록되지 않은 호출자를 허용하지 않습니다…”	키가 전송되지 않았습니다. `key` 매개변수 또는 `x-goog-api-key` 헤더를 추가하십시오.
403	`quotaExceeded`	“할당량을 초과하여 요청을 완료할 수 없습니다.”	태평양 표준시 자정 재설정까지 기다리거나, 중복 호출을 줄이거나, 연장을 요청하십시오.
400	`missingRequiredParameter`	“요청에 필수 매개변수가 누락되었습니다.”	거의 항상 `part`가 누락된 경우입니다.
401	`authorizationRequired`	“요청이 mine 매개변수를 사용하지만 제대로 인증되지 않았습니다.”	이 호출에는 키가 아닌 OAuth 2.0 토큰이 필요합니다. FAQ를 참조하십시오.

실제 사용에서 한 가지 더: 애플리케이션 제한이 호출자와 일치하지 않으면 차단된 리퍼러 또는 IP를 명시하는 403 오류가 발생합니다. 제한을 수정하거나 허용된 호스트에서 호출하십시오. 그리고 오래된 포럼 스레드에서는 유효하지 않은 키 오류를 keyInvalid라고 부르지만, 실제 API는 API_KEY_INVALID 세부 정보와 함께 badRequest를 반환하므로, 이전 사유 문자열이 아닌 메시지나 세부 정보에 일치시키십시오.

FAQ

YouTube API 키는 무료인가요?

예. 키 생성에는 비용이 들지 않으며, 문서에는 API 비용이 돈이 아닌 할당량 단위로 책정되어 있습니다. 위에서 언급된 기본 할당량은 요청 없이도 얻을 수 있는 양입니다.

API 키 대신 OAuth가 필요한 경우는 언제인가요?

API 키는 프로젝트를 식별하고 공개 데이터를 잠금 해제합니다. 개인 사용자 데이터를 건드리거나, 어떤 것을 삽입, 업데이트 또는 삭제하는 순간, Google은 해당 데이터의 소유자로부터 OAuth 2.0 토큰을 요구합니다. 동영상 평가, 자신의 구독 목록 보기 또는 mine=true 필터 사용은 모두 OAuth 영역에 속합니다. API 키와 베어러 토큰 비교는 두 가지 자격 증명이 서로 다른 질문에 답하는 이유를 설명합니다.

AI 에이전트가 내 YouTube API 키를 사용할 수 있나요?

예, 키의 제한이 허용하는 곳에서 에이전트가 실행되는 한 가능합니다. YouTube MCP 서버는 코딩 지원자에게 동영상 데이터를 전달하는 한 가지 방법입니다. 데이터 API 및 에이전트가 실행되는 머신으로 제한된 키를 제공하고, 프롬프트 자체에는 포함시키지 마십시오.

키가 유출되면 어떻게 해야 하나요?

자격 증명 페이지에서 해당 키를 삭제하고 새 키를 생성하십시오. 그런 다음 소스를 수정하십시오. Apidog의 로컬 값 또는 비밀 저장소로 키를 옮기고, 이전 키가 기록에 남아 있지 않도록 저장소를 스캔하십시오.

다음 단계

이제 프로젝트, 활성화된 API, 제한된 키, 그리고 curl, Python, Apidog에서 작동하는 요청을 갖게 되었습니다. 저장된 시나리오를 CI에 연결하고 할당량 페이지를 통해 최적화 시기를 확인하십시오.