개요

이 페이지는 Voice File Job을 생성하고, 오디오를 업로드하고, 결과를 가져오는 전체 흐름을 설명해요. 현재 구현은 클라이언트가 직접 호출하는 upload-complete 방식을 사용해요(S3 이벤트 없음).

​

필요한 것

• API key: Authorization: Bearer {id}.{secret}
• transcriptLocaleHints: 최대 1개 (선택)
  • 제공하지 않으면 언어가 자동으로 감지돼요
• translationLocales: 최대 5개 (선택)

​

전체 체크리스트

1. Job 생성 → { id, uploadUri } 수신
2. uploadUri에 오디오 업로드
3. PUT /v1/external/voice-file/jobs/{jobId}/upload-complete 호출
4. 완료될 때까지 job 상태 폴링
5. transcript 및 (선택적으로) translations 가져오기
6. 콘텐츠를 더 잘 이해하기 위해 paragraph summary 가져오기

​

폴링 전략 (권장)

• GET /v1/external/voice-file/jobs/{jobId}를 exponential backoff로 폴링해요
  • 1~2s 간격으로 시작해서 4s, 8s, 최대 30s까지 늘려요
  • 중단 조건:
    • 성공: status = COMPLETED
    • 실패: status = FAILED
  • 성공 후:
    • 항상 transcript를 가져와요: GET /v1/external/voice-file/jobs/{jobId}/transcript
    • translations를 요청했다면: GET /v1/external/voice-file/jobs/{jobId}/translations 또는 locale별 endpoint
    • paragraph summary 가져오기:
      • transcript의 경우: GET /v1/external/voice-file/jobs/{jobId}/transcript/paragraph-summary
      • translations의 경우: GET /v1/external/voice-file/jobs/{jobId}/translations/{locale}/paragraph-summary

​

파일 제한 및 요구사항

​

지원하는 오디오 포맷

업계 표준 STT 역량을 기반으로 Tiro는 다음 포맷을 지원해요: 오디오 포맷: 비디오 포맷 (오디오 추출):

​

파일 크기 및 길이 제한

​

처리 시간 예상치

처리 시간은 긴 파일에 대해 병렬 처리로 최적화돼요:

​

Paragraph Summary 기능

Paragraph Summary 기능은 오디오 콘텐츠를 지능적으로 요약해서, transcript나 translation을 이해하기 쉬운 단락 단위 요약으로 나눠줘요.

​

동작 방식

1. Transcript 처리: 전사가 완료되면 텍스트가 CompositeTextSplitter를 사용해 논리적 단락으로 자동 분할돼요
2. Summary 생성: 각 단락이 ParagraphSummarizer를 거쳐 간결한 요약으로 만들어져요
3. Translation 통합: translations를 요청하면 각 locale의 번역된 콘텐츠를 기반으로 요약이 다시 생성돼요
4. 비동기 처리: 요약 생성은 transcript/translation 완료 후 비동기로 이루어져요

​

시퀀스

직접 해보고 싶으세요? 단계별 튜토리얼에서 전체 흐름을 따라가 보세요. 업로드, 폴링, 그리고 첫 transcript 가져오기까지 끝까지 안내해요.