미디어 가이드
오디오 및 실시간(Realtime)
음성 생성, 오디오 전사, 음성 번역 또는 실시간 세션 시작하기
결과물이 파일이나 텍스트인 경우 오디오 엔드포인트를 사용하세요. 라이브 양방향 오디오 경험이 필요한 경우에는 실시간 WebSocket 엔드포인트를 사용하세요.
엔드포인트 선택
| 필요 작업 | 엔드포인트 | 사용 시기 |
|---|---|---|
| 텍스트 음성 변환 (TTS) | POST /v1/audio/speech | 텍스트로부터 오디오 파일이 필요할 때. |
| 전사 (Transcription) | POST /v1/audio/transcriptions | 오디오 파일로부터 텍스트가 필요할 때. |
| 오디오 번역 | POST /v1/audio/translations | 오디오 파일로부터 번역된 텍스트가 필요할 때. |
| 실시간 WebSocket | WS /v1/realtime?model={model} | WebSocket을 통한 양방향 스트리밍 오디오가 필요할 때. 일반 GET /v1/realtime은 메타데이터만 반환합니다. |
모델 선택
모델 목록을 하드코딩하지 말고 현재 모델 목록을 읽어오세요. 소켓을 열기 전에 선택한 모델의 세부 정보에서 실시간 지원 여부를 확인하세요.
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 응답으로 오디오를 반환합니다. 전사 및 번역은 최종 텍스트 또는 수락된 작업을 반환할 수 있습니다. 본문에 최종 텍스트 대신 작업 ID와 상태가 포함된 경우, 해당 ID를 저장하고 완료 또는 실패할 때까지 GET /v1/tasks/{id}를 폴링하세요. 대용량 파일의 경우 충분한 시간을 확보하고 Request ID를 유지하세요.
오디오 결과 URL은 30일 동안 유효한 TokenLab 미디어 결과 URL입니다. media_retention.items는 각 항목의 저장 상태와 expires_at을 보고합니다. 저장 상태를 제때 알 수 없는 경우 응답에서 media_retention이 생략될 수 있으며, 이 경우에도 URL은 정상적으로 작동합니다. 인라인 또는 바이너리 오디오 응답은 이 URL 복사 보존 정책의 대상이 아닙니다. 데이터 보존을 참조하세요.
curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-tts",
"voice": "eve",
"input": "Welcome to TokenLab."
}' \
--output speech.mp3실시간 세션
쿼리 문자열에 모델을, Authorization 헤더에 API 키를 포함하여 WebSocket을 엽니다. 선택한 실시간 모델에 대해 문서화된 이벤트 형식을 유지하고, 세션이 완료되면 소켓을 닫으세요.
세션은 최대 1시간 동안 지속됩니다. 이후 서버는 코드 1000과 사유 session_timeout으로 소켓을 닫습니다. 단일 메시지는 최대 32 MiB까지 가능하며, 더 큰 메시지는 코드 1009와 함께 소켓을 닫습니다. grok-voice-think-fast-2.0과 같은 일부 실시간 모델은 오디오 프레임과 세션 업데이트만 허용합니다. 텍스트 입력 항목은 unsupported_realtime_text_input 오류를 반환하며 코드 1008로 소켓을 닫습니다.
이 가이드는 WebSocket 하위 집합만 다룹니다. TokenLab은 현재 OpenAI Realtime REST 클라이언트 시크릿, 번역 클라이언트 시크릿, 통화(Calls) 또는 레거시 베타 세션 관리 엔드포인트를 제공하지 않습니다.
아래 서버 측 예제를 위해 ws를 설치하고 TOKENLAB_REALTIME_MODEL을 /v1/realtime을 지원하는 현재 모델로 설정하세요. 서버 환경에 TOKENLAB_API_KEY를 제공하세요. 이름만으로는 실시간 지원이 설정되지 않습니다.
npm install wsimport WebSocket from 'ws';
const model = process.env.TOKENLAB_REALTIME_MODEL;
const apiKey = process.env.TOKENLAB_API_KEY;
if (!model || !apiKey) throw new Error('Set TOKENLAB_REALTIME_MODEL and TOKENLAB_API_KEY');
const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', model);
const socket = new WebSocket(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
socket.on('message', (event) => console.log(event.toString()));
socket.on('error', (error) => console.error(error.message));
process.once('SIGINT', () => socket.close(1000, 'Client stopped'));안전하게 진행 상황 표시하기
- 새로고침 시 동일한 요청을 다시 실행하는 대신 생성된 오디오 파일을 저장하세요.
- 전사 및 번역의 경우, API 호출이 동기식이더라도 업로드 및 처리 상태를 표시하세요.
- 실시간의 경우, 닫기 이벤트를 처리하고 사용자가 새 세션을 시작한 후에만 재연결하세요.
- 오디오 텍스트 입력에 API 키, 개인 URL 또는 계정 시크릿을 넣지 마세요.