지지난 기사에서는 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을 통해 푸시 알림을 받는 것도 가능합니다.

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

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

일본어 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월 기준)

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

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

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

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