API 연동

첫 번째 전사

전사는 백그라운드에서 진행됩니다. 작업 생성 요청은 즉시 응답하므로 결과가 준비될 때까지 상태를 확인하세요.

1. 1

   작업 생성

   직접 접근할 수 있는 공개 미디어 URL을 POST /transcripts로 전송하고 반환된 id를 보관하세요.

2. 2

   진행 상황 확인

   status가 complete 또는 error가 될 때까지 15–30초마다 GET /transcripts/{id}를 폴링하세요.

3. 3

   전사 결과 사용

   data에서 JSON을 읽거나, SRT 또는 VTT를 요청했다면 export_url에서 파일을 다운로드하세요.

작업 상태

그 밖의 상태는 처리 중으로 간주하세요. 새로운 중간 상태가 추가될 수 있습니다.

인증

모든 요청의 Authorization 헤더에 생성 시 표시된 API 키를 그대로 전송하세요.

Authorization: <your api key>

Bearer 접두사를 추가하지 마세요.

새 키는 tp_live_로 시작합니다. 전체 키는 생성할 때 한 번만 표시됩니다. 키를 분실하면 해당 키를 폐기하고 새 키를 만드세요. 폐기된 키는 즉시 작동하지 않습니다.

활성 구독과 필요한 권한이 있는 API 키가 필요합니다.

전사 생성

공개 URL에 있는 미디어 파일의 전사 작업을 시작합니다. 작업이 대기열에 등록되면 status: "initializing"과 함께 응답합니다.

Taption은 파일을 직접 다운로드합니다. Google Drive나 Dropbox 미리보기 페이지와 같은 공유 페이지 링크는 사용할 수 없습니다.

media_urlstring필수

미디어 파일을 직접 다운로드할 수 있는 링크입니다.

최대 2048자

extensionstring필수

미디어 파일 형식입니다.

mp3wavm4aaacflacwmaopusmp4

languagestring필수

미디어에서 사용하는 언어의 태그입니다. 언어 참조를 확인하세요.

언어 태그 보기

namestring

전사의 표시 이름입니다. 기본값은 `media_url`의 파일 이름이며, 긴 이름은 200자로 잘립니다.

최대 200자

export_typestring

출력 형식입니다. 기본값인 json은 파싱된 전사 내용을 data에 반환합니다. srt와 vtt는 export_url에 파일 링크를 반환합니다.

jsonsrtvtt

기본값: json

max_charinteger

자막 구간당 최대 문자 수입니다. 중국어, 일본어, 한국어, 광둥어의 기본값은 `16`이며 다른 언어는 `65`입니다. 1-200 범위를 벗어난 값은 무시되고 기본값이 적용됩니다.

1–200

응답

전사 조회

전사의 현재 상태와 결과를 조회합니다. 작업이 진행 중일 때는 15–30초마다 폴링하세요.

json을 지정하거나 내보내기 형식을 생략하면 완료된 결과가 data에 표시됩니다. srt 또는 vtt는 export_url에서 파일을 다운로드하세요.

idstring필수

POST /transcripts에서 반환된 전사 ID입니다.최대 256자

응답

전사 객체

생성 및 상태 조회 요청은 JSON 객체를 반환합니다. 필드에는 작업 정보와 준비된 출력 결과가 포함됩니다.

idstring

전사 ID입니다. `GET /transcripts/{id}`와 함께 사용하세요.

statusstring

작업의 현재 상태입니다: `initializing`, `transcribing`, `complete`, `error`. 다른 값은 처리 중으로 간주하세요.

dataJSON

json 또는 export_type 생략 시 결과가 준비되면 파싱된 JSON 내보내기 내용을 반환합니다. 그 외에는 빈 문자열입니다.

export_urlstring

srt 또는 vtt 내보내기 파일의 다운로드 링크입니다. 준비되기 전에는 비어 있습니다. json 또는 export_type을 생략한 상태 응답에서는 제외됩니다.

messagestring

현재 상태에 대한 추가 정보입니다. `transcribing` 중에는 `ANALYZING` 또는 `FINALIZING` 같은 진행 단계가 표시될 수 있습니다. `status`가 `error`이면 실패 내용을 설명합니다. 사람이 읽기 위한 내용이므로 파싱하지 마세요.

error_codestring

제출 제한 오류를 나타내는 선택적 기계 판독 코드입니다.

limitinteger

HTTP 429에 포함되는 해당 계정의 적용 제한값입니다.

오류 및 재시도

HTTP 상태 코드로 다음 동작을 결정하세요. message 필드는 사람이 읽기 위한 내용이며 문구가 변경될 수 있습니다.

API 응답에는 X-Request-Id 헤더가 포함됩니다. 요청에 관해 지원팀에 문의할 때 이 값을 함께 알려 주세요.