# 자막이 없어도 쓸 수 있는 YouTube Transcript API

> YouTube Transcript API에 링크를 보내고 JSON, 텍스트, SRT, VTT로 받아보세요. 자막이 있으면 가져오고, 없으면 AI가 음성을 텍스트로 바꿔요. 오디오 1분당 1크레딧이에요.

Canonical: https://transcript1.com/ko/features/youtube-transcript-api
Language: ko
Last updated: 2026-10-19

YouTube Transcript API에 영상 링크를 보내면 JSON, 텍스트, SRT, VTT로 스크립트를 받을 수 있어요. 쓸 수 있는 자막이 있으면 가져오고, 없으면 AI가 음성을 텍스트로 바꿔요.

- 자막을 먼저 확인하고, 없으면 AI로 변환
- 자막과 AI 모두 오디오 1분당 1크레딧
- watch, youtu.be, Shorts, embed 링크 지원

## 앱에 필요한 스크립트 가져오기

### 쓰던 영상 링크 그대로

watch, youtu.be, Shorts, embed, live 링크를 받아요. www가 있어도 없어도 같은 영상으로 인식해요.

### 유튜브 자막 API로 활용

source=auto에서는 업로더가 올린 자막을 먼저 골라요. 없으면 자동 생성 자막을 확인하고, 자동 번역 자막은 쓰지 않아요.

### 자막이 없을 때는 음성으로

쓸 수 있는 자막이 없으면 AI 텍스트 변환으로 넘어가요. 자막과 관계없이 음성으로 변환하려면 source=stt로 보내세요.

### 어디서 가져온 텍스트인지 확인

transcript_source를 보면 youtube_captions인지 speech_to_text인지 알 수 있어요. 앱에서도 두 경우를 구분해 보여줄 수 있어요.

### 변환 방식이 달라도 같은 요금

영상 길이를 분 단위로 올림해 1분당 1크레딧을 써요. 변환에 실패하거나 취소하면 크레딧을 차감하지 않아요.

## 서버나 스크립트에서 영상 링크 보내기

