전사 API: 개요, 인증 및 한도
VoxScriber REST API 사용 방법: 접근 권한, vpt_live_ 키, Bearer 인증, 요청 한도 및 주기별 과금에 대해 알아봅니다.
VoxScriber REST API를 사용하면 사이트를 거치지 않고도 URL로 오디오를 보내고 전사 결과를 바로 내 시스템에서 받을 수 있습니다. 패널에서 만든 전사와 동일한 엔진을 사용하며, 동일한 주기를 차감합니다.
사용할 수 있는 사람
API는 Profissional(R$ 39,90/월) 요금제부터 제공됩니다. Profissional, Premium, 모든 Empresariais 요금제(월간 및 연간)와 그에 해당하는 레거시 요금제에서 사용할 수 있습니다. 계정이 자격 요건을 충족하지 않으면 키 관련 라우트에서 403 PLAN_NOT_ELIGIBLE 오류가 반환됩니다.
API 키
키 생성
비밀 키를 즉시 복사하세요
vpt_live_...이며 생성 시 한 번만 표시됩니다. 저희는 키의 해시만 저장하므로 나중에 다시 볼 수 없습니다.안전하게 보관하세요
키를 잃어버렸나요? 다시 표시할 방법이 없습니다. 이전 키를 폐기하고 새 키를 만드세요. 유출된 키는 즉시 폐기해야 합니다.
개인 키 생성은 아직 패널에 전용 화면이 없습니다. 요금제가 자격을 갖추었고 API 사용을 시작하려면 티켓 열기를 통해 팀이 액세스를 활성화해 드립니다.
인증
모든 요청은 Authorization 헤더에 키를 포함해야 합니다.
Authorization: Bearer vpt_live_SUA_CHAVE
헤더 없이 요청하면 401 MISSING_API_KEY가 반환됩니다.
오디오를 전사하도록 보내기
전사 엔드포인트는 api.voxscriber.com 게이트웨이에 있습니다.
curl -X POST https://api.voxscriber.com/v1/transcriptions \
-H "Authorization: Bearer vpt_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{
"audio_url": "https://exemplo.com/gravacoes/reuniao.mp3",
"webhook_url": "https://seusistema.com/webhooks/vozparatexto",
"formats": ["txt", "srt"]
}'
본문에서 허용되는 필드: audio_url, webhook_url, engine(ASSEMBLYAI, WHISPER 또는 ELEVENLABS), language, formats(txt, json, srt, vtt, docx, pdf), metadata 및 idempotency_key. 결과물은 webhook_url로 전달됩니다. Webhooks 및 알림을 참고하세요.
idempotency_key에 고유 식별자(예: 시스템의 녹음 ID)를 사용하세요. 같은 요청이 실수로 다시 전송되어도 오디오가 두 번 처리되거나 과금되지 않습니다.
한도
| 한도 | 값 |
|---|---|
| 키당 요청 수 | 분당 60회 |
| URL에서 다운로드하는 오디오 | 최대 500 MB(60초 타임아웃) |
| passthrough를 통한 오디오(프리미엄 engine이 URL을 직접 읽음) | 최대 5 GB |
| 계정당 활성 키 | 20개 |
URL 보안 규칙: https만 허용하며, 리디렉션은 금지되고 내부/비공개 주소는 차단됩니다. 오디오 URL은 공개적으로 접근 가능해야 합니다.
사용 가능한 내보내기 형식은 사이트와 동일하게 요금제 게이트를 따릅니다. 요금제에 포함되지 않은 형식은 exports_skipped에 나열되어 반환됩니다.
과금
API는 선택한 engine에 따라 사이트에서 전사했을 때와 동일한 주기를 차감합니다(표준/Whisper: 1주기/분, Premium: 4주기/분, Ultra: 10주기/분). 현재 월간 호출 할당량이나 키별 지출 상한은 없습니다. 주기 잔액으로 사용량을 관리하세요. 주기 시스템을 참고하세요.
FAQ
API 키를 잃어버렸습니다. 어떻게 복구하나요?
복구할 수 없습니다. 데이터베이스에는 해시만 있기 때문입니다. 잃어버린 키를 폐기하고 새 키를 만드세요.
API가 사이트보다 더 비싸나요?
아니요. 주기 비용은 동일하며, engine과 오디오 길이에 따라 결정됩니다.
URL 대신 파일을 직접 보낼 수 있나요?
기본 채널은 audio_url입니다. 오디오에 공개 URL이 없다면 지원팀에 문의하여 적합한 방식을 평가받으세요.
OpenAPI 문서가 있나요?
/.well-known/openapi.json의 공개 스펙은 현재 공개 엔드포인트(통계 및 공유 전사)만 다룹니다. 나머지는 이 헬프 센터와 지원팀을 이용하세요.
관련 문서
문제가 해결되지 않았나요? 티켓 열기 — 팀이 빠르게 응답합니다.