# 빠르게 시작하기

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

Canonical: https://transcript1.com/ko/docs/getting-started
Language: ko
Last updated: 2026-10-14

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

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

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

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

```bash
export TRANSCRIPT1_API_KEY="t1_..."
```

## 2. 영상 링크로 변환 시작하기

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

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

### cURL

```bash
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

```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"`을 설정하세요.

```javascript
// 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도 실행하지 않아요. 자세한 선택 기준은 [지원 링크와 변환 옵션](https://transcript1.com/ko/docs/sources-and-options)을 확인하세요.

## 3. 스크립트 가져오기

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

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

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

```json
{
  "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` 중 원하는 형식을 지정하세요.

```bash
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까지는 요청 한 번으로 업로드할 수 있어요.

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

95MB보다 큰 파일은 청크로 나눠 보내세요. 최대 2GB까지 업로드할 수 있고, 전송이 끊기면 이어서 올릴 수 있어요. 방법은 [파일 업로드](https://transcript1.com/ko/docs/uploads)에 있어요.

## 이어서 살펴보기

- [지원 링크와 변환 옵션](https://transcript1.com/ko/docs/sources-and-options): 자막과 AI 텍스트 변환 선택, 화자 분리와 언어 설정.
- [파일 업로드](https://transcript1.com/ko/docs/uploads): 파일을 한 번에 보내거나 청크로 나눠 보내는 방법.
- [웹훅 연동](https://transcript1.com/ko/docs/webhooks): 작업이 끝나면 서명된 알림 받기.
- [MCP 서버 연결](https://transcript1.com/ko/docs/mcp): Claude, ChatGPT, Cursor, VS Code, Claude Code와 연동하기.
- [API 레퍼런스](https://transcript1.com/ko/docs/api-reference): 엔드포인트별 파라미터 확인하기.