Zoom Summarizer API 핸즈온 — 텍스트 변환부터 회의 요약 및 액션 아이템 추출까지

지지난 기사에서는 Zoom Scribe API (텍스트 변환), 지난 기사에서는 Translator API (번역)를 다루었습니다. 이번에는 Zoom AI Services API 시리즈의 두 번째이자 마지막 하나인 Summarizer API (요약) 입니다.

2026년 5월, Zoom AI Services에 Summarizer API (Fast + Batch)가 정식 출시되었습니다. 본 기사에서는:

• 🇯🇵
  일본어를 포함한 12개 언어 출력 - 🎯
  4종류의 요약 태스크 (full_summary / recap / summary / action_items) - 📦 Fast (동기·텍스트 직접 전달)와 Batch (비동기·S3 연동) 2가지 모드

를 실제로 호출하여 지원 포맷, 실제 동작, 주의할 점을 정리합니다. 지난번까지 사용해 온 auth.js와 index.js 구성에 맞춰 진행하겠습니다.

본 기사는 2026년 5월 시점의 동작을 기준으로 합니다. Translator Batch가 .txt만 지원했던 것에 비해, Summarizer Batch는 .vtt / .srt / .txt 3종류를 지원한다는 점이 큰 차이점입니다. VTT/SRT는 내부적으로 타임스탬프를 자동으로 제거하여 정규화됩니다.

Fast 모드 (동기)와 Batch 모드 (비동기)의 시계열을 나열한 도표입니다.

이번 기사에서는 Batch 작업의 처리 상태를 폴링 (Polling)으로 가져오고 있지만, 공식 문서에 명시된 대로 Webhook을 통해 푸시 알림을 받는 것도 가능합니다.

항목	Fast	Batch
엔드포인트	POST /v2/aiservices/summarizer/summarize	POST /v2/aiservices/summarizer/jobs
처리 방식	동기 (즉시 응답)	비동기 (폴링 또는 Webhook)
입력	input.text 필드에 직접	S3 상의 파일
입력 포맷	플레인 텍스트	.vtt / .srt / .txt
입력 크기 상한	(명시되지 않음)	96 KB / 파일
작업 상한	-	PREFIX: 10,000 파일 / MANIFEST: 1,000 파일 / 1억 자
AWS 인증	불필요	필수 (STS 임시 자격 증명)
적합한 용도	단발성 요약, 니어 리얼타임 (Near Real-time) 회의 사후 처리	아카이브 일괄 요약, 콜센터 QA

config.task로 출력 내용을 전환할 수 있습니다. 응답의 result 필드 내용도 task에 따라 변화합니다.

task	출력 필드	용도
full_summary	result.full_summary (Recap + Summary + Action Items가 모두 포함된 마크다운)	모든 내용 포함. 기본값
recap	result.recap	핵심 요약 (Executive Summary)
summary	result.summary_text	회의록 스타일의 섹션 요약
action_items	result.action_items	담당자가 지정된 TODO 추출

ISO 로케일 형식입니다. config.language로 출력 언어를 지정합니다. 입력 언어는 자동 감지되므로, source_language와 같은 지정은 필요하지 않습니다.

코드	언어
en-US	영어
ja-JP	일본어
zh-CN / zh-Hans	중국어 (간체)
es-ES	스페인어
fr-FR	프랑스어
de-DE	독일어
pt-PT / pt-BR	포르투갈어
it-IT	이탈리아어
ar-SA / ar-AE	아랍어

일본어 transcript를 넣고 영어 요약을 출력하는 것과 같은 언어 교차 요약도 가능합니다. 요약과 번역이 한 번에 이루어진다는 이미지입니다.

JWT 인증은 지난번까지와 동일한 메커니즘입니다. auth.js의 generateJwt()를 그대로 재사용합니다.

이전의 디렉토리 구성을 그대로 활용합니다.

ai-services-handson/
├── .env
├── auth.js # JWT 인증 (공통)
...

// fast.js
import { generateJwt } from "./auth.js";
const SUMMARIZER_FAST_URL =
...

포인트:

