파일 하나를 한 요청으로 보내기
multipart 요청의 file 필드에 녹음을 넣으세요. language, diarize, source, webhook_url도 함께 보낼 수 있어요. 업로드 예제와 완료 웹훅을 참고하세요.
서버에 작은 파일이 있다면 이 방식으로 시작하세요. multipart boundary는 HTTP 클라이언트가 설정하게 두세요. JSON에 로컬 경로를 적는 게 아니라 파일 내용을 보내야 해요. 빈 파일이나 지원하지 않는 확장자는 입력부터 고쳐야 해요.
파일 크기와 녹음 길이는 따로 확인하세요. 압축한 파일은 95MB보다 작아도 5시간을 넘을 수 있어요. 반대로 짧은 고화질 영상은 크기 제한에 걸릴 수 있어요. 업로드 방식은 바이트 크기로 고르고, 재생 시간도 확인하세요.
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F language=auto큰 파일은 업로드를 예약한 뒤 나눠 보내기
파일 이름과 크기로 업로드를 예약하세요. 2GB까지 보낼 수 있어요. 응답에 각 청크의 전송 정보와 이번 업로드에만 쓰는 X-Upload-Token이 담겨요. 전체 순서는 청크 업로드 문서를 확인하세요.
응답에 담긴 청크 인덱스, 시작 바이트, 크기를 그대로 따르세요. 마지막 청크는 더 작을 수 있어요. 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 문서에 있어요.
이어 올리기 전에 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시간 뒤 삭제해요. 스크립트는 직접 삭제할 때까지 남으니, 나중에 오디오 재생도 제공하려면 원본은 따로 보관하세요.
업로드 화면을 만든다면 음성 파일 준비와 검토를, 연구용 앱이라면 인터뷰 녹취록 활용을 참고하세요. 파일을 옮기는 것뿐 아니라, 사용자가 발언을 확인하고 활용할 흐름도 함께 준비하세요.