# 녹음과 동영상 파일을 위한 음성 텍스트 변환 API

> 음성 텍스트 변환 API에 오디오·동영상 파일을 보내세요. 타임스탬프를 받고 화자 분리도 선택할 수 있어요. 95MB까지 한 요청으로, 2GB까지 나눠 올려요. 오디오 1분당 1크레딧이에요.

Canonical: https://transcript1.com/ko/features/eumseong-tekseuteu-byeonhwan-api
Language: ko
Last updated: 2026-10-19

음성 텍스트 변환 API로 오디오나 동영상 파일을 보내세요. 타임스탬프와 구간별 언어를 받고, 필요하면 화자도 나눌 수 있어요. 95MB까지 한 요청으로 보내고, 더 큰 파일은 2GB까지 나눠 올리세요. 중간에 끊겨도 이어서 올릴 수 있어요.

- 95MB까지 한 요청으로 업로드
- 2GB까지 나눠 올리고 중단 지점부터 재개
- 처리 종료 24시간 뒤 원본 파일 삭제

## 파일 크기에 맞춰 업로드 방식 고르기

### 오디오와 동영상을 같은 API로

mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm, mkv를 받아요. 동영상에도 오디오 트랙이 있어야 해요.

### 작은 파일은 한 번에

95MB까지는 POST /v1/transcriptions에 multipart/form-data로 보내면 돼요. file 필드에 파일을 넣으세요.

### 큰 파일은 나눠서

2GB까지는 업로드를 예약하고 약 8MiB씩 보낸 뒤 완료를 요청해요. 연결이 끊기면 빠진 부분만 이어서 올리세요.

### 녹음 길이는 5시간까지

AI 텍스트 변환은 최대 5시간까지 가능해요. 더 긴 녹음은 media_too_long 오류가 나고 크레딧은 차감하지 않아요.

### 원본과 스크립트는 따로 보관

처리가 최종 상태에 도달하면 24시간 뒤 업로드 파일을 삭제해요. 스크립트는 직접 삭제할 때까지 남아요.

## 파일 하나를 한 요청으로 보내기

