# 用音频转文字 API处理录音和视频文件

> 通过音频转文字 API上传音频或视频，获取带时间戳的转录文本，可选说话人分离。95MB以内可单次上传，分块上传支持最大2GB，每分钟1积分。

Canonical: https://transcript1.com/zh/features/yinpin-zhuan-wenzi-api
Language: zh-Hans
Last updated: 2026-10-19

音频转文字 API支持上传音频或视频，返回带时间戳的转录文本和每段的语言，也可开启说话人分离。95MB以内用单次请求；更大的文件分块上传，最大2GB，中断后可以继续。

- 单次请求支持最大95MB
- 分块上传支持最大2GB，可中断续传
- 转录结束24小时后删除音视频文件

## 先看文件大小，再选上传方式

### 常用音视频格式都能上传

支持mp3、wav、m4a、flac、ogg、opus、mp4、mov、webm和mkv。文件必须包含音轨。

### 小文件直接发一次请求

95MB以内的文件，用multipart/form-data提交到POST /v1/transcriptions即可。

### 大文件分块传，中断后接着传

先创建上传任务，再按返回的方案发送约8MiB的分块，最后确认上传完成。最大支持2GB，不必因连接中断就从头再来。

### 录音时长也有上限

AI转录支持最长5小时。超过时会返回media_too_long，不扣积分；文件够小也不代表时长符合要求。

### 原文件和文字分开保留

任务进入最终状态24小时后删除上传的音视频文件。转录文本会保留，直到主动删除。

## 单次请求上传，不必实现分块逻辑

把文件放在名为file的multipart字段里，可同时传入language、diarize、source和webhook_url。[单次上传文档](https://transcript1.com/zh/docs/uploads#one-shot-upload)给出了完整请求，也可用[Webhook](https://transcript1.com/zh/features/zhuanlu-webhook)接收完成或失败通知。

服务器上已经有录音文件时，这种方式容易接入。发送实际文件内容，不要把本地路径塞进JSON；multipart的boundary交给HTTP客户端生成。

空文件或不支持的扩展名会在校验时出错，反复提交没有帮助。先检查输入，再决定是否重试。

文件大小和录音时长要分别检查。压缩录音可能不到95MB，却超过5小时；短视频也可能因为分辨率高而超出单次上传上限。按字节大小选上传方式，再单独检查时长。

### cURL

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

## 创建上传任务，拿到分块方案和Token

上传最大2GB的文件时，先提交文件名和大小。接口会返回分块方案，以及仅供这次上传使用的X-Upload-Token。完整流程见[分块上传文档](https://transcript1.com/zh/docs/uploads#chunked-upload)。

每块的序号、偏移量和大小都以接口返回为准。客户端按指定字节范围读取文件，最后一块可能更短，不要自行假设每块都一样大。

二进制PUT请求使用上传Token认证。Token有效期为1小时，只能用于这次上传，不能代替通用API密钥。

创建上传任务时使用固定的Idempotency-Key。Token过期后，带相同的key和参数重发创建请求，就能为原上传获取新Token。每次断线都新建任务，会留下不必要的记录，也更难核对进度。

### 创建分块上传任务

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Idempotency-Key: interview-2026-10-13" \
  -H "Content-Type: application/json" \
  -d '{"upload":{"filename":"interview.m4a","size":48210334,"mime_type":"audio/mp4"}}'
```

## 补齐缺少的分块，再提交转录

带上传Token把每块PUT到指定地址，全部发送后再确认上传完成。transcript1会检查分块是否齐全，通过后才把转录加入队列。相关接口见[上传接口说明](https://transcript1.com/zh/docs/api-reference#uploads)。

断线后先调用GET /v1/transcriptions/:id/upload，把received_chunks与原方案对照，只补传缺少的块。重复发送会替换原块，请求体仍须符合计划中的大小。

分块请求返回401时，先检查Token是否过期，不必重新生成音视频文件。确认完成时若返回409 upload_incomplete，按提示补齐缺少的序号。

加入队列后，通过转录接口查询进度，或等待Webhook。界面要分开展示“文件上传进度”和“转录进度”，文件传完不等于文字已经生成。

### 发送分块并确认上传完成

```
curl -X PUT "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/chunks/0" \
  -H "X-Upload-Token: t1u_..." \
  -H "Content-Type: application/octet-stream" \
  --data-binary @chunk-0.bin

curl -X POST "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/complete" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY"
```

## 分清上传、处理和文件保留时间

awaiting_upload表示等待文件，不是正在转录。流程依次是传输文件、校验上传、处理音视频。确认完成后如果连接断开，先查询原任务，不要直接假定还要再提交一次确认。

每个团队最多可有20个未完成的上传任务。24小时内没有完成上传，系统会取消任务并删除分块。转录进入最终状态后，上传的音视频文件还会保留24小时，然后删除。

转录文本会保留到主动删除。如果产品需要以后播放原音频，请自行保存原文件，不能把转录服务当作长期文件存储。

上传接通后，还要考虑用户怎样检查和使用文字。[音频转文字指南](https://transcript1.com/zh/features/yinpin-zhuan-wenzi)介绍录音准备和校对；[访谈转录指南](https://transcript1.com/zh/use-cases/fangtan-luyin-zhuan-wenzi)介绍参与者对应和保留出处的分析方式。

## 常见问题

### 支持哪些音视频文件？

支持mp3、wav、m4a、flac、ogg、opus、mp4、mov、webm和mkv，文件里必须有音轨。其他扩展名会返回422 unsupported_media。

### 最大能上传多大的文件？

单次上传最大95MB，分块上传最大2GB，实际额度可能受套餐限制。超过限制会返回413 media_too_large。

### 文件和转录文本分别保留多久？

任务进入最终状态24小时后删除音视频文件，转录文本保留到主动删除。上传任务如果24小时内没有完成，会被取消，分块也会删除。

### 上传文件也能区分谁在说话吗？

可以。设置diarize=true，每段发言会带上Speaker 1、Speaker 2等标签。上传文件始终使用AI语音转文字。

## 相关内容

- [说话人分离](https://transcript1.com/zh/features/shuohuaren-fenli-zhuanlu)
- [音频转文字](https://transcript1.com/zh/features/yinpin-zhuan-wenzi)
- [上传音频和视频 （文档）](https://transcript1.com/zh/docs/uploads)
- [视频转文字](https://transcript1.com/zh/features/shipin-zhuan-wenzi)