개요

Voice File Job은 생성 → 업로드 → upload-complete 호출 → 상태 확인 → 결과 조회 순서로 처리해요. upload-complete는 클라이언트가 직접 호출하며 S3 이벤트는 사용하지 않아요.

​

필요한 것

• 워크스페이스 사용자 키 또는 워크스페이스 시스템 키: Authorization: Bearer {id}.{secret}
• Tiro 관리자가 해당 워크스페이스의 Voice File Job 정책을 활성화해야 해요.
• 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 가져오기

​

웹훅으로 상태 변경을 받고 작업을 삭제하려면 어떻게 하나요?

폴링 대신 작업 상태 변경을 받으려면 voice_file_job.created, voice_file_job.completed, voice_file_job.failed, voice_file_job.deleted를 구독하세요. 웹훅 페이로드는 작업 메타데이터만 포함해요. Tiro는 전사 본문을 웹훅으로 전송하지 않으므로 GET /v1/external/voice-file/jobs/{jobId}/transcript로 가져오세요. 어떤 상태의 작업이든 DELETE /v1/external/voice-file/jobs/{jobId}로 삭제할 수 있어요. Tiro는 오디오와 생성된 결과를 삭제하고, 삭제 뒤 도착하는 처리 콜백은 무시해요.

​

오디오와 전사 데이터는 어떻게 보관되나요?

Tiro는 업로드한 오디오를 객체 저장소에, 전사·번역 결과를 서비스 데이터베이스에 저장해요. API에는 자동 보관 기간을 설정하는 기능이 없으므로, 데이터가 더 필요하지 않으면 DELETE /v1/external/voice-file/jobs/{jobId}를 호출하세요. 워크스페이스 사용자 키는 자신이 만든 작업에, 워크스페이스 시스템 키는 같은 워크스페이스의 모든 작업에 접근해요. 작업을 삭제하면 오디오와 전사·번역 결과도 지워져 다시 조회할 수 없어요.

​

폴링 전략 (권장)

• 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

​

파일 제한 및 요구사항

​

지원하는 오디오 포맷

지원하는 파일 형식은 다음과 같아요. 오디오 포맷: 비디오 포맷 (오디오 추출):

​

파일 크기 및 길이 제한

​

처리 시간 예상치

파일 길이별 예상 처리 시간은 다음과 같아요.

​

Paragraph Summary 기능

Paragraph Summary는 전사 또는 번역 결과를 단락별로 요약해요.

​

동작 방식

전사 텍스트를 단락으로 나눈 뒤 각 단락의 요약을 만들어요. 번역을 요청했다면 번역 결과에도 같은 과정을 적용해요. 요약은 전사·번역 처리가 끝난 뒤 비동기로 생성돼요.

​

시퀀스

전체 예시는 단계별 튜토리얼을 참고하세요.