multipart 요청의 file 필드에 녹음을 넣으세요. language, diarize, source, webhook_url도 함께 보낼 수 있어요. [업로드 예제](https://transcript1.com/ko/docs/uploads#one-shot-upload)와 [완료 웹훅](https://transcript1.com/ko/features/badasseugi-wephuk)을 참고하세요.

서버에 작은 파일이 있다면 이 방식으로 시작하세요. multipart boundary는 HTTP 클라이언트가 설정하게 두세요. JSON에 로컬 경로를 적는 게 아니라 파일 내용을 보내야 해요. 빈 파일이나 지원하지 않는 확장자는 입력부터 고쳐야 해요.

파일 크기와 녹음 길이는 따로 확인하세요. 압축한 파일은 95MB보다 작아도 5시간을 넘을 수 있어요. 반대로 짧은 고화질 영상은 크기 제한에 걸릴 수 있어요. 업로드 방식은 바이트 크기로 고르고, 재생 시간도 확인하세요.

### cURL

```
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@interview.m4a \
  -F language=auto
```

## 큰 파일은 업로드를 예약한 뒤 나눠 보내기

파일 이름과 크기로 업로드를 예약하세요. 2GB까지 보낼 수 있어요. 응답에 각 청크의 전송 정보와 이번 업로드에만 쓰는 X-Upload-Token이 담겨요. 전체 순서는 [청크 업로드 문서](https://transcript1.com/ko/docs/uploads#chunked-upload)를 확인하세요.

응답에 담긴 청크 인덱스, 시작 바이트, 크기를 그대로 따르세요. 마지막 청크는 더 작을 수 있어요. X-Upload-Token은 파일 조각을 PUT으로 보낼 때 쓰며 1시간 동안 유효해요. 일반 API 키 대신 다른 작업에 쓸 수는 없어요.

예약 요청을 재시도할 수 있다면 Idempotency-Key를 고정해 두세요. 토큰이 만료됐을 때 같은 키와 같은 파라미터로 예약을 다시 요청하면 기존 업로드의 새 토큰을 받아요. 연결이 끊길 때마다 새 업로드를 예약할 필요는 없어요.

### 업로드 예약 요청

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Idempotency-Key: interview-2026-10-13" \
  -H "Content-Type: application/json" \
  -d '{"upload":{"filename":"interview.m4a","size":48210334,"mime_type":"audio/mp4"}}'
```

## 빠진 청크를 채우고 업로드 완료 요청하기

각 URL에 업로드 토큰을 넣어 청크를 PUT으로 보내세요. 모두 보낸 뒤 완료를 요청하면 파일을 검증하고 변환 대기열에 넣어요. 진행 상황과 완료 요청은 [업로드 API 문서](https://transcript1.com/ko/docs/api-reference#uploads)에 있어요.

이어 올리기 전에 GET /v1/transcriptions/:id/upload의 received_chunks를 원래 전송 정보와 비교하세요. 빠진 청크만 보내면 돼요. 같은 청크를 다시 보내면 덮어쓰며, 크기는 처음 안내한 값과 같아야 해요. 401 오류라면 토큰 만료부터 확인하세요.

완료 요청에서 409 upload_incomplete가 나오면 누락된 인덱스를 확인해 채우세요. 대기열에 들어간 다음에는 변환 상태를 조회하거나 웹훅을 기다리세요. 화면에서도 파일 전송 진행률과 텍스트 변환 진행 상황을 따로 보여주세요.

### 청크 전송과 업로드 완료 요청

```
curl -X PUT "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/chunks/0" \
  -H "X-Upload-Token: t1u_..." \
  -H "Content-Type: application/octet-stream" \
  --data-binary @chunk-0.bin

curl -X POST "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/complete" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY"
```

## 파일 전송 완료와 텍스트 변환 완료는 달라요

awaiting_upload는 예약만 해 둔 상태예요. 업로드 완료 요청이 성공해야 변환 대기열에 들어가요. 전송, 검증, 변환 순서로 상태를 보여주세요. 완료 요청 뒤 연결이 끊기면 먼저 기존 작업을 조회하세요.

팀당 진행 중인 업로드 예약은 최대 20개예요. 24시간 안에 업로드를 마치지 않으면 예약을 취소하고 청크를 삭제해요. 처리까지 끝난 원본 파일은 최종 상태에 도달한 시점부터 24시간 뒤 삭제해요. 스크립트는 직접 삭제할 때까지 남으니, 나중에 오디오 재생도 제공하려면 원본은 따로 보관하세요.

업로드 화면을 만든다면 [음성 파일 준비와 검토](https://transcript1.com/ko/features/eumseong-tekseuteu-byeonhwan)를, 연구용 앱이라면 [인터뷰 녹취록 활용](https://transcript1.com/ko/use-cases/inteobyu-nokchwirok-jakseong)을 참고하세요. 파일을 옮기는 것뿐 아니라, 사용자가 발언을 확인하고 활용할 흐름도 함께 준비하세요.

## 자주 묻는 질문

### 어떤 파일을 보낼 수 있나요?

mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm, mkv를 받아요. 오디오 트랙이 있어야 해요. 다른 확장자는 422 unsupported_media 오류가 나요.

### 파일 크기 제한은 얼마인가요?

한 요청으로는 95MB까지, 청크 업로드로는 2GB까지 보낼 수 있어요. 요금제에 따라 한도가 더 낮을 수 있어요. 제한을 넘으면 413 media_too_large 오류가 나요.

### 업로드한 파일은 언제 삭제되나요?

처리가 최종 상태에 도달하면 24시간 뒤 원본을 삭제해요. 업로드를 24시간 안에 마치지 못해도 예약을 취소하고 청크를 삭제해요. 스크립트는 직접 삭제할 때까지 남아요.

### 파일에서도 화자를 나눌 수 있나요?

네. diarize=true로 보내면 Speaker 1, Speaker 2처럼 나눠요. 업로드한 파일은 항상 AI로 음성을 텍스트로 바꿔요.

## 함께 보면 좋은 페이지

- [화자 분리](https://transcript1.com/ko/features/hwaja-insik-api)
- [음성을 텍스트로](https://transcript1.com/ko/features/eumseong-tekseuteu-byeonhwan)
- [파일 업로드 (문서)](https://transcript1.com/ko/docs/uploads)
- [동영상을 텍스트로](https://transcript1.com/ko/features/dongyeongsang-tekseuteu-byeonhwan)