Google Apps Script와 Supadata를 이용해 YouTube 영상을 자동으로 전사하고 요약하는 방법

iadots.com에서는 AI, 에이전트, 로봇 공학 및 휴머노이드에 관한 영상을 네 가지 언어로 모아둡니다. 모든 영상을 시청하며 손으로 요약하는 것은 확장성이 떨어지기 때문에 간단한 자동화를 구축했습니다. Google Apps Script의 스크립트를 사용하여 Supadata API로 영상 전사본을 가져오고, 텍스트를 언어 모델에 보내 요약을 저장합니다. 이 튜토리얼에서는 완전한 코드와 실제 운영 중 배운 주의사항과 함께 동일한 구조를 처음부터 만드는 방법을 보여줍니다.

예제는 Google 스프레드시트를 영상 작업 대기열(queue)로 사용합니다. 제 경우 소스는 Blogger의 게시물들이지만, 논리는 같습니다.

사전 준비 사항 (Pré-requisitos)

• Apps Script와 Google Sheets를 사용하기 위한 Google 계정.
• Supadata API 키 (테스트에는 무료 플랜으로 충분).
• Google AI Studio에서 생성한 Gemini API 키. 요약 기능을 적응시킨다면 다른 모델을 사용해도 됩니다.
• Videos라는 이름의 시트가 있고, 세 개의 열(youtubeId (URL의 v= 뒤 코드), lang (영상의 원본 언어, 예: en 또는 pt), resumo (처음에는 비워둠))를 가진 스프레드시트.

스프레드시트 내에서 '확장 프로그램(Extensions)' > 'Apps Script'로 프로젝트를 만들거나 script.google.com에서 만드세요.

1단계: 스크립트 속성에 키 저장하기 (guardar as chaves em Script Properties)

API 키는 절대 코드에 직접 작성하지 마세요. Apps Script 편집기에서 '프로젝트 설정(Configurações do projeto)' > '스크립트 속성(Propriedades do script)'으로 이동하여 두 가지 속성을 만드세요: SUPADATA_API_KEY와 GEMINI_API_KEY. 스크립트는 실행 시간에 이 값들을 읽습니다:

const SUPADATA_BASE = 'https://api.supadata.ai/v1';
const GEMINI_MODEL = 'gemini-3.8-flash'; // 원하는 모델로 변경하세요
const PLANILHA_ID = '여기에 스프레드시트 ID를 붙여넣으세요';
...

2단계: 전사 기능 (a função de transcrição)

엔드포인트는 GET /v1/transcript이며, 헤더 x-api-key로 인증합니다. 세 가지 중요한 매개변수를 사용합니다: mode=native는 AI를 통해 전사본을 생성하지 않고 영상에 이미 존재하는 자막만 검색합니다; text=true는 시간별 조각 대신 연속된 텍스트를 반환하며; lang은 원본 언어와 관련됩니다.

문서의 세부 사항이 모든 것을 바꿉니다: 요청된 언어가 존재하지 않으면 API는 사용 가능한 첫 번째 언어를 반환합니다. 따라서 스크립트는 응답의 lang 필드를 확인하고, 이 값이 요청과 일치하지 않을 경우 결과를 폐기합니다. 이렇게 하면 일본어 영상이 실수로 번역된 자막을 기반으로 요약되는 것을 방지할 수 있습니다.

매우 긴 영상은 상태 202와 jobId를 가지고 반환될 수 있습니다. 이 경우, 상태가 completed 또는 failed가 될 때까지 GET /v1/transcript/{jobId}를 주기적으로 확인하기만 하면 됩니다.

