Wave 개발자 API
범위가 지정된 토큰을 만들어 직접 작성한 코드에서 Wave 세션, 전사, 할 일을 읽고 업데이트하거나 가져올 수 있으며, 검색, 일괄 내보내기, 웹훅도 사용할 수 있습니다.
최종 업데이트:
Wave AI 개발자 API는 내 녹음에 접근하는 REST API입니다. Wave에서 만든 토큰으로 코드를 https://api.wave.co/v1에 연결하면 세션 목록 조회, 요약과 전사 읽기, 의미 기반 검색, 오디오 다운로드, 녹음 가져오기, 제목·요약·할 일 업데이트를 할 수 있습니다. 녹음 처리가 끝나는 즉시 웹훅으로 알림을 받을 수도 있습니다.
모든 Wave 요금제에서 무료로 사용할 수 있으며, 오직 내 계정에만 접근합니다.
토큰 만들기
app.wave.co의 Wave 웹 앱에서 설정 → 개발자로 이동한 뒤 API 토큰 및 웹훅을 여세요. app.wave.co/settings/integrations/api로 바로 이동해도 됩니다.
API 토큰 아래에서 토큰 만들기를 클릭하세요.
나중에 알아보기 쉬운 토큰 이름을 입력하고, 필요한 권한을 선택한 다음 토큰 만들기를 클릭하세요. 공유 토큰 하나보다 연동마다 토큰을 하나씩 두는 편이 훨씬 관리하기 쉽습니다.
토큰 생성됨 대화상자에서 토큰을 복사하세요. Wave는 토큰을 한 번만 보여 줍니다. 지금 이 토큰을 복사하세요. 다시 볼 수 없습니다.
모든 요청에 bearer 토큰으로 보내세요.
curl -H "Authorization: Bearer wave_api_xxx..." \
https://api.wave.co/v1/sessions토큰 목록에는 각 토큰의 이름, wave_api_ 접두사, 권한, 생성일, 마지막 사용일, 만료일이 표시됩니다. 휴지통 아이콘을 누르면 이 토큰을 취소할까요? 확인 창이 나타납니다. 토큰 취소를 선택하면 즉시 적용되며, 해당 토큰을 사용하는 모든 요청은 401을 받게 됩니다.
API 토큰은 생성 후 1년이 지나면 만료됩니다. 몇 달 동안 잘 작동하던 연동이 갑자기 401 invalid_token을 반환한다면 토큰 목록에서 만료 날짜를 확인하고 새 토큰을 만드세요.
권한
권한은 토큰별로 지정합니다. 작업에 필요한 최소한의 권한만 부여하세요.
| 권한 | 허용되는 작업 |
|---|---|
| 세션 읽기 | 세션 목록 조회 및 열기, 통계, 인물, 일괄 내보내기 |
| 세션 및 할 일 쓰기 | 제목, 메모, 요약, 태그, 즐겨찾기, 할 일 업데이트 |
| 세션 삭제 | 세션 영구 삭제 |
| 세션 검색 | 라이브러리 전체 의미 기반 검색 |
| 스크립트 읽기 | 화자 구간이 포함된 전체 전사 |
| 미디어 액세스 | 오디오 및 동영상의 서명된 다운로드 URL |
| 계정 읽기 | 계정 정보 및 구독 상태 |
| 웹훅 관리 | 웹훅 엔드포인트 등록 및 관리 |
| 이벤트 피드 읽기 | 이벤트 피드 가져오기 및 확인 처리 |
| 폴더 읽기 | 폴더 목록 조회 및 열기(세션 읽기로도 가능) |
| 폴더 관리 | 폴더 생성, 이름 변경, 색상 변경, 고정, 순서 변경, 삭제 및 세션 추가·제거 |
| 세션 공유 및 액세스 관리 | 다른 Wave 사용자와 세션 공유, 액세스 권한이 있는 사람 확인 및 제거 |
| 녹음 가져오기(가져오기 한도 사용) | 링크나 업로드로 오디오와 동영상을 Wave에 가져오기. 쓰기 권한에 포함되지 않으므로 따로 선택해야 합니다 |
필요한 권한 없이 엔드포인트를 호출하면 누락된 권한이 명시된 403을 받습니다.
데이터 읽기
GET /v1/sessions— 최신순, 커서 기반 페이지네이션이며type,since,folder,tag,person으로 필터링할 수 있습니다.folder에는 id, 이름 또는Parent/Child경로를 지정하며,include_subfolders=false를 전달하지 않으면 상위 폴더에 하위 폴더의 세션도 포함됩니다. 처리가 완료된 세션만 반환됩니다.GET /v1/sessions/:id— 제목, 길이, 마크다운 요약, 메모, 태그, 즐겨찾기. 통화에는 발신·수신 방향과 전화번호도 포함됩니다.GET /v1/sessions/:id/transcript— 하나로 이어진 전사 문자열과 시간 및 화자 정보가 포함된 구간.GET /v1/sessions/:id/action-items— 구조화된 할 일과 버전 번호.GET /v1/sessions/:id/media— 1시간 동안 유효한 서명된 오디오 및 동영상 URL.POST /v1/sessions/search— 의미 기반 검색, 최대 50개 결과, 태그 필터 선택 가능.POST /v1/sessions/bulk— 한 번의 호출로 요약과 전사를 포함한 세션을 최대 50개 가져옵니다. 기존 데이터를 한꺼번에 가져올 때 가장 빠른 방법입니다.GET /v1/folders,GET /v1/folders/:id,GET /v1/sessions/stats— 폴더, 그리고 유형 및 플랫폼별 합계. 폴더는 한 단계까지만 중첩됩니다. 각 폴더에는parent_id(최상위는null)가 있으며,GET /v1/folders?parent_id=none또는?parent_id={id}로 한 단계씩 조회합니다.
인물
인물은 음성 ID로 저장한 목소리입니다. 세션 읽기 권한만 있으면 되며, 읽기 전용입니다.
GET /v1/people— 목소리를 저장한 모든 사람과 각자가 등장한 녹음 수, 마지막으로 등장한 시점. 내 목소리는is_me로 표시되며 맨 앞에 나옵니다.GET /v1/people/:id/sessions— 한 사람의 녹음을 최신순으로 반환하며, 커서 기반 페이지네이션이고type,from,to로 필터링할 수 있습니다. 각 항목에는 발언 시간, 해당 전사에서의 이름, 가장 긴 발언 세 개가 표시됩니다. 내 목소리는 id로me를 사용하세요.GET /v1/sessions?person=:id— 일반 세션 목록을 해당 인물이 등장한 녹음으로 좁혀 반환합니다.
음성 샘플과 전체 전사는 반환되지 않습니다. 세 줄 이상이 필요하면 전사를 따로 가져오세요. Wave에서 두 음성 ID를 병합했다면 이전 id로 요청할 때 404가 반환되며, merged_into에 사용할 id가 표시됩니다. Wave가 계정의 인물을 아직 색인하는 중에는 최근 1,000개 녹음만 집계되며 응답에 partial: true가 포함됩니다.
데이터 쓰기
PATCH /v1/sessions/:id로 제목, 메모, 요약(마크다운), 태그, 즐겨찾기, 할 일을 설정합니다. 할 일은 먼저 읽은 뒤 받은 버전을 함께 전달하세요. 그러면 Wave 앱에서 동시에 수정된 내용이 있을 때 이를 덮어쓰지 않고 요청이 거부됩니다. POST /v1/folders, PATCH /v1/folders/:id, DELETE /v1/folders/:id와 폴더 소속 관리 엔드포인트(POST 및 DELETE /v1/sessions/:id/folders/:folderId)로 세션을 정리합니다. 폴더는 배타적이지 않아 한 세션이 여러 폴더에 속할 수 있으며, 폴더를 삭제해도 안의 세션은 삭제되지 않습니다. POST /v1/folders에 parent_id를 전달하면 하위 폴더를 만들고, PATCH /v1/folders/:id에 전달하면 폴더를 이동합니다(null이면 최상위로 되돌립니다). 상위 폴더는 최상위 폴더여야 하며, 하위 폴더가 있는 폴더는 다른 폴더 안으로 이동할 수 없습니다. 두 경우 모두 400 invalid_parent를 반환합니다. 상위 폴더를 삭제하면 하위 폴더는 최상위로 이동합니다.
DELETE /v1/sessions/:id는 영구 삭제이며 앱에서 삭제하는 것과 다릅니다. 복구할 수 없다고 생각하세요.
녹음 가져오기
POST /v1/sessions/import는 오디오 또는 동영상 파일로 세션을 만듭니다. Wave는 앱에서 가져온 파일과 똑같이 텍스트로 변환하고 요약합니다. 녹음 가져오기(가져오기 한도 사용) 권한(sessions:import)이 필요합니다. 다음 중 하나를 보내세요.
source_url: 파일 자체를 가리키는 공개 https 링크. Wave가 파일을 다운로드하며(최대 2GiB)status: "fetching"과 함께202로 응답합니다.upload:content_type(선택적으로filename,size_bytes)과 함께 보냅니다. Wave가 서명된upload.url과 함께201로 응답합니다. 15분 이내에 받은upload.headers를 그대로 사용해 해당 URL로 파일을 PUT하세요(최대 5GiB). 업로드가 끝나면 처리가 자동으로 시작됩니다.
title, notes, tags, language, recorded_at도 전달할 수 있습니다. 이후 GET /v1/sessions/:id로 processing_status를 폴링하거나 세션 완료됨 웹훅을 기다리세요.
curl -X POST https://api.wave.co/v1/sessions/import \
-H "Authorization: Bearer wave_api_xxx..." \
-H "Content-Type: application/json" \
-H "Idempotency-Key: standup-2026-10-21" \
-d '{"source_url": "https://example.com/standup.mp3", "title": "Daily standup"}'Idempotency-Key 헤더를 보내면 안전하게 재시도할 수 있습니다. 같은 키와 본문으로 다시 요청하면 두 번째로 가져오지 않고 원래 세션을 반환합니다.
지원 형식: MP3, M4A, WAV, AAC, FLAC, OGG, OPUS, WebM, MP4, MOV, AIFF, AMR, WMA, 3GP, CAF, MPEG, MPEG-TS. 가져오기는 Wave 앱과 계정의 가져오기 한도를 공유합니다. 시간당 12개, 하루 20개이며(유료 고객은 40개, 100개, 생성 후 2일이 지나지 않은 계정은 더 적음), 이를 넘으면 429 import_rate_limited를 받습니다. 남은 녹음 시간이 없는 무료 요금제 계정은 403 subscription_required를 받습니다.
공유
토큰은 사용자 본인으로 동작하므로, 위 권한으로 다른 Wave 사용자가 나와 공유한 세션을 읽을 수 있습니다. GET /v1/shared-sessions로 목록을 조회하고, GET /v1/shared-sessions/{owner_id}/{id}와 그 하위의 /transcript, /action-items, /media로 개별 세션을 읽습니다. GET /v1/sessions에 include=shared를 추가하면 내 목록에 함께 표시되며, 각 항목에 access(owner 또는 shared)가, 공유 항목에는 소유자가 포함됩니다. 공유 항목은 폴더나 태그로 필터링할 수 없고, 공유 세션은 읽기 전용이며, 검색은 내 세션만 대상으로 합니다.
세션 공유 및 액세스 관리 권한이 있으면 토큰으로 내 세션을 공유할 수 있습니다. /v1/sessions/{id}/sharing에서 액세스 권한이 있는 사람을 확인하고, 그 하위 경로로 초대 링크 생성, 이메일 초대(호출당 최대 10개 주소), 대기 중인 초대 취소, 한 사람 제거, 링크 재설정을 할 수 있습니다. 전체 목록과 제한은 Claude, ChatGPT, API, CLI에서 세션 공유하기를 참고하세요.
요청 한도
모든 토큰은 분당 60회, 하루 10,000회까지 요청할 수 있습니다. 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 포함되며, 429에는 Retry-After가 포함됩니다. 바로 재시도하지 말고 기다렸다가 다시 시도하세요.
같은 검색어를 1시간에 10회 넘게 반복해도 429를 받습니다. 동일한 검색은 동일한 결과를 반환하므로, 새 항목을 찾으려면 웹훅이나 GET /v1/sessions?since=를 사용하세요.
웹훅
폴링하는 대신 Wave가 직접 POST하도록 설정하세요. 웹훅 섹션에서 웹훅 추가를 클릭하고 엔드포인트 URL을 입력한 다음(HTTPS만 가능하며, 사설 주소로 연결되는 URL은 거부됩니다) 이벤트를 선택하고 웹훅 만들기를 클릭하세요. 서명 시크릿은 한 번만 표시되므로 바로 저장해 두세요. 웹훅은 최대 5개까지 만들 수 있습니다.
이벤트는 세션 완료됨(처리가 끝나고 요약을 조회할 수 있을 때 한 번 전송되며, 대부분의 연동에 필요한 이벤트), 세션 업데이트됨, 할 일 업데이트됨(API로 할 일을 쓰거나 수정할 때 전송), 세션 삭제됨입니다. POST /v1/webhooks(또는 wave webhooks create)로 코드에서 직접 웹훅을 등록할 수도 있습니다.
세션 완료됨에는 요약 외의 정보도 담을 수 있습니다. POST /v1/webhooks로 웹훅을 만들거나 PATCH /v1/webhooks/:id로 변경할 때 include 객체를 전달하세요.
{ "include": { "summary": true, "transcript": true, "action_items": true } }summary는 기본적으로 켜져 있고, transcript와 action_items는 꺼져 있습니다. 전사를 포함하려면 스크립트 읽기 권한이 있는 토큰이 필요합니다. 매우 긴 전사는 200,000자에서 잘리고 transcript_truncated: true로 표시되므로, 나머지는 GET /v1/sessions/:id/transcript에서 가져오세요. 할 일은 세션이 완료된 시점의 항목이며, 잠시 후 Wave가 할 일을 더 추가하면 할 일 업데이트됨 이벤트를 받습니다. 다른 이벤트에는 항상 기본 세션 정보만 담깁니다.
각 전송은 시크릿으로 서명되며 X-Wave-Webhook-Id, X-Wave-Webhook-Timestamp, X-Wave-Webhook-Signature 헤더와 함께 도착합니다. 페이로드를 신뢰하기 전에 서명을 검증하세요. 서명할 정확한 문자열은 API 레퍼런스에 있습니다.
Wave는 이벤트당 한 번의 전송을 보장하지 않습니다. 시간 초과(10초)되거나 2xx가 아닌 응답을 받은 전송은 짧은 간격(약 10초, 1분, 5분)으로 최대 3회 재시도되며, 같은 이벤트가 두 번 이상 도착할 수 있습니다. 핸들러를 멱등하게 만드세요. X-Wave-Webhook-Id를 키로 사용해 이미 처리한 id는 무시하고, 2xx를 빠르게 반환하세요. 이 시간보다 오래 다운된 엔드포인트는 놓친 이벤트를 받지 못하므로, 아래 이벤트 피드로 따라잡으세요.
엔드포인트가 10회 연속 실패하면 Wave는 해당 웹훅을 자동으로 꺼짐으로 표시하고 전송을 중단합니다. 엔드포인트를 수정한 다음 웹훅 항목에서 웹훅 다시 켜기를 선택하세요.
서버가 없다면 이벤트 피드 사용하기
공개 URL을 호스팅할 수 없다면 폴링하세요. GET /v1/events는 Wave가 토큰별로 추적하는 커서 이후의 이벤트를 반환하고, 처리가 끝나면 POST /v1/events/ack로 커서를 앞으로 옮깁니다. 따라서 스크립트를 다시 시작해도 이벤트를 처음부터 다시 받지 않습니다. 페이지 크기는 기본 50개, 최대 200개이며, 피드에는 할 일 변경도 포함됩니다. 이벤트 피드 읽기 권한이 필요합니다.
폴링 루프를 직접 작성하고 싶지 않다면 Wave CLI의 wave events tail을 사용하세요.
자주 묻는 질문
api.wave.co/reference에서 모든 엔드포인트, 매개변수, 응답 형식을 실시간 예시와 함께 확인할 수 있습니다. api.wave.co/llms.txt는 같은 내용을 일반 텍스트로 제공합니다. AI 어시스턴트에 붙여 넣고 연동 코드를 작성하게 할 수 있습니다.
항상 code와 message가 포함된 JSON입니다. 자주 발생하는 오류는 401 invalid_token(만료, 취소 또는 잘못 입력), 403 insufficient_scope(토큰에 권한 없음), 429(요청 한도 초과)입니다.
나와 공유된 녹음만 표시됩니다. 토큰은 토큰을 만든 계정에 묶여 있어, 해당 계정의 세션과 다른 Wave 사용자가 그 계정과 공유한 세션만 읽기 전용으로 반환합니다.
이 문서가 도움이 되었나요?
도움이 더 필요하신가요?