# 快速接入

> 从创建API密钥到获取转录文本，用cURL、Python或Node.js处理视频链接和本地文件。

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

先创建API密钥，再提交视频链接或文件，最后获取转录文本。API地址为`https://api.transcript1.com`，调用时将密钥放在`Authorization`请求头中。

## 1. 注册并创建API密钥

打开[注册页](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/zh/docs/sources-and-options)。API会从链接识别平台，无需填写`platform`。

调用`POST /v1/transcriptions`并传入视频URL。加上查询参数`wait=60`，API会最多等待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/zh/docs/sources-and-options)。

## 3. 获取转录文本

先看HTTP状态码，确认是否还需要等待：

- `200`：任务已结束，`status`为`completed`、`failed`或`canceled`，不一定代表转录成功。
- `202`：任务还在处理。继续调用`GET /v1/transcriptions/:id?wait=60`，每次最多等待60秒，直到`status`变为最终状态。

转录成功后会返回以下JSON，示例省略了部分内容：

```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`。例如，获取SRT字幕：

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

这里调用的是`GET /v1/transcriptions/:id?format=srt`。只有`status`为`completed`时，接口才返回指定格式的文本或字幕；任务尚未完成时，仍返回JSON对象供查询状态。

## 4. 上传本地文件

本地音频或视频不超过95MB时，可以用`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
```

文件超过95MB时，改用分块上传，最大支持2GB，中断后可以续传。操作步骤见[文件上传](https://transcript1.com/zh/docs/uploads)。

## 继续接入

- [来源与转录设置](https://transcript1.com/zh/docs/sources-and-options)：选择字幕或AI转录，设置说话人分离和语言。
- [文件上传](https://transcript1.com/zh/docs/uploads)：直接提交文件，或分块上传大文件。
- [Webhook](https://transcript1.com/zh/docs/webhooks)：通过带签名的回调接收转录结束通知。
- [MCP服务器](https://transcript1.com/zh/docs/mcp)：将transcript1接入Claude、ChatGPT、Cursor、VS Code或Claude Code。
- [API接口文档](https://transcript1.com/zh/docs/api-reference)：查询各接口及其参数。