API로 전사 자동화: 실용 예제
VoxScriber API로 자동화 레시피: URL로 녹음 보내기, 엔진과 형식 선택, idempotency_key와 metadata 사용, 웹훅으로 모든 결과 받기.
API를 사용하면 전화, 회의 녹음기, 내부 시스템 등 모든 녹음 소스를 수동 개입 없이 검색 가능한 텍스트로 변환할 수 있습니다. 이 글에서는 권장 흐름과 준비된 레시피를 소개합니다. 먼저 전사 API의 사전 요구 사항을 확인하세요(Profissional+ 플랜 및 vpt_live_ 키).
권장 흐름
webhook_url과 함께 URL로 오디오를 보냅니다.- 작업이 끝나면(성공 또는 실패) 콜백을 받습니다.
- 결과 링크에서 내보낸 파일을 다운로드합니다 — 링크는 7일간 유효합니다.
폴링은 필요 없습니다. 키당 분당 60회 요청 제한이 있으므로 상태를 반복 조회하면 할당량을 낭비하게 됩니다. 웹훅이 서버가 다운된 경우 최대 6회 재전송과 함께 결과를 자동으로 전달합니다.
레시피 1 — 모든 새 녹음 전사하기
curl -X POST https://api.voxscriber.com/v1/transcriptions \
-H "Authorization: Bearer $VPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://storage.suaempresa.com/calls/2026-08-02-0931.mp3",
"webhook_url": "https://api.suaempresa.com/hooks/vpt",
"formats": ["txt", "docx"],
"metadata": { "call_id": "0931", "agente": "maria" },
"idempotency_key": "call-2026-08-02-0931"
}'
metadata는 웹훅에서 다시 전달됩니다. 결과를 시스템의 레코드와 연관 짓는 데 사용하세요.idempotency_key는 실수로 인한 재전송(클라이언트 측 재시도, 작업 중 배포)으로 같은 오디오가 두 번 처리되거나 청구되지 않도록 보장합니다.
레시피 2 — 비용에 따라 엔진 선택하기
engine 필드는 ASSEMBLYAI(Premium, 기본값), WHISPER(Padrão), ELEVENLABS(Ultra)를 지원합니다. 마감 품질보다 비용이 더 중요한 대용량 처리에는 Whisper를 사용하세요 — Premium의 4사이클/분 대비 1사이클/분:
-d '{ "audio_url": "...", "webhook_url": "...", "engine": "WHISPER" }'
실용 규칙: 중요한 회의와 인터뷰에는 Premium, 대용량 및 소음이 있는 오디오에는 Padrão(Whisper), 화자 분리가 완벽해야 할 때는 Ultra를 사용하세요(Profissional+에서 제공).
레시피 3 — 자동 자막
formats: ["srt", "vtt"]를 요청하면 웹훅에서 YouTube 또는 웹 플레이어용 자막을 바로 받을 수 있습니다. 각 형식의 자세한 내용은 다른 도구로 내보내기에서 확인하세요.
자동화에 영향을 주는 제한
| 항목 | 규칙 |
|---|---|
| Rate limit | 키당 분당 60회 요청 |
audio_url | https 전용, 공개, 최대 500 MB(다운로드) 또는 Premium 엔진으로 passthrough 시 5 GB |
| 형식 | 플랜에 따른 게이트를 따름; 허용되지 않은 형식은 exports_skipped로 반환 |
| 다운로드 링크 | 7일 후 만료(전사 결과는 아카이브에 계속 유지) |
| 사이클 | 사이트와 동일한 비용, 동일한 잔액에서 차감 |
사이클 잔액을 모니터링하세요. 현재 키당 지출 상한은 없습니다. 통제되지 않은 루프가 있는 자동화는 실제 잔액을 소모합니다. idempotency_key가 첫 번째 방어선입니다.
FAQ
최종 텍스트는 어떻게 받나요 — 웹훅으로 받나요 아니면 다운로드해야 하나요?
웹훅은 요청한 형식으로 내보낸 파일의 링크와 완료 상태를 전달합니다. 파일은 7일 이내에 다운로드하세요. 이후에도 콘텐츠는 사이트의 아카이브에서 계속 확인할 수 있습니다.
오디오 언어를 설정할 수 있나요?
네, language 필드로 설정할 수 있습니다. 미설정 시 계정의 기본값이 적용되며, 자동 감지도 엔진에서 지원됩니다.
두 시스템이 같은 오디오를 보내면 어떻게 되나요?
두 곳에서 동일한 idempotency_key를 사용하세요 — 첫 번째 요청만 처리되고 청구됩니다.
자동화는 조직 구성원도 사용할 수 있나요?
네 — 사용량은 회사 플랜의 규칙을 따릅니다. 대규모 통화 감사가 필요하면 전용 API를 확인하세요.
관련 문서
문제가 해결되지 않았나요? 티켓 열기 — 저희 팀이 빠르게 응답합니다.