무료로 시작하기

문서빠르게 시작하기

빠르게 시작하기

API 키 발급부터 첫 스크립트 확인까지, cURL, Python, Node.js 예제로 영상 링크와 파일을 텍스트로 변환해 보세요.

API 주소는 https://api.transcript1.com이에요. Authorization 헤더에 API 키를 넣어 호출하세요. 먼저 키를 발급받고, 영상이나 파일로 변환 작업을 시작한 뒤 스크립트를 가져와 볼게요.

1. 가입하고 API 키 발급받기

/signup에서 이메일, Google 또는 Microsoft 계정으로 가입하세요. 이메일 인증을 마치면 60분을 무료로 쓸 수 있어요. Google이나 Microsoft로 가입하면 바로 받아요. 무료 분량은 계정당 한 번만 제공하며, 카드 등록은 필요 없어요.

대시보드의 “API keys” 페이지(/dashboard/account/tokens)에서 키를 만드세요. t1_로 시작하는 키는 생성할 때 한 번만 보여요. 바로 복사해 TRANSCRIPT1_API_KEY 환경 변수에 설정하세요.

export TRANSCRIPT1_API_KEY="t1_..."

YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn, Snapchat의 영상 링크를 보낼 수 있어요. 공개된 녹화 영상 중 어떤 링크를 쓸 수 있는지는 지원 링크와 변환 옵션에서 확인하세요. 플랫폼은 URL로 알아내므로 platform을 따로 넣지 않아도 돼요. 여기서는 YouTube 링크로 시작해요.

POST /v1/transcriptions에 영상 URL을 보내세요. 쿼리에 wait=60을 붙이면 서버가 최대 60초 동안 작업이 끝나기를 기다린 뒤 응답해요. 다만 생성 응답에는 스크립트 본문이 없어요. Python 예제처럼 GET /v1/transcriptions/:id?wait=60을 별도로 호출해야 해요. Node.js SDK를 쓰면 TRANSCRIPT1_API_KEY를 읽고 스크립트가 준비될 때까지 기다리는 과정을 알아서 처리해요.

cURL

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

Python

import os
import requests
 
headers = {"Authorization": f"Bearer {os.environ['TRANSCRIPT1_API_KEY']}"}
response = requests.post(
    "https://api.transcript1.com/v1/transcriptions?wait=60",
    headers=headers,
    json={"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
)
response.raise_for_status()
transcription = response.json()
while True:
    transcription = requests.get(
        f"https://api.transcript1.com/v1/transcriptions/{transcription['id']}?wait=60",
        headers=headers,
    ).json()
    if transcription["status"] in ("completed", "failed", "canceled"):
        break
 
if transcription["status"] == "completed":
    print(transcription["transcript"]["text"])
else:
    print(transcription["status"], transcription["error"])

Node.js

아래 코드를 index.mjs로 저장한 뒤 node index.mjs로 실행하세요. .js 파일로 저장하려면 package.json에 "type": "module"을 설정하세요.

// npm i @transcript1/sdk
import { Transcript1 } from '@transcript1/sdk';
 
const t1 = new Transcript1();
const transcription = await t1.transcribe('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
console.log(transcription.transcript.text);

기본 설정에서는 YouTube, X, TikTok, Bluesky, Dailymotion, LinkedIn의 자막을 먼저 확인해요. 영상 원본 언어의 자막을 사용할 수 없으면 AI로 음성을 텍스트로 변환해요. YouTube와 X의 기존 자막 처리 방식은 바뀌지 않아요. YouTube 외 플랫폼의 자막에는 세그먼트별 타임스탬프만 있고 단어별 타임스탬프는 없어요. 영상에 따라 사용할 자막 자체가 없을 수도 있어요.

source=stt를 지정하거나 화자 분리를 켜면 자막 대신 음성을 변환해요. captions(자막만) 모드는 오디오를 다운로드하지 않고 STT도 실행하지 않아요. 자세한 선택 기준은 지원 링크와 변환 옵션을 확인하세요.

3. 스크립트 가져오기

HTTP 상태 코드로 작업이 끝났는지 확인할 수 있어요.

  • 200: 대기 시간 안에 작업이 끝났어요. 성공 여부는 최종 상태인 completed, failed, canceled로 구분하세요.
  • 202: 아직 처리 중이에요. GET /v1/transcriptions/:id?wait=60으로 최대 60초씩 기다리며 조회하세요. status가 최종 상태가 될 때까지 반복하면 돼요.

변환을 마친 작업의 응답이에요. 필요한 부분만 추렸어요.

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

전체 스크립트는 transcript.text에서 읽으세요. 구간별 텍스트와 타임스탬프는 transcript.segments에 있어요. 각 세그먼트의 시작과 끝을 나타내는 start, end는 초 단위예요.

텍스트나 자막 파일로 받으려면 text, srt, vtt 중 원하는 형식을 지정하세요.

curl "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD?format=srt" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY"

위의 GET /v1/transcriptions/:id?format=srt 호출은 completed 상태일 때 SRT를 반환해요. 아직 완료되지 않았다면 형식을 지정해도 JSON 객체를 반환하므로 현재 상태를 확인할 수 있어요.

4. 파일로 변환 시작하기

컴퓨터에 있는 오디오나 영상 파일은 multipart/form-data로 보내세요. 95MB까지는 요청 한 번으로 업로드할 수 있어요.

curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F [email protected]

95MB보다 큰 파일은 청크로 나눠 보내세요. 최대 2GB까지 업로드할 수 있고, 전송이 끊기면 이어서 올릴 수 있어요. 방법은 파일 업로드에 있어요.

이어서 살펴보기

최근 업데이트 2026년 10월 14일