# Bắt đầu với transcript1

> Lấy khóa API, gửi link video hoặc file và đọc transcript đầu tiên. Có ví dụ cURL, Python và Node.js để chạy thử.

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

Bạn cần khóa API để gọi `https://api.transcript1.com`. Hướng dẫn này đi từ tạo khóa, gửi video hoặc file đến đọc transcript. Mỗi request đều gửi khóa qua header `Authorization`.

## 1. Tạo tài khoản và khóa API

Vào [/signup](https://transcript1.com/signup) và đăng ký bằng email, Google hoặc Microsoft. Xác minh email để nhận 60 phút miễn phí; tài khoản dùng Google hoặc Microsoft nhận ngay khi đăng ký. Đây là ưu đãi một lần cho mỗi tài khoản, không cần thẻ thanh toán.

Trong bảng điều khiển, mở [“API keys”](https://transcript1.com/dashboard/account/tokens) tại `/dashboard/account/tokens` để tạo khóa. Sao chép ngay: khóa có tiền tố `t1_` và chỉ hiện một lần. Lưu khóa vào biến môi trường `TRANSCRIPT1_API_KEY`:

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

## 2. Gửi link video

Bạn có thể gửi link từ YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn và Snapchat. API nhận diện nền tảng qua link nên không bắt buộc truyền `platform`. Ví dụ dưới đây dùng YouTube. Trước khi dùng nền tảng khác, kiểm tra [các dạng link và giới hạn](https://transcript1.com/vi/docs/sources-and-options) cho video công khai đã ghi hình.

Gọi `POST /v1/transcriptions` với URL video. Thêm `wait=60` vào query để chờ tối đa 60 giây trong cùng request. Response tạo job chưa kèm transcript: ví dụ Python gọi tiếp `GET /v1/transcriptions/:id?wait=60` để lấy nội dung. Với Node.js SDK, bạn chỉ cần đặt `TRANSCRIPT1_API_KEY`; SDK tự chờ và lấy transcript.

### 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

Lưu đoạn code thành `index.mjs`, rồi chạy `node index.mjs`. Nếu muốn dùng đuôi `.js`, đặt `"type": "module"` trong `package.json`.

```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);
```

Mặc định, transcript1 tìm phụ đề bằng ngôn ngữ gốc trên YouTube, X, TikTok, Bluesky, Dailymotion và LinkedIn. Nếu không có bản dùng được, AI sẽ chuyển audio thành văn bản. Cơ chế xử lý phụ đề của YouTube và X không đổi. Ngoài YouTube, phụ đề chỉ có mốc thời gian theo đoạn, không có mốc thời gian từng từ.

Muốn bỏ qua phụ đề, chọn `source=stt` hoặc bật nhận diện người nói. Ngược lại, chế độ `captions` (chỉ phụ đề) không tải audio và không chạy STT. Không phải video nào cũng có phụ đề phù hợp; xem [cách chọn nguồn transcript](https://transcript1.com/vi/docs/sources-and-options) trước khi chọn chế độ này.

## 3. Lấy transcript

Đọc mã HTTP để biết có cần chờ tiếp hay không:

- `200`: job đã kết thúc trong thời gian chờ. Kiểm tra `status`: có thể là `completed`, `failed` hoặc `canceled`.
- `202`: job còn đang xử lý. Gọi `GET /v1/transcriptions/:id?wait=60` để chờ thêm tối đa 60 giây. Tiếp tục gọi cho đến khi `status` chuyển sang một trong các trạng thái kết thúc.

Khi job có trạng thái `completed`, response có dạng sau. Ví dụ đã lược bớt nội dung:

```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." }
    ]
  }
}
```

Lấy toàn bộ văn bản từ `transcript.text`. Nếu cần từng đoạn, đọc `transcript.segments`; `start` và `end` là thời điểm bắt đầu và kết thúc, tính bằng giây.

Để tải văn bản thuần hoặc file phụ đề, chọn `text`, `srt` hoặc `vtt`:

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

Ví dụ trên gọi `GET /v1/transcriptions/:id?format=srt`. API chỉ trả file theo định dạng bạn chọn khi job đã `completed`. Nếu chưa xong, API vẫn trả object JSON để bạn kiểm tra trạng thái.

## 4. Gửi file từ máy

Với file audio hoặc video tối đa 95 MB, gửi trực tiếp bằng một request `multipart/form-data`:

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

File lớn hơn cần chia thành các chunk, tối đa 2 GB. Nếu tải lên bị ngắt, bạn có thể gửi tiếp các chunk còn thiếu. Xem [hướng dẫn tải file lên](https://transcript1.com/vi/docs/uploads).

## Tìm hiểu thêm

- [Link video và tùy chọn](https://transcript1.com/vi/docs/sources-and-options): chọn phụ đề hay AI, bật nhận diện người nói và đặt ngôn ngữ.
- [Tải file lên](https://transcript1.com/vi/docs/uploads): gửi một request hoặc chia file thành các chunk.
- [Webhook](https://transcript1.com/vi/docs/webhooks): nhận request có chữ ký khi job hoàn tất.
- [Kết nối MCP server](https://transcript1.com/vi/docs/mcp): dùng transcript1 trong Claude, ChatGPT, Cursor, VS Code và Claude Code.
- [Tài liệu API](https://transcript1.com/vi/docs/api-reference): tra cứu endpoint và tham số.