Zoom AI Services를 사용하여 15분 만에 모든 앱에 AI 회의 요약 추가하기

만약 여러분이 회의 녹화본(스탠드업, 영업 통화, 지원 통화 등)을 가지고 있고, 자체 음성 모델을 실행하지 않고도 그 내용에서 요약 및 실행 항목을 얻고 싶다면, 단 두 개의 REST 호출이면 충분합니다:

1. Scribe — 오디오 파일을 스크립트로 변환합니다(화자 및 타임스탬프 포함).
2. Summarizer — 스크립트를 개요, 상세 요약, 실행 항목으로 변환합니다.

이 두 기능 모두 Zoom의 개발자 API 플랫폼인 Zoom AI Services에 속해 있습니다. 개발자 포털은 zoom.ai에서 확인할 수 있습니다 (2026년 10월 확인됨 — 이는 Zoom 자체 포털이며, 제3자가 아닙니다). SDK가 필요하지 않으며, 일반적인 REST 방식입니다.

전체 코드는 파이썬(Python) 약 60줄 분량입니다.

전제 조건 (Prerequisites)

• Python 3.9 이상 및 requests 라이브러리 (pip install requests).
• Zoom AI Services 개발자 포털 계정. zoom.ai에 로그인하여 API keys 섹션으로 이동한 후, Scribe와 Summarizer 스코프를 가진 키를 생성합니다. 이 키는 한 번만 표시되므로, 즉시 복사하여 서버 측에 저장해야 합니다.

이것이 자격 증명(credentials) 설정의 전부입니다. 중요한 규칙 하나가 있습니다: API 키는 반드시 서버 간 통신(server-to-server) 용도로만 사용해야 합니다. 절대로 클라이언트 측 코드에 넣거나 모바일/웹 앱 번들에 포함해서 배포하지 마십시오. 이 튜토리얼의 모든 호출은 백엔드에서 실행됩니다.

먼저 아무 설정 없이 시도해 보기 (Try it with zero setup first)

키를 생성할 준비가 되지 않았나요? 포털에는 샘플 데이터와 상호 작용 가능한 플레이그라운드가 있습니다 — 별도의 설정이 필요 없습니다. 스크립트를 연결하기 전에 응답 형식을 파악하기 위해 2분 정도 사용해 보는 것을 추천합니다.

단계 1: Scribe를 사용하여 오디오 전사 (Transcribe audio with Scribe) (빠른 모드)