• 입력은 input.text로 감싸는 구조입니다 (Translator는 text:로 평치(flat)되어 있었던 것과 미묘하게 다르므로 주의하세요).
• language는 **출력 언어 (output language)**만 지정합니다. Translator와 같은 source_language는 없습니다 (입력은 자동 감지됩니다).
• summary_type은 현재 `

에서 JSON 구조 문자(중괄호, 키 이름, 인용부호 등)까지 전부 카운트됩니다. 요약 모델은 JSON을 읽어 내용을 이해하지만, 과금은 모든 문자에 대해 발생한다는 개념입니다.

Fast Summarizer에 JSON이나 구조화된 텍스트를 직접 입력하면 구조 문자까지 토큰으로 소비됩니다. 비용 최적화를 고려한다면, Scribe 출력 JSON에서 result.text_display나 segments[].text를 추출하여 일반 텍스트(plain text)로 변환한 뒤 전달하는 것을 권장합니다.

"For All Mankind" 시즌 1-에피소드 6의 긴 대사를 넣어 테스트해 보았습니다.

node index.js summarize-fast ./samples/english.txt --lang en-US --task action_items

Status: 200
Elapsed: 2.13s
Usage: input=944 output=0 (characters)

output=0으로 비어 있음! 내용을 읽어보니, 확실히 "식에서 누군가가 연설을 하고 있을 뿐"이라 액션 아이템(action items)이 없는 스크립트(transcript)였습니다. Summarizer는 억지로 액션 아이템을 날조하지 않고, 찾을 수 없으면 빈 값을 반환하는 동작을 하는 것으로 보입니다.

반면, 동일한 소재를 --task recap으로 호출하면:

--- recap ---
The meeting marked a significant occasion as NASA recognized the first woman to become a Flight Director.
Administrator Weisner delivered a speech highlighting the importance of the day for the country and the program.
...

제대로 요약해 줍니다. task에 따라 출력 여부가 달라지므로, 애플리케이션 측에서 핸들링이 필요할 것 같습니다.

node index.js summarize-fast --text "Alice: 朝礼始めます。Bob: 認証モジュール終わりました。" --lang ja-JP

--- full_summary ---
# Recap
この会議は朝礼の開始を目的として行われた。Aliceが朝礼を始めると述べた。Bobは認証モジュールの作業が完了したと報告した。
...

단 33자의 입력으로부터 Action Items까지 추측해 줍니다.

S3의 summarize_input/에 다음을 배치합니다:

• japanese.txt — 일본어 텍스트
• english.txt — 영어 텍스트
• transcript.vtt — VTT 자막
• *.json × 3개 (Scribe Batch의 이전 출력, 검증용)

node index.js summarize-batch --lang ja-JP --task full_summary --ref summary-ja-001

=== Summarizer Batch API ===
Input: s3://zoom-scribe-handson-<yourname>/summarize_input/
Output: s3://zoom-scribe-handson-<yourname>/summarize_output/
...

에러 메시지를 통해 API가 지원하는 확장자를 알려줍니다:

Supported extensions: .srt, .txt, .vtt

node index.js summarize-batch --lang en-US --task action_items --ref summary-en-001

성공한 파일의 summarize_output/에는 각각 JSON이 출력됩니다. 예를 들어 영어 샘플 출력(AI_NEXUS.m4a_<uuid>.txt_<uuid>.json):

{
"model": "zoom-summarizer-v1",
"request_id": "090da4a3-e078-4a41-b306-37b0e194daee",
...

담당자 이름을 알 수 없는 경우에는 Unknown으로 화자를 플레이스홀더(Placeholder) 처리해 줍니다. 화자 라벨(Speaker label)이 붙어 있지 않은 전사 데이터(Transcript)에서도 오류가 발생하지 않도록 설계된 사양으로 보입니다.

Summarizer API도 새로운 API이기 때문에, 몇 가지 확인이 필요한 포인트가 있습니다.

{
"state": "FILE_SKIPPED",
"error": {
...

원인: Summarizer Batch는 .srt / .txt / .vtt 3가지 형식만 지원합니다. Scribe Batch의 .json 출력을 그대로 흘려보내면 스킵(Skip)됩니다. 대응 방안:

• Scribe Batch를 output_format: "vtt"로 설정하여 VTT 출력으로 전환합니다 (가장 간편한 방법).
• JSON 파일만 있는 경우, result.text_display나 segments[].text를 추출하여 .txt로 재업로드합니다.

Usage: input=944 output=0 (characters)

원인: 입력된 전사 데이터(Transcript)에 액션 아이템(Action items) 요소가 포함되어 있지 않으면, Summarizer는 빈 값을 반환합니다 (억지로 꾸며내지 않는 사양).

대응 방안: 이는 에러가 아니라 사양입니다. 액션 아이템을 찾지 못했을 경우에 대한 핸들링을 애플리케이션 측에서 구현해 주세요.

if (data.result.action_items?.trim()) {
// 일반적인 처리
} else {
...

이는 Scribe / Translator Batch에서도 관찰되었던 현상인데, Summarizer에서도 동일하게 발생합니다. 모든 파일이 FILE_SKIPPED로 끝날 경우, state가 QUEUED 상태로 머물며 움직이지 않을 수 있습니다.

대응 방안: summary.total_files == 각 카운트의 합계가 되면 종료된 것으로 직접 판단하는 워크아라운드(Workaround)를 넣습니다. 지난번 Translator 기사와 동일한 구현 방식입니다.

// 직접 종료를 판정하는 워크아라운드
function isTerminal(summary) {
const { total_files, queued, processing } = summary;
...

참고로 Webhook으로 알림을 받는 경우에도, 이 패턴(모든 파일이 SKIPPED된 경우)에서는 알림이 오지 않습니다. (2026년 5월 기준)

이는 설계상의 사양입니다.

입력	출력
예상	플레인 텍스트(Plain text) 또는 VTT/SRT (타임스탬프 자동 제거)
목적	"인간의 발화·대화 텍스트"를 요약 모델에 전달

즉, "Summarizer의 출력 JSON을 그대로 Summarizer에 다시 투입할 수 없는 것"은 사양입니다. Scribe / Translator의 JSON 출력도 마찬가지로 그대로는 사용할 수 없습니다. 파이프라인을 구축할 때는 중간 단계에 "JSON → plain text 추출" 단계를 삽입하도록 하세요.

// Scribe JSON을 Summarizer에 전달하기 위한 변환 헬퍼 (예시)
function scribeJsonToPlainText(scribeResult) {
return scribeResult.result.segments
...

간략하게 정리해 보았습니다.

관점	Fast Summarizer	Batch Summarizer
처리 방식 (Processing Method)	동기 (즉시 응답)	비동기 (Polling 또는 Webhook)
입력 (Input)	텍스트 직접 (input.text)	S3 상의 파일
입력 포맷 (Input Format)	플레인 텍스트 (Plain Text) (VTT/JSON도 문자열로 수용 가능하지만 비용 측면에서 비권장)	.vtt / .srt / .txt
AWS 인증	불필요	필수 (STS 임시 자격 증명)
task의 동작	해당 내용이 없는 경우 빈 값을 반환	위와 동일
적합한 용도	짧은 transcript (전사 데이터)의 즉시 요약, VTT 자막의 요약 추출	아카이브 일괄 요약, 향후 Scribe (VTT) 파이프라인