小鱼开发
202 lines
5.0 KiB
Markdown
202 lines
5.0 KiB
Markdown
# 火山引擎音视频字幕 API 开发文档
|
|
|
|
> 更新日期: 2026-04-09
|
|
> 官方文档: https://www.volcengine.com/docs/6561/80907
|
|
|
|
---
|
|
|
|
## 产品简介
|
|
|
|
火山引擎音视频字幕服务提供两种能力：
|
|
|
|
1. **音视频字幕生成** - 自动识别音频中的语音/歌词，生成带时间轴的字幕
|
|
2. **自动字幕打轴** - 为已有字幕文本自动配上时间轴
|
|
|
|
---
|
|
|
|
## 基础信息
|
|
|
|
| 项目 | 内容 |
|
|
|------|------|
|
|
| 基础 URL | `https://openspeech.bytedance.com/api/v1/vc` |
|
|
| 鉴权 Header | `Authorization: Bearer; {token}` |
|
|
| 文件限制 | ≤200MB, 支持 WAV/M4A/MP3/MP4/MOV/OGG |
|
|
|
|
---
|
|
|
|
## API 接口
|
|
|
|
### 1. 音视频字幕生成
|
|
|
|
#### 提交任务
|
|
```http
|
|
POST /submit?appid={appid}&language=zh-CN&use_punc=True
|
|
Content-Type: application/json
|
|
Authorization: Bearer; {token}
|
|
|
|
{"url": "https://example.com/audio.mp3"}
|
|
```
|
|
|
|
**关键参数:**
|
|
- `language` - 语言: `zh-CN`, `en-US`, `ja-JP`, `ko-KR`, `es-MX`, `ru-RU`, `fr-FR`, `yue`, `wuu`, `nan`, `ug`
|
|
- `caption_type` - 识别类型: `auto`(默认), `speech`, `singing`
|
|
- `use_punc` - 自动标点: `True`, `False`
|
|
- `use_itn` - 数字转换: `True`(中文数字转阿拉伯数字)
|
|
- `words_per_line` - 每行字数, 默认 46
|
|
- `max_lines` - 每屏行数, 默认 1
|
|
|
|
#### 查询结果
|
|
```http
|
|
GET /query?appid={appid}&id={task_id}&blocking=1
|
|
Authorization: Bearer; {token}
|
|
```
|
|
|
|
**响应:**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "Success",
|
|
"duration": 5.32,
|
|
"utterances": [
|
|
{
|
|
"text": "识别文本",
|
|
"start_time": 0,
|
|
"end_time": 3197,
|
|
"words": [
|
|
{"text": "单字", "start_time": 0, "end_time": 208}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### 2. 自动字幕打轴
|
|
|
|
#### 提交任务
|
|
```http
|
|
POST /ata/submit?appid={appid}&caption_type=speech
|
|
Content-Type: application/json
|
|
Authorization: Bearer; {token}
|
|
|
|
{
|
|
"url": "https://example.com/audio.mp3",
|
|
"audio_text": "这是要被打轴的字幕文本"
|
|
}
|
|
```
|
|
|
|
**参数:**
|
|
- `caption_type` - `speech`(说话) 或 `singing`(歌词)
|
|
- `sta_punc_mode` - 标点模式: `1`(省略句末标点), `2`(空格代替), `3`(保留完整标点)
|
|
|
|
#### 查询结果
|
|
```http
|
|
GET /ata/query?appid={appid}&id={task_id}&blocking=1
|
|
Authorization: Bearer; {token}
|
|
```
|
|
|
|
---
|
|
|
|
## 错误码
|
|
|
|
| 码 | 含义 | 处理 |
|
|
|----|------|------|
|
|
| 0 | 成功 | - |
|
|
| 2000 | 处理中 | 继续轮询 |
|
|
| 1001 | 参数无效 | 检查必填参数 |
|
|
| 1002 | 无权限 | 检查 token |
|
|
| 1003 | 超频 | 降低调用频率 |
|
|
| 1010 | 音频过长 | 缩短音频 |
|
|
| 1011 | 音频过大 | 压缩音频(<200MB) |
|
|
| 1012 | 格式无效 | 检查音频格式 |
|
|
| 1013 | 音频静音 | 检查音频内容 |
|
|
|
|
---
|
|
|
|
## Python 代码示例
|
|
|
|
```python
|
|
import requests
|
|
import time
|
|
|
|
TOKEN = "your_token"
|
|
APPID = "your_appid"
|
|
BASE_URL = "https://openspeech.bytedance.com/api/v1/vc"
|
|
|
|
def submit(audio_url, language="zh-CN", use_punc=True):
|
|
"""提交字幕生成任务"""
|
|
resp = requests.post(
|
|
f"{BASE_URL}/submit",
|
|
params={"appid": APPID, "language": language, "use_punc": str(use_punc)},
|
|
json={"url": audio_url},
|
|
headers={"Authorization": f"Bearer; {TOKEN}"}
|
|
)
|
|
return resp.json()["id"]
|
|
|
|
def query(task_id):
|
|
"""查询任务结果"""
|
|
resp = requests.get(
|
|
f"{BASE_URL}/query",
|
|
params={"appid": APPID, "id": task_id, "blocking": "1"},
|
|
headers={"Authorization": f"Bearer; {TOKEN}"}
|
|
)
|
|
return resp.json()
|
|
|
|
def generate_caption(audio_url, language="zh-CN"):
|
|
"""完整流程: 提交->轮询->返回结果"""
|
|
task_id = submit(audio_url, language)
|
|
|
|
for _ in range(60): # 最多轮询60秒
|
|
result = query(task_id)
|
|
if result["code"] == 0:
|
|
return result["utterances"]
|
|
elif result["code"] != 2000:
|
|
raise Exception(f"Task failed: {result['message']}")
|
|
time.sleep(1)
|
|
|
|
raise Exception("Timeout")
|
|
|
|
def to_srt(utterances):
|
|
"""转换为 SRT 字幕格式"""
|
|
def ms_to_time(ms):
|
|
h = ms // 3600000
|
|
m = (ms % 3600000) // 60000
|
|
s = (ms % 60000) // 1000
|
|
ms = ms % 1000
|
|
return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
|
|
|
|
lines = []
|
|
for i, u in enumerate(utterances, 1):
|
|
lines.append(f"{i}")
|
|
lines.append(f"{ms_to_time(u['start_time'])} --> {ms_to_time(u['end_time'])}")
|
|
lines.append(u['text'])
|
|
lines.append("")
|
|
return "\n".join(lines)
|
|
|
|
# 使用示例
|
|
if __name__ == "__main__":
|
|
utterances = generate_caption("https://example.com/audio.mp3")
|
|
srt_content = to_srt(utterances)
|
|
print(srt_content)
|
|
```
|
|
|
|
---
|
|
|
|
## cURL 示例
|
|
|
|
```bash
|
|
# 1. 提交任务
|
|
TASK_ID=$(curl -s -X POST \
|
|
-H "Authorization: Bearer; ${TOKEN}" \
|
|
-H "content-type: application/json" \
|
|
-d '{"url": "'${AUDIO_URL}'"}' \
|
|
"https://openspeech.bytedance.com/api/v1/vc/submit?appid=${APPID}&language=zh-CN" \
|
|
| jq -r '.id')
|
|
|
|
# 2. 查询结果
|
|
curl -s -X GET \
|
|
-H "Authorization: Bearer; ${TOKEN}" \
|
|
"https://openspeech.bytedance.com/api/v1/vc/query?appid=${APPID}&id=${TASK_ID}&blocking=1"
|
|
```
|