API 키와 영상 URL로 POST 요청을 보내세요. Python을 비롯해 HTTP 요청을 보낼 수 있는 환경이면 돼요. wait=60을 붙이면 최대 60초 동안 기다려요. 요청 필드는 [API 문서](https://transcript1.com/ko/docs/api-reference#create-a-transcription)에서 확인하세요.

대시보드에서 API 키를 만들고 서버나 스크립트에서 사용하세요. 요청이 성공하면 바로 변환 ID를 저장하세요. 기다리는 시간이 끝났다고 변환까지 실패한 건 아니에요. 같은 영상을 다시 보내지 말고 GET /v1/transcriptions/:id로 확인하세요.

처리 중에는 queued, fetching, transcribing 상태를 볼 수 있어요. completed면 스크립트를 읽고, failed면 오류를 처리하세요. 네트워크 지연이나 영상 접근 오류를 빈 스크립트로 처리하지 않도록 상태를 구분해 두세요.

### cURL

```
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'
```

## transcript\_source로 자막과 AI 구분하기

자막에서 가져온 스크립트에는 자막 종류도 함께 담겨요. billed_minutes는 영상 길이를 분 단위로 올림한 값이에요. 전체 필드는 [응답 객체 문서](https://transcript1.com/ko/docs/api-reference#the-transcription-object)에서 확인하세요.

출처가 중요한 앱이라면 transcript_source와 caption_kind를 함께 저장하세요. 업로더가 올린 자막은 원문을 유지하고 단어별 타임스탬프는 없어요. 자동 생성 자막에는 단어 시작 시간이, AI 텍스트 변환에는 단어 시작·종료 시간과 신뢰도가 있어요.

segments에는 각 구간의 시작과 끝이 초 단위로 들어 있어요. 재생 위치로 이동하거나 메모에 근거를 붙일 때 쓰세요. 단어별 정보가 필요한 화면에서만 include=words를 추가하면 돼요. 아래 JSON은 구조를 설명하는 예시로, 예제 영상의 실제 발언은 아니에요.

### JSON 응답 예시(일부)

```
{
  "id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
  "status": "completed",
  "transcript_source": "youtube_captions",
  "caption_kind": "auto_generated",
  "language": "en",
  "billed_minutes": 4,
  "transcript": {
    "text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
    "segments": [
      { "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." }
    ]
  }
}
```

## 자막 원문이 필요한지, 음성 변환이 필요한지

source의 기본값은 auto예요. captions(자막만)을 고르면 쓸 수 있는 자막이 없을 때 no_captions로 끝나고 크레딧은 차감하지 않아요. stt는 항상 음성으로 변환해요. 조합별 동작은 [source 옵션 문서](https://transcript1.com/ko/docs/sources-and-options#source)를 확인하세요.

게시된 자막 원문이 꼭 필요하면 captions를, 음성을 새로 변환하거나 화자를 나누려면 stt를 고르세요. auto에 diarize=true를 더하면 자막이 있어도 음성으로 변환해요. captions와 화자 분리를 함께 요청하면 오류가 나요. 화자 옵션을 임의로 무시하지 않아요.

language를 지정하면 그 언어에 맞는 자막을 찾아요. auto에서는 영상의 원래 언어를 기준으로 골라요. 자동 번역 자막은 사용하지 않아요. 음성 변환에 언어 힌트를 줘도 다른 언어로 번역해 주는 건 아니에요.

### 음성 변환을 지정한 요청 본문

```
{
  "platform": "youtube",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "source": "stt"
}
```

## 다시 보내기 전에 오류와 기존 작업 확인하기

먼저 [오류 코드](https://transcript1.com/ko/docs/errors)를 확인하세요. 비공개·연령 제한 영상이나 진행 중인 라이브는 같은 요청을 반복해도 해결되지 않아요. no_captions라면 음성 변환을 써도 되는지 결정하세요. 아직 처리 중이라면 저장한 ID로 상태를 다시 읽으세요.

생성 요청을 재시도할 때는 [Idempotency-Key 규칙](https://transcript1.com/ko/docs/api-reference#idempotency)을 따르세요. 최근 스크립트 재사용은 별도 옵션으로, 같은 영상과 같은 옵션을 보낸 이전 요청을 찾아요. 캐시에서 가져왔어도 새 작업이면 과금할 수 있어요. 완료된 작업을 ID로 다시 읽는 데는 크레딧이 들지 않아요.

같은 생성 API로 [TikTok](https://transcript1.com/ko/features/tiktok-jamak-chuchul), [Instagram](https://transcript1.com/ko/features/instagram-rilseu-tekseuteu-byeonhwan) 등 지원하는 영상 링크도 보낼 수 있어요. YouTube, X, TikTok, Bluesky에서는 쓸 수 있는 자막이 없으면 음성으로 변환해요. 플랫폼마다 가능한 조합이 다르니 입력 화면을 만들 때 [지원 소스와 옵션](https://transcript1.com/ko/docs/sources-and-options)을 확인하세요.

## 자주 묻는 질문

### 영상에 자막이 없어도 되나요?

네. 기본값인 source=auto에서는 쓸 수 있는 자막이 없으면 AI가 음성을 텍스트로 바꿔요. 자막이 없는 영상은 실패 처리하고 싶다면 source=captions로 보내세요.

### 어떤 YouTube 링크를 보낼 수 있나요?

watch, youtu.be, Shorts, embed, live 링크를 받을 수 있어요. 채널 주소나 영상이 지정되지 않은 재생목록 주소는 422 invalid_url 오류가 나요.

### 비공개 영상도 가져올 수 있나요?

아니요. 공개 또는 일부 공개 영상만 가져올 수 있어요. 비공개·연령 제한 영상과 진행 중인 라이브는 처리할 수 없어요. 직접 가진 녹화 파일이 있다면 파일로 업로드하세요.

### 비용은 얼마나 드나요?

자막과 AI 모두 오디오 1분당 1크레딧이며, 분 단위로 올림해요. 가입 후 이메일을 인증하면 60분을 한 번 무료로 받아요. 카드는 필요 없어요.

### Python 패키지 youtube-transcript-api와 같은 건가요?

아니요. transcript1은 호스팅형 REST API예요. Python에서는 API 키를 넣어 HTTP 요청을 보내면 돼요.

## 함께 보면 좋은 페이지

- [타임스탬프와 자막](https://transcript1.com/ko/features/srt-pail-mandeulgi)
- [파일 변환 API](https://transcript1.com/ko/features/eumseong-tekseuteu-byeonhwan-api)
- [웹훅](https://transcript1.com/ko/features/badasseugi-wephuk)
- [영상으로 글 쓰기](https://transcript1.com/ko/use-cases/yeongsang-beullogeu-geul-byeonhwan)