메인 콘텐츠로 건너뛰기
오디오 작업은 두 가지 형태로 나뉩니다. 텍스트 음성 변환, 전사, 오디오 번역처럼 파일에 가까운 요청은 audio endpoint를 사용합니다. 낮은 지연의 대화형 오디오나 실시간 멀티모달 이벤트가 필요하면 realtime WebSocket endpoint를 사용합니다.

​
워크플로 선택

워크플로Endpoint사용 시점
텍스트 음성 변환POST /v1/audio/speech텍스트에서 오디오 파일이 필요할 때.
전사POST /v1/audio/transcriptions오디오 파일에서 텍스트가 필요할 때.
오디오 번역POST /v1/audio/translations오디오 파일에서 번역된 텍스트가 필요할 때.
실시간 세션GET /v1/realtime양방향 스트리밍 오디오나 실시간 멀티모달 이벤트가 필요할 때.

​
모델 찾기

클라이언트에 모델 목록을 고정하지 마세요. 음성과 전사는 추천 목록을 사용하고, realtime은 socket을 열기 전에 모델 상세에서 지원 여부를 확인하세요. 
curl "https://api.tokenlab.sh/v1/models?recommended_for=tts" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models?recommended_for=stt" \
  -H "Authorization: Bearer sk-your-api-key"

​
동기 오디오 요청

음성, 전사, 번역은 HTTP 요청에서 직접 반환됩니다. 큰 입력은 일반적인 클라이언트 timeout보다 오래 걸릴 수 있으므로 넉넉한 timeout과 request ID 저장을 권장합니다. 
curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1-hd",
    "voice": "nova",
    "input": "Welcome to TokenLab."
  }' \
  --output speech.mp3

​
실시간 세션

WebSocket을 열 때 query string에 model을, Authorization header에 API key를 넣습니다. 선택한 realtime 모델 문서의 이벤트 형식을 사용하고, 세션이 끝나면 socket을 닫으세요. 
import WebSocket from 'ws';

const socket = new WebSocket('wss://api.tokenlab.sh/v1/realtime?model=gpt-realtime', {
  headers: { Authorization: 'Bearer sk-your-api-key' }
});

socket.on('message', (event) => console.log(event.toString()));

​
상태 처리

  • 생성된 오디오 파일을 저장하고 새로고침 때 같은 요청을 반복하지 마세요.
  • 전사와 번역은 동기 호출이어도 업로드 및 처리 상태를 보여주세요.
  • realtime은 close 이벤트를 처리하고 사용자가 새 세션을 시작할 때만 재연결하세요.
  • API key, 비공개 URL, 계정 secret을 오디오 텍스트 입력에 넣지 마세요.

​
API 레퍼런스

주제레퍼런스
음성 생성음성 생성
전사 생성전사 생성
번역 생성번역 생성
Realtime WebSocketRealtime WebSocket
모델 목록모델 목록
청구 및 가격청구 및 가격