개요

Voice File Job API는 엔터프라이즈 플랜에서 제공하는 기능이에요. 개인 플랜과 팀 플랜에서는 활성화할 수 없어요. Voice File Job은 생성 → 업로드 → upload-complete 호출 → 상태 확인 → 결과 조회 순서로 처리해요. upload-complete는 클라이언트가 직접 호출하며 S3 이벤트는 사용하지 않아요.

​

필요한 것

• 계정 API Key 또는 워크스페이스 API Key: Authorization: Bearer {id}.{secret}
• scope를 지정한 키라면 작업 생성·업로드 완료·삭제에는 voice_file_job:write, 조회에는 voice_file_job:read가 필요해요. write는 read를 포함하고, scope를 지정하지 않은 키는 모든 작업을 할 수 있어요.
• 엔터프라이즈 플랜 계약과 함께 Voice File Job 정책이 활성화된 워크스페이스가 필요해요.
• 워크스페이스에 묶이지 않은 계정 API Key와 조직 API Key는 작업을 만들 때 workspaceGuid를 보내야 해요.
• transcriptLocaleHints: 최대 1개 (선택)
  • 제공하지 않으면 언어가 자동으로 감지돼요
• translationLocales: 최대 5개 (선택)

​

전체 체크리스트

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

​

작업 완료는 어떻게 확인하나요? 웹훅 (권장)

작업 완료는 웹훅으로 받으세요. Tiro가 처리를 끝내면 voice_file_job.completed 또는 voice_file_job.failed 이벤트를 보내요. 처리에는 파일 길이에 따라 보통 45초~18분이 걸리고, 대기열 상황에 따라 더 길어질 수 있어요. 웹훅을 구독하면 그동안 상태를 반복해서 조회하지 않아도 돼요.

• voice_file_job.completed와 voice_file_job.failed를 구독하세요. 워크스페이스 Webhook은 그 워크스페이스에서 만든 모든 작업의 이벤트를 받고, 조직 Webhook은 조직에 속한 모든 워크스페이스에서 만든 작업의 이벤트를 받아요. 노트와 달리 폴더 공유 범위는 적용되지 않아요. 계정 Webhook은 본인이 계정 API Key로 만든 작업 중 Webhook을 등록한 워크스페이스의 작업 이벤트만 받아요. 등록 방법은 Webhook 개요를 참고하세요.
• job ID는 이벤트의 data.resourceId에, 결과는 data.resource.status에 COMPLETED 또는 FAILED로 들어 있어요. 전체 필드는 Event Structure에서 확인하세요.
• 웹훅 페이로드에는 작업 메타데이터만 있어요. 전사 본문은 GET /v1/external/voice-file/jobs/{jobId}/transcript로 가져오세요.
• Tiro는 재시도까지 모두 실패한 이벤트를 다시 보내지 않아요. 예상 처리 시간이 지났는데 이벤트가 없으면 GET /v1/external/voice-file/jobs/{jobId}로 상태를 확인하세요.

작업 생성과 삭제를 추적하려면 voice_file_job.created와 voice_file_job.deleted도 구독하세요.

​

폴링 전략 (웹훅을 받을 수 없을 때)

웹훅 endpoint를 운영할 수 없거나 웹훅 이벤트가 오지 않을 때는 job 상태를 폴링하세요.

• 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

​

작업이 FAILED여도 전사를 받을 수 있나요?

받을 수 있는 경우가 있어요. 요약 생성만 실패해도 작업은 FAILED가 돼요. 이때 GET /v1/external/voice-file/jobs/{jobId} 응답의 transcriptAvailable이 true이면 GET /v1/external/voice-file/jobs/{jobId}/transcript로 전사를 가져올 수 있어요. 실패 이유는 errorMessage에 있어요. voice_file_job.failed 웹훅의 data.resource.errorMessage에도 같은 값이 들어 있어요.

​

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

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

​

파일 제한 및 요구사항

​

지원하는 오디오 포맷

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

​

파일 크기 및 길이 제한

​

처리 시간 예상치

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

​

Paragraph Summary 기능

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

​

동작 방식

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

​

시퀀스

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