function buscarTranscricao(youtubeId, lang) {
  const key = chave('SUPADATA_API_KEY');
  const videoUrl = 'https://www.youtube.com/watch?v=' + youtubeId;
...

180,000 바이트 제한은 엄청나게 긴 전사본이 요약을 느리고 비싸게 만들 수 있고, Apps Script의 실행 시간을 초과할 수 있기 때문에 존재합니다.

단계 3: 요약 기능

요약에는 UrlFetchApp을 통해 직접 호출하는 Gemini API의 generateContent 메서드를 사용합니다. 키는 로그에 나타나지 않도록 URL이 아닌 x-goog-api-key 헤더에 넣어야 합니다.

function gerarResumo(transcricao, lang) {
  const url = 'https://generativelanguage.googleapis.com/v1beta/models/' + 
    GEMINI_MODEL + ':generateContent';
...

원래 언어로 요약을 요청하면 사이트의 모든 버전이 일관성을 유지할 수 있습니다.

단계 4: 모두 연결하고 중복 지출 방지

이것은 제가 가장 걱정했던 부분입니다. Supadata 호출이 도중에 만료되면, 스크립트는 크레딧이 사용되었는지 알 수 없습니다. 만약 다음 실행에서 단순히 다시 시도하면 같은 영상에 대해 두 번 결제할 수도 있습니다.

해결책은 요청을 보내기 전에 PropertiesService에 시도를 기록하는 것입니다. 이미 마커가 존재하면 해당 영상은 건너뜁니다. 이 기록은 성공 여부 또는 실패 사유와 함께 마지막에 업데이트됩니다.

function listarPendentes() {
  const aba = SpreadsheetApp.openById(PLANILHA_ID).getSheetByName('Videos');
  return aba.getDataRange().getValues().slice(1)
...

만약 전사(transcription) 후 요약이 실패하면, 해당 영상은 erro로 표시됩니다. 원인을 확인하고 나중에 다시 시도하려면 수동으로 속성(property)을 삭제할 수 있습니다. 이는 의식적인 결정입니다. 저는 알아차리지 못하고 두 번 지불하는 것보다 한 사례를 직접 검토하는 것을 선호합니다.

5단계: 자동 트리거 (gatilho automático)

마지막으로, 메인 함수가 한 번에 몇 개의 영상만 처리하며, 시간 기반 트리거(trigger)가 이를 매시간 실행합니다. LockService는 두 개의 실행이 동시에 작동하여 같은 영상을 가져가는 것을 방지합니다.

function rodarAutomacao() {
  const lock = LockService.getScriptLock();
  if (!lock.tryLock(1000)) return;
...

편집기에서 criarGatilho를 한 번 실행하고 권한을 승인하세요. 그 후부터는 스프레드시트의 새 행마다 최대 1시간 이내에 요약이 생성됩니다.

팁 및 일반적인 오류

• Status 206 또는 "transcript-unavailable": 해당 영상에 요청된 언어의 자막(caption)이 없는 경우입니다. mode=native를 사용할 때는 예상되는 상황입니다. 이러한 경우까지 처리하려면, 자막이 없을 때 AI로 전사를 생성하는 mode=auto를 테스트해 볼 수 있지만, 사전에 크레딧 비용을 확인하세요.
• 잘못된 언어 코드: ISO 639-1 코드(en, pt, es)를 사용하세요. 스크립트는 비교 시 -BR과 같은 접미사를 이미 무시합니다.
• 실행 시간: Apps Script는 실행당 몇 분의 제한 시간이 있습니다. 그래서 한 번에 다섯 개의 영상을 처리합니다.
• 속성(Properties) 제한: PropertiesService에는 저장 공간 할당량(quota)이 있습니다. 여기에 상태만 저장하고 요약은 스프레드시트나 데이터베이스에 남겨두세요.

결론

Apps Script 약 100줄만으로, 서버와 인프라 비용 없이도 영상 목록을 게시할 준비가 된 요약본으로 변환할 수 있습니다. iadots.com이 수동 작업 없이 네 가지 언어로 영상 요약을 유지하는 방식이 바로 이렇습니다. 차이를 만드는 핵심 포인트는 반환된 언어를 확인하고, 텍스트 크기를 제한하며, 크레딧을 소모하기 전에 모든 시도를 표시하는 것입니다.

Supadata 테스트: https://supadata.ai/r/HHD1MQYC

고지: 이 기사는 Supadata의 제휴 링크를 포함하고 있습니다. 이 링크를 통해 가입하시면 제가 크레딧을 받을 수 있습니다.