Scribe는 세 가지 모드를 가지고 있습니다: Live(보안 WebSocket을 통한 실시간 전사, 주소: wss://api.zoom.us/v2/aiservices/scribe/live), Fast(동기식 — 오디오 바이트를 POST하면 전사가 완료될 때 응답이 돌아옴), 그리고 Batch(긴 파일을 위한 비동기 작업 API 및 웹훅 콜백). 이 튜토리얼에서는 가장 간단한 Fast 모드를 사용합니다. Fast 모드는 최대 5분 분량의 파일까지 처리할 수 있으며, 더 긴 녹음은 Batch(파일당 최대 6시간)을 통해 진행해야 합니다.

입력은 원본 오디오 바이트입니다: WAV, Opus, 그리고 µ-law 인코딩(Content-Type에 따라 audio/wav 등). 지원하는 로케일은 9개입니다: en-US, de-DE, es, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, zh-CN.

엔드포인트: POST https://api.zoom.us/v2/aiservices/scribe/transcribe

인증(Auth): 하나의 헤더 — x-api-key: <your API key>. 포털 문서에 따르면 이것이 전체 인증 방식입니다.

옵션은 쿼리 매개변수로 전달됩니다 (model, language, diarization, text_polishing, profanity_filter, `w

Step 2: 스크립트 요약하기 (Summarizer Fast 모드)

Summarizer API는 전사(transcript) 텍스트(Scribe에서 온 것일 필요 없음 — 어떤 시스템의 것이든 상관없음)를 받아 result.text에 표시 가능한 형태로 렌더링된 텍스트를 반환합니다. Fast 모드는 인라인 스크립트 하나(최대 96 KB)를 받아 동기적으로 결과를 반환합니다.

엔드포인트: POST https://api.zoom.us/v2/aiservices/summarizer/summarize

요청은 플랫 JSON 형태이며, config으로 감싸지 않습니다. transcript는 화자/텍스트 턴(speaker/text turns)의 JSON 인코딩된 문자열입니다:

curl -X POST https://api.zoom.us/v2/aiservices/summarizer/summarize \
  -H "x-api-key: $ZOOM_API_KEY" \
  -H "Content-Type: application/json" \
...

선택할 수 있는 네 가지 작업(task)이 있으며, task에 설정합니다:

가격 책정 관련: Zoom AI Services는 선불 크레딧을 사용하는 사용량 기반(usage-based) 방식입니다. 제가 검증된 분당 요율을 가지고 있지 않으므로, 비용을 추정하기 전에 zoom.us/pricing/developer에서 현재 수치를 확인하세요.

문제 해결 (Troubleshooting)

401 Unauthorized. 가장 흔한 원인: 키가 잘못되었거나 만료된 경우입니다(생성 시 한 번만 표시되므로, 분실했다면 포털에서 재생성해야 합니다), 또는 헤더 이름이 잘못된 경우입니다. 포털 문서에 따르면 인증은 x-api-key 헤더로만 이루어져야 합니다.

지원되지 않는 형식 / 가져오기 오류 (fetch errors). Scribe Fast 모드는 URL이 아닌 원본 오디오 바이트(--data-binary)를 사용합니다. 따라서 Content-Type을 일치하도록 설정해야 합니다 (audio/wav, audio/mpeg, …). Fast 모드 파일은 5분 이내로 유지하고, 더 긴 오디오는 배치(Batch) 처리를 거쳐야 합니다.

429 속도 제한 (rate limits). 백오프(Back off)하며 지수적 백오프(exponential backoff)를 사용하여 재시도하세요. 정확한 속도 제한 및 할당량은 사용자의 플랜에 따라 다르므로, 추측하기보다는 포털을 확인하는 것이 좋습니다.

화자 분리 품질 (Diarization quality). 심한 배경 소음, 겹치는 발화, 그리고 매우 짧은 클립 모두 화자 분리를 저하시킵니다. 만약 레이블이 중요하다면(분석가에게는 중요합니다—Summarizer는 소유자별로 실행 항목을 그룹화하기 때문입니다), 업로드 전에 노이즈 감소 도구로 빠르게 처리하는 것이 도움이 됩니다.

요약기 Fast 모드에 적합하지 않은 긴 스크립트. 인라인 입력은 96 KB로 제한됩니다. 더 긴 회의의 경우, 스크립트를 청크(chunks)로 분할하여 각각 요약하거나 배치 모드로 전환해야 합니다.

다음 단계 (Where to go next)

다음 단계(Where to go next)

• 배치 모드(Batch mode) (두 API 모두): 비동기 작업(async jobs)을 제출하고, GET /aiservices/summarizer/jobs/{jobId} 또는 .../scribe/jobs/{jobId}를 폴링하거나 웹훅 콜백을 받습니다. 웹훅은 서명되어 있으므로, 비밀 키와 함께 x-zm-signature (HMAC-SHA256, sha256= 접두사) 및 x-zm-request-timestamp 헤더로 검증해야 합니다.
• 실시간 모드(Live mode): wss://api.zoom.us/v2/aiservices/scribe/live를 통해 오디오 스트리밍으로 실시간 전사(real-time transcription)를 수행하며, 감지된 발화 턴당 하나의 완료된 세그먼트가 생성됩니다.
• 번역기 API(Translator API): 단 한 번의 호출로 요약 내용을 현지화할 수 있습니다.
• 참조 구현체(Reference implementations): ai-services-quickstart (Express + React 플레이그라운드), scribe-quickstart, 그리고 Scribe/Summarizer, 웹훅 및 문제 해결을 위한 skills 레포지토리 런북이 있습니다.
• 문서(Docs): AI Services 개요와 Scribe API 문서를 참고하세요.

공개 고지: 이 문서는 AI 도움을 받아 작성되었으며, 모든 API 호출 및 코드는 공식 Zoom AI Services 포털 문서(2026년 10월)와 대조하여 확인되었고, Scribe 흐름은 포털 플레이그라운드에서 실시간으로 실행되었습니다.