YouTube Data API v3 활용법

시작하며

1. 영상을 YouTube에 업로드하는 방법

2. 자막 파일을 영상에 업로드하는 방법

3. 다국어 제목과 설명 같은 메타데이터를 함께 등록하는 방법

전체 흐름

1. 사용자가 Google OAuth로 로그인합니다.

2. 서버는 YouTube 업로드 권한이 있는 access token을 확보합니다.

3. 서버 API가 영상 파일 또는 영상 URL을 받습니다.

4. videos.insert로 YouTube 업로드 세션을 만듭니다.

5. 반환된 upload URL에 실제 영상 파일을 PUT으로 업로드합니다.

6. 업로드 결과로 videoId를 받습니다.

7. SRT 자막이 있으면 captions.insert로 업로드합니다.

8. 다국어 제목과 설명은 영상 업로드 시 localizations에 포함합니다.

1. 영상 올리는 법

POST https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status

1-1. 업로드 세션 만들기

const metadata = {
  snippet: {
    title: '업로드할 영상 제목',
    description: '업로드할 영상 설명',
    tags: ['AI dubbing', 'YouTube Data API'],
    categoryId: '22',
    defaultLanguage: 'ko',
    defaultAudioLanguage: 'ko',
  },
  status: {
    privacyStatus: 'private',
    selfDeclaredMadeForKids: false,
  },
}

const initRes = await fetch(
  'https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json; charset=UTF-8',
      'X-Upload-Content-Length': String(videoBlob.size),
      'X-Upload-Content-Type': videoBlob.type || 'video/mp4',
    },
    body: JSON.stringify(metadata),
  },
)

1-2. 실제 영상 파일 업로드하기

const uploadUrl = initRes.headers.get('Location')

const putRes = await fetch(uploadUrl, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': videoBlob.type || 'video/mp4',
  },
  body: videoBlob,
})

const result = await putRes.json()
const videoId = result.id

metadata POST
  -> Location header로 upload URL 수신
  -> upload URL에 video blob PUT
  -> videoId 수신

2. 자막 올리는 법

POST https://www.googleapis.com/upload/youtube/v3/captions?uploadType=multipart&part=snippet

1. 자막 metadata

2. 실제 SRT 파일 내용

const metadata = {
  snippet: {
    videoId,
    language: 'en',
    name: 'English',
  },
}

1
00:00:00,000 --> 00:00:02,000
Hello, everyone.

2
00:00:02,000 --> 00:00:04,000
This video was dubbed automatically.

const boundary = `caption_boundary_${Date.now()}`

const body =
  `--${boundary}\r\n` +
  `Content-Type: application/json; charset=UTF-8\r\n\r\n` +
  JSON.stringify(metadata) +
  `\r\n--${boundary}\r\n` +
  `Content-Type: application/x-subrip\r\n\r\n` +
  srtContent +
  `\r\n--${boundary}--`

const res = await fetch(
  'https://www.googleapis.com/upload/youtube/v3/captions?uploadType=multipart&part=snippet',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': `multipart/related; boundary=${boundary}`,
    },
    body,
  },
)

3. 다국어 제목과 설명(localizations) 올리는 법

const metadata = {
  snippet: {
    title: 'AI 더빙 테스트 영상',
    description: '한국어 기본 설명입니다.',
    categoryId: '22',
    defaultLanguage: 'ko',
    defaultAudioLanguage: 'ko',
  },
  status: {
    privacyStatus: 'private',
    selfDeclaredMadeForKids: false,
  },
  localizations: {
    en: {
      title: 'AI Dubbing Test Video',
      description: 'This is the English description.',
    },
    ja: {
      title: 'AI吹き替えテスト動画',
      description: 'これは日本語の説明です。',
    },
  },
}

POST https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=snippet,status,localizations

서버 API에서 처리한 이유

1. OAuth access token을 서버에서 통제할 수 있습니다.

2. 외부 영상 URL을 서버가 fetch할 때 허용 도메인을 제한할 수 있습니다.

3. YouTube Data API v3 에러를 서비스에서 사용하는 에러 형태로 변환할 수 있습니다.

4. 업로드, 자막, metadata 처리를 하나의 흐름으로 묶기 쉽습니다.

구현하면서 헷갈렸던 점

1. 영상 파일

2. 자막 트랙

3. 다국어 metadata

마무리

참고 자료

• YouTube Data API videos.insert: https://developers.google.com/youtube/v3/docs/videos/insert

• YouTube Data API resumable upload: https://developers.google.com/youtube/v3/guides/using_resumable_upload_protocol

• YouTube Data API captions.insert: https://developers.google.com/youtube/v3/docs/captions/insert

• YouTube Data API video resource: https://developers.google.com/youtube/v3/docs/videos