API 통합

개발자를 위한 완전한 VoxScriber REST API 문서입니다. 인증, 주요 엔드포인트, 웹훅, 그리고 시스템에 자동 전사를 통합하는 방법을 알아보세요.

API 특징

인증

API 키 얻기

API 키 사용

모든 요청의 Authorization 헤더에 API 키를 포함하세요:

curl -X POST https://api.vozparatexto.com.br/v1/transcribe \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@audio.mp3"

주요 엔드포인트

파일 업로드

POST /v1/upload
Content-Type: multipart/form-data

매개변수:

• file (필수) - 오디오/비디오 파일
• language (선택) - 언어 코드 (예: "en-US")
• engine (선택) - 전사 엔진 ("ASSEMBLYAI", "WHISPER", "ELEVENLABS")
• speaker_detection (선택) - 화자 식별 활성화 (boolean)

응답:

{
  "id": "upload_abc123",
  "status": "UPLOADED",
  "duration": 120.5,
  "fileSize": 2048000
}

전사 시작

POST /v1/transcribe
Content-Type: application/json

본문:

{
  "uploadId": "upload_abc123",
  "engine": "ASSEMBLYAI",
  "speakerDetection": true,
  "language": "en-US"
}

상태 확인

GET /v1/transcription/{id}/status

응답:

{
  "id": "trans_xyz789",
  "status": "COMPLETED",
  "progress": 100,
  "text": "Transcribed text...",
  "duration": 120.5,
  "creditsUsed": 8
}

결과 다운로드

GET /v1/transcription/{id}/export?format=json

사용 가능한 형식: json, txt, srt, vtt, docx, pdf

속도 제한

| 엔드포인트 | 제한 | 시간 창 | |---|---|---| | 업로드 | 10개 요청 | 60초 | | 전사 | 10개 요청 | 60초 | | 조회 | 60개 요청 | 60초 | | 내보내기 | 30개 요청 | 60초 |

통합 예제

Node.js

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const API_KEY = process.env.VOXSCRIBER_API_KEY;
const BASE_URL = 'https://api.vozparatexto.com.br/v1';

async function transcribeFile(filePath) {
  // 1. Upload
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));

  const upload = await axios.post(`${BASE_URL}/upload`, form, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      ...form.getHeaders()
    }
  });

  // 2. Transcribe
  const transcription = await axios.post(`${BASE_URL}/transcribe`, {
    uploadId: upload.data.id,
    engine: 'ASSEMBLYAI',
    speakerDetection: true
  }, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });

  return transcription.data;
}

Python

import requests
import os

API_KEY = os.environ['VOXSCRIBER_API_KEY']
BASE_URL = 'https://api.vozparatexto.com.br/v1'

def transcribe_file(file_path):
    headers = {'Authorization': f'Bearer {API_KEY}'}

    # 1. Upload
    with open(file_path, 'rb') as f:
        upload = requests.post(
            f'{BASE_URL}/upload',
            headers=headers,
            files={'file': f}
        )

    # 2. Transcribe
    transcription = requests.post(
        f'{BASE_URL}/transcribe',
        headers=headers,
        json={
            'uploadId': upload.json()['id'],
            'engine': 'ASSEMBLYAI',
            'speakerDetection': True
        }
    )

    return transcription.json()

오류 처리

| 코드 | 의미 | 권장 조치 | |---|---|---| | 400 | 잘못된 요청 | 매개변수 확인 | | 401 | 인증되지 않음 | API 키 확인 | | 403 | 금지됨 | 토큰 권한 확인 | | 429 | 속도 제한 초과 | 잠시 기다린 후 다시 시도 | | 500 | 내부 오류 | 30초 후 다시 시도 |

보안

• 모든 요청에 HTTPS 사용
• API 키를 환경 변수에 저장
• 정기적으로 키 교체
• 필요한 최소 권한 사용
• 웹훅에 대한 서명 확인 구현

계속 학습하기

• 웹훅 및 알림 - 자동 콜백 설정
• 배치 처리 - API를 통해 여러 파일 전사
• 워크플로 자동화 - API로 프로세스 자동화