---
title: "비디오와 오디오를 위한 트랜스크립트 API"
description: "YouTube, TikTok, Instagram, LinkedIn, Twitter/X 링크를 하나의 REST API로 타임스탬프가 있는 트랜스크립트로 바꿉니다. 자막을 먼저 쓰고, 없으면 AI가 처리합니다."
canonical: "https://transcript.im/ko/api"
markdown: "https://transcript.im/ko/api.md"
---

# 비디오와 오디오를 위한 트랜스크립트 API

YouTube, TikTok, Instagram, LinkedIn, Twitter/X 링크를 하나의 REST API로 타임스탬프가 있는 트랜스크립트로 바꿉니다. 자막을 먼저 쓰고, 없으면 AI가 처리합니다.

## 모래밭

- [표준 HTML](https://transcript.im/ko/api)
- [Markdown](https://transcript.im/ko/api.md)


transcript.im은 제품을 구동하는 것과 같은 추출 파이프라인을 버전이 지정된 트랜스크립트 API로 제공합니다. 비디오나 오디오 URL을 보내면 JSON 또는 일반 텍스트로 타임스탬프가 있는 텍스트를 돌려받으며, 플랫폼은 자동으로 감지됩니다. 기존 자막이 있으면 먼저 사용하고, 비디오에 자막이 없으면 AI가 오디오를 전사하며 결과는 비동기로 전달됩니다.

- 하나의 `url`이 전체 링크나 짧은 링크를 받아 YouTube, TikTok, Instagram, LinkedIn, Twitter/X를 감지합니다. YouTube는 비디오 id만 있어도 인식하며, 이미 아는 소스라면 `platform`과 `externalId`로 지정할 수 있습니다.
- 자막을 먼저 사용하고, 비디오에 자막이 없으면 AI가 말소리를 전사합니다. 로컬 파일 업로드는 항상 음성 인식으로 처리됩니다.
- `format=json`은 타임스탬프가 있는 세그먼트를, `format=text`는 붙여 넣기 좋은 일반 텍스트를 반환합니다.
- 배치 추출은 URL 목록, 재생목록, 채널을 지원합니다.
- 배치 내보내기는 txt, csv, json, srt, vtt, zip을 지원하고, 저장된 트랜스크립트는 txt, srt, vtt, json, md로 다운로드됩니다.
- 저장된 트랜스크립트는 계정 라이브러리에 보관되며, YouTube 탐색은 검색, 동영상, 채널, 업로드, 재생목록, 자막을 지원합니다.
- 전체 계약은 OpenAPI 문서로 공개됩니다.

## transcript.im API가 하는 일

transcript.im API는 공개된 비디오나 오디오 링크를 제품이 읽고, 저장하고, 검색하거나 모델에 넘길 수 있는 타임스탬프 트랜스크립트로 바꿉니다. URL을 보내면 API가 플랫폼을 판별하고, 크리에이터가 이미 가진 자막 트랙을 찾아 모든 줄에 타임스탬프가 붙은 텍스트를 돌려줍니다. 비디오에 자막이 전혀 없어도 API는 오류로 멈추지 않고 말소리에 대한 AI 전사로 넘어가, 같은 요청이 계속 텍스트를 만들어 냅니다.

이 한 가지 동작이 바로 트랜스크립트 추출 API의 핵심입니다. 다운로더, 자막 스크레이퍼, 음성-텍스트 서비스를 서로 이어 붙일 필요가 없습니다. API는 링크마다 실제로 동작하는 가장 저렴한 소스를 고르고, 실제로 말한 내용에 타임스탬프를 맞추며, 어떤 언어로 응답했는지 알려 줍니다. 이미 있는 트랜스크립트는 즉시 돌아오고, 음성 인식이 필요한 비디오는 작업으로 넘겨져 긴 녹음이 요청을 붙잡고 있지 않습니다.

- 한 번의 요청, 실제 텍스트 — 링크를 판별해 타임스탬프 트랜스크립트 세그먼트나 일반 텍스트를 반환합니다.
- 자막 먼저, AI 다음 — 크리에이터의 트랙이 있으면 쓰고, 없으면 오디오를 전사합니다.
- ASR은 기본이 비동기 — job id로 긴 전사를 막히지 않고 조회할 수 있습니다.
- 언어 인식 — 언어 우선순위를 요청하고 API가 판별한 언어를 다시 읽습니다.
- 플랫폼 독립적 — 호출자는 비디오가 어디에 호스팅되는지 몰라도 됩니다.

## 다섯 플랫폼을 위한 하나의 트랜스크립트 API

### YouTube

공개된 YouTube 동영상, Short, 라이브 녹화를 위한 트랜스크립트로, 크리에이터의 자막을 먼저 쓰고 자막이 없으면 AI 전사를 씁니다. YouTube는 검색, 동영상, 채널, 업로드, 재생목록, 자막이라는 완전한 탐색 표면을 갖춘 유일한 플랫폼으로, 트랜스크립트 자체와 함께 사용할 수 있습니다. 채널의 밀린 영상이나 재생목록은 타임스탬프 트랜스크립트의 배치가 되고, 단일 링크는 검색할 수 있는 읽기 쉬운 텍스트로 돌아옵니다.

### TikTok

공개된 TikTok 동영상을 위한 트랜스크립트로, 자막을 먼저 쓰고 음성 인식을 대안으로 씁니다. 비디오 링크를 붙여 넣으면 재활용하거나 번역하거나 인용할 수 있는 깔끔한 타임스탬프 텍스트로 말한 내용을 읽을 수 있습니다. 같은 호출이 짧은 클립과 더 긴 업로드를 모두 처리하므로, 트렌드, 튜토리얼, 카메라 앞에서 말하는 영상이 모두 텍스트로 돌아옵니다.

### Instagram

공개된 Instagram Reels와 동영상 게시물을 위한 트랜스크립트입니다. Instagram에는 읽을 자막 트랙이 없어 추출은 비동기 음성 인식으로 처리됩니다. 링크를 보내고 작업을 조회한 뒤 준비되면 텍스트를 받습니다. 그래서 플랫폼이 말을 텍스트로 공개한 적이 없어도 Reel을 인용하고 검색할 수 있습니다.

### LinkedIn

공개된 LinkedIn 동영상 게시물을 위한 트랜스크립트로, 자막을 먼저 쓰고 음성 인식을 대안으로 씁니다. 결과는 타임스탬프와 함께 돌아오므로 발표, 제품 클립, 녹화한 미팅이 인용하고 재사용할 수 있는 검색 가능한 텍스트가 됩니다. 웨비나 녹음에서 논지를 뽑아내거나 창업자의 업데이트를 편집할 초안으로 바꿀 수 있습니다.

### Twitter/X

공개된 X 동영상 게시물을 위한 트랜스크립트입니다. X에는 읽을 자막 트랙이 없어 추출은 비동기 음성 인식으로 처리됩니다. 링크를 보내고 작업을 조회한 뒤 검색할 수 있는 타임스탬프 텍스트를 받습니다. 게시물이 수정되거나 삭제되기 전에 영상을 정확히 인용하거나 말한 내용을 보관할 수 있습니다.

## 트랜스크립트 요청이 흐르는 방식

한 번의 호출이 링크나 업로드한 파일을 입력에서 트랜스크립트까지 데려가며, API는 어떤 경로를 택했는지 알려 줍니다.

- 소스 보내기 — `url`을 보내고, 이미 알고 있다면 `platform`과 `externalId`를 넘기거나, 같은 엔드포인트에 파일을 `multipart/form-data`로 업로드합니다.
- 자막 일치 얻기 — 비디오가 목록에 있는 언어의 자막을 가지고 있으면 트랜스크립트가 응답으로 돌아옵니다.
- 언어 불일치 처리 — 자막은 있지만 목록에 맞는 것이 없으면 요청이 AI 전사로 이어지고 job id와 함께 `202`를 반환합니다. `availableLanguages`와 함께 오는 `404`는 호출자에게 음성 인식이 허용되지 않을 때만 반환됩니다.
- ASR 강제 또는 대안 — 명시적인 `asr` 항목, 자막 트랙이 전혀 없는 비디오, 업로드한 파일은 ASR 작업을 시작하고 job id를 반환합니다.
- 조회 또는 스트리밍 — `GET /v1/transcript/job/{id}`로 작업이 성공하거나 실패할 때까지 읽거나, `/events` 스트림을 구독해 서버 전송 진행 상황을 받습니다. 작업 조회는 실패한 작업에도 `200`을 반환하므로 `status` 필드로 분기합니다.
- 결과 읽기 — 완료된 트랜스크립트에는 판별된 언어, 길이, 타임스탬프 세그먼트와 요청 시 제목, 작성자, 게시일 같은 메타데이터가 담깁니다.
- 안전하게 반복 — 이미 추출한 트랜스크립트는 새 작업을 시작하지 않고 캐시에서 제공되므로 같은 소스를 다시 요청할 수 있습니다.
- 먼저 조사 — `GET /v1/transcript/info`가 소스를 판별하고 추출을 결정하기 전에 제공할 수 있는 언어를 나열합니다.

같은 엔드포인트가 캐시 적중과 새 추출을 모두 처리하므로, 통합 코드는 소스에 따라 분기하지 않습니다. 항상 소스를 보내고 받은 상태에 반응하면 됩니다. 자막 일치는 트랜스크립트를 바로 반환하고, 언어 불일치는 AI 전사로 이어져 job id와 함께 `202`를 반환하며, 정말로 없는 자산이나 허용되지 않은 대안은 `404`를 반환합니다. 텍스트가 준비되면 모든 경로가 같은 트랜스크립트 형태를 반환합니다.

## 배치 추출과 내보내기

실제 작업은 비디오 하나에서 멈추는 일이 드물어, API는 배치를 URL 목록, 재생목록, 채널로 받습니다. 각 배치는 자체 합계 — 대기 중인 항목 수, 성공한 수, 실패한 수 — 를 추적하고 항목을 페이지 단위로 반환하므로, 긴 채널이 하나의 거대한 페이로드로 오지 않습니다.

- 세 가지 배치 형태 — `POST /v1/batch`는 보내는 본문에 따라 URL 목록, 재생목록, 채널을 받습니다.
- 독립적인 상태 — 실패한 링크는 따로 표시되고 나머지 배치를 절대 버리지 않습니다. 실패한 항목은 `/retry`로 재시도할 수 있습니다.
- 페이지 단위 항목 — `GET /v1/batch/{batchId}`로 배치를 읽고, 반환된 페이지 토큰을 따라 나머지 항목을 가져옵니다.
- 실시간 진행 — 조회할 때마다 갱신된 카운트가 반환되어, 호출자가 긴 실행이 얼마나 끝났는지 보여 줄 수 있습니다.
- 원하는 형식으로 내보내기 — 완료된 배치를 `/export`에서 `txt`, `csv`, `json`, `srt`, `vtt`, `zip`으로 다운로드합니다.

자막 파이프라인이라면 `srt`와 `vtt` 내보내기를 편집기나 플레이어에 바로 넣을 수 있습니다. 아카이브라면 `csv`, `json`, `zip`이 녹음 라이브러리 전체를 하나의 코퍼스로 검색 가능하게 유지합니다. 형식이 단일 트랜스크립트 응답과 맞춰져 있어, 결과 하나를 처리하는 소비자는 이미 배치를 읽을 줄 압니다.

## 계정 라이브러리에 저장된 트랜스크립트

추출과 저장은 별개입니다. 트랜스크립트는 저장되는 순간 계정 라이브러리의 일부가 되고, 라이브러리는 나중에 추출을 다시 실행하지 않고 읽고, 검색하고, 다운로드하고, 삭제하는 곳입니다.

- 저장된 콘텐츠 나열 — `GET /v1/library/transcripts`가 계정의 트랜스크립트, 배치 기록, 실패 이력 행을 페이지 단위로 넘기며, 검색, 플랫폼·언어 필터, 정렬을 지원합니다.
- 항목 하나 읽기 — `GET /v1/library/transcripts/{platform}/{externalId}`가 플랫폼과 외부 id로 저장된 트랜스크립트를, 또는 지정한 언어로 반환합니다.
- 다운로드 — `/download` 경로가 저장된 트랜스크립트를 `txt`, `srt`, `vtt`, `json`, `md`로 내보냅니다.
- 관련 콘텐츠 — `/related` 경로가 같은 채널의 다른 저장 항목을 나열합니다.
- 삭제 — `DELETE`가 다른 사람의 복사본은 건드리지 않고 라이브러리에서 항목을 제거합니다.
- 계정 범위 읽기 — 라이브러리 요청은 계정이 저장한 것만 반환하고 새 추출을 절대 시작하지 않으므로, 저장된 트랜스크립트를 다시 보는 것은 읽기이지 또 다른 작업이 아닙니다.

## 트랜스크립트 너머의 YouTube 탐색

YouTube는 API가 트랜스크립트 주변의 질문에도 답하는 플랫폼이며, YouTube Data API와 같은 리소스 이름을 사용합니다.

- 검색 — `GET /v1/youtube/search`가 쿼리로 동영상, 채널, 재생목록을 찾고 커서 페이지 결과를 반환합니다.
- 동영상 — `GET /v1/youtube/videos`가 자막 사용 가능 여부를 포함한 동영상 세부 정보를 반환합니다.
- 채널 — `GET /v1/youtube/channels`가 id나 `@handle`로 채널을 판별합니다.
- 채널 업로드 — `GET /v1/youtube/channels/{channelId}/videos`가 채널의 업로드를 순회합니다.
- 재생목록 항목 — `GET /v1/youtube/playlists/{playlistId}/items`가 재생목록을 순회합니다.
- 자막 — `GET /v1/youtube/captions`가 동영상의 자막 트랙 메타데이터와 자막 텍스트를 반환합니다. 음성 인식 작업은 절대 시작하지 않습니다. `requiresAsync`를 보고하면 `POST /v1/transcript`를 호출해 전사를 실행하세요.

탐색은 무엇을 전사할지 답하고, 추출은 무엇을 말했는지 답합니다. 둘을 분리해 두면 먼저 검색하고 나열한 다음, 고른 링크만 트랜스크립트나 배치 요청으로 보낼 수 있습니다.

## 프로덕션 사용을 위해 설계

표면은 의도적으로 작게 유지했고, 서비스에 중요한 부분은 추측이 아니라 문서로 남겼습니다.

- 하나의 자격 증명 — Bearer 토큰으로 보낸 API 키로, 또는 스크립트나 서버에서 `X-API-Key`로 인증합니다.
- 범위가 지정된 키 — 호출자에게 필요한 범위만 부여하며, `transcripts`와 `batches`가 추출과 배치 작업을 담당합니다.
- 구조화된 오류 — 추출과 검증 실패는 안정적인 `code`와 읽을 수 있는 `message`를 가진 오류 객체를 반환합니다. 인증(401)과 속도 제한(429) 응답은 더 단순한 평면 오류 본문을 씁니다.
- 실행 가능한 한도 — 속도 제한에 걸린 요청은 `Retry-After`와 함께 `429`를 반환하고, 성공한 응답에는 `X-RateLimit-*` 헤더가 붙어 클라이언트가 올바르게 물러설 수 있습니다.
- 공개된 계약 — 전체 OpenAPI 문서가 API를 뒷받침하므로 클라이언트를 생성하거나, 서버를 모의하거나, 실제 응답을 스키마에 맞춰 검증할 수 있습니다.
- 에이전트를 위한 형제 — 호출자가 서비스가 아니라 AI 클라이언트라면 같은 계정과 도구를 transcript.im MCP 서버에서 사용할 수 있습니다.

## 관련 도구

- [API 문서](/docs)
- [OpenAPI 문서](/docs/openapi.json)
- [MCP 서버](/ko/mcp)
- [Agent Skills](/ko/skills)
- [YouTube 트랜스크립트 생성기](/ko/youtube-transcript)
- [YouTube 동영상 요약기](/ko/youtube-video-summarizer)
- [YouTube 자막 생성기](/ko/youtube-subtitle-generator)
- [YouTube 자막 다운로더](/ko/youtube-subtitle-downloader)
- [YouTube 채널 트랜스크립트](/ko/youtube-channel-transcript)
- [YouTube 재생목록 트랜스크립트](/ko/youtube-playlist-transcript)
## 트랜스크립트 API 자주 묻는 질문

### transcript.im API란 무엇인가요?

transcript.im API는 공개된 비디오나 오디오 링크를 타임스탬프 트랜스크립트로 바꾸는 REST 표면으로, 기존 자막을 먼저 쓰고 비디오에 자막이 없으면 AI 전사를 사용합니다.

### transcript.im API는 어떤 플랫폼을 지원하나요?

보낸 링크에서 플랫폼을 감지해 YouTube, TikTok, Instagram, LinkedIn, Twitter/X의 트랜스크립트를 추출합니다. YouTube, TikTok, LinkedIn은 자막을 먼저 쓰고 음성 인식을 대안으로 사용하며, Instagram과 X는 자막 트랙이 없어 바로 음성 인식으로 갑니다.

### 비디오에 자막이 없으면 어떻게 되나요?

비디오에 자막 트랙이 전혀 없으면 API가 ASR 작업을 시작하고 job id를 반환합니다. 트랜스크립트가 준비될 때까지 그 작업을 조회하므로, 요청이 음성 인식 때문에 막히지 않습니다.

### 로컬 오디오나 비디오 파일을 전사할 수 있나요?

네. `POST /v1/transcript`는 URL 대신 `file` 파트가 있는 `multipart/form-data` 본문을 받습니다. 업로드한 파일은 바로 음성 인식으로 가므로 `202` 작업을 반환하며, 대기 예산 안에 끝나면 `200` 결과를 반환합니다.

### transcript.im API가 텍스트와 함께 타임스탬프를 반환할 수 있나요?

네. JSON 응답에는 타임스탬프 세그먼트가 담기고, 텍스트 응답은 줄마다 타임스탬프 접두사를 유지할 수 있어 한 줄이 말해진 시점으로 돌아갈 수 있습니다.

### 특정 언어로 트랜스크립트를 요청하려면 어떻게 하나요?

`asr`와 `asr-<code>` 항목을 포함해 쉼표로 구분한 언어 우선순위 목록을 보냅니다. 자막 일치는 바로 반환되고, 자막은 있지만 목록에 맞는 것이 없으면 요청이 AI 전사로 이어져 `202` 작업을 반환합니다. 사용 가능한 언어와 함께 오는 `404`는 음성 인식이 허용되지 않을 때만 반환됩니다.

### 비동기 트랜스크립트가 언제 준비되는지 어떻게 아나요?

같은 자격 증명으로 `GET /v1/transcript/job/{id}`를 성공 또는 실패를 보고할 때까지 조회하거나, `GET /v1/transcript/job/{id}/events`를 구독해 서버 전송 업데이트를 받습니다. 작업 조회는 실패한 작업에도 `200`을 반환하므로 HTTP 코드 대신 `status`와 `error` 필드를 읽으세요.

### transcript.im API는 배치 추출을 지원하나요?

네. 배치는 URL 목록, 재생목록, 채널을 받고 각 항목의 상태를 추적하며 항목을 페이지 단위로 반환합니다.

### 어떤 내보내기 형식을 다운로드할 수 있나요?

완료된 배치는 `txt`, `csv`, `json`, `srt`, `vtt`, `zip`으로 내보내고, 저장된 트랜스크립트 하나는 `txt`, `srt`, `vtt`, `json`, `md`로 다운로드합니다.

### 저장된 트랜스크립트는 어디에 있나요?

계정 라이브러리가 저장된 트랜스크립트와 배치 기록이 있는 곳이며 `/v1/library` 아래에 있습니다. 나열, 읽기, 다운로드, 관련, 삭제 경로를 제공하고, 읽기는 계정 범위로 제한되며 새 추출을 절대 시작하지 않습니다.

### YouTube 자막 엔드포인트는 무엇을 반환하나요?

`GET /v1/youtube/captions`는 동영상의 자막 트랙 메타데이터와 자막 텍스트를 함께 반환합니다. 음성 인식 작업은 절대 시작하지 않으며, `requiresAsync`를 보고하면 `POST /v1/transcript`를 호출해 전사를 실행하세요.

### transcript.im API는 오류와 속도 제한을 어떻게 알리나요?

추출과 검증 오류는 `code`와 `message`가 있는 객체를 씁니다. 인증은 평면 `401`을, 속도 제한은 `Retry-After`와 `X-RateLimit-*` 헤더가 있는 평면 `429`를 반환해 클라이언트가 올바르게 물러설 수 있습니다.

## 제품에 트랜스크립트를 추가하세요

API 키를 만들고 비디오 링크나 로컬 파일을 보낸 뒤 트랜스크립트를 JSON 또는 일반 텍스트로 읽으세요.

- [API 키 만들기](/app/account/api-keys)
- [문서 읽기](/docs)