字幕 API Subtitle API
支持从视频/音频自动生成字幕、多语言翻译翻译与格式转换 (SRT/VTT/ASS),一站式字幕处理。 Automatic subtitle generation from video/audio, multi-language translation, and format conversion (SRT/VTT/ASS) in one call.
快速概览 Quick Overview
属性 Attribute 说明 Description
生成端点 Generate Endpoint POST /v1/subtitle/generate
转换端点 Convert Endpoint POST /v1/subtitle/convert
认证 Authentication Bearer Token(Authorization 请求头) Bearer Token in Authorization header
输入方式 Input Method 本地文件上传(multipart/form-data)或视频/音频 URL Local file upload (multipart/form-data) or video/audio URL
文件上限 File Limit 最大 500MB,视频最长 4 小时 Max 500MB, max 4 hours video
输出格式 Output Format SRT / VTT / ASS / JSON,默认为 SRT SRT / VTT / ASS / JSON, default SRT
支持语言 Supported Languages 30+ 种语言,支持自动检测和指定 30+ languages, auto-detect and manual specification supported
字幕类型 Subtitle Type 原文字幕 / 翻译字幕 / 双语合并字幕 Source subtitles / translated subtitles / merged bilingual
生成字幕 Generate Subtitles
POST /v1/subtitle/generate
从视频或音频文件中提取语音并自动生成字幕,可选择翻译为目标语言并输出多格式字幕文件。
Extract speech from video/audio files and automatically generate subtitles, with optional translation and multi-format output.
认证 Authentication
所有 API 请求需在 HTTP Header 中携带 Access Token。
All API requests must include an Access Token in the HTTP Header.
Authorization: Bearer {access_token}
请求参数 Request Parameters
参数 Parameter 类型 Type 必填 Required 说明 Description
video file required 视频/音频文件,最大 500MB,最长 4 小时 Video/audio file, max 500MB, max 4 hours
video_url string optional 视频/音频文件的公网可访问 URL(与 video 二选一) Publicly accessible URL of the video/audio file (alternative to video)
source_lang string required 源语言代码,如 en、zh,也支持 auto 自动检测 Source language code, e.g. en, zh. Also supports auto for detection
target_lang string optional 翻译目标语言代码,不填则仅生成原文字幕 Target language code; omit for source-only subtitles
output_format string optional 输出格式:srt / vtt / ass / json,默认 srt Output format: srt / vtt / ass / json; default srt
merge boolean optional 是否生成双语合并字幕(原文+译文在同一字幕条),默认 false Generate merged bilingual subtitles, default false
max_chars_per_line integer optional 每行最大字符数,超出自动换行分割,默认 42 Max characters per line, auto-wraps if exceeded, default 42
min_duration number optional 每条字幕最短显示时长(秒),默认 1.0 Minimum display duration per subtitle in seconds, default 1.0
max_duration number optional 每条字幕最长显示时长(秒),默认 7.0 Maximum display duration per subtitle in seconds, default 7.0
formality string optional 翻译语气:default / formal / informal Translation tone: default / formal / informal
glossary_id string optional 关联术语库 ID,翻译时应用自定义术语 Glossary ID for custom term mappings during translation
enable_diarization boolean optional 是否开启说话人分离,默认 false Enable speaker diarization, default false
speaker_count integer optional 预期说话人数量(1-10),配合 diarization 使用 Expected speaker count (1-10), used with diarization
subtitle_encoding string optional 字幕文件编码:utf-8 / utf-8-bom / gbk,默认 utf-8 Subtitle file encoding: utf-8 / utf-8-bom / gbk, default utf-8
callback_url string optional 异步回调地址,处理完成后 POST 结果到此 URL Async callback URL, receives POST result upon completion
字幕格式对比 Subtitle Format Comparison
格式 Format 全称 Full Name 特点 Features 推荐场景 Best For
srt
SubRip
通用标准,兼容性最好,纯文本格式
Universal standard, best compatibility, plain text
YouTube、VLC、通用视频播放器
YouTube, VLC, general video players
vtt
WebVTT
HTML5 标准,支持样式设置和元数据
HTML5 standard, supports styling and metadata
网页播放器、在线课程、H5 应用
Web players, online courses, H5 apps
ass
Advanced SubStation Alpha
专业字幕格式,支持丰富的样式、特效和定位
Professional format, rich styling, effects, and positioning
影视后期、字幕组、特效需求
Post-production, fansub groups, special effects
json
JSON
结构化数据,方便程序处理和分析
Structured data for easy programmatic processing and analysis
API 集成、数据分析、自定义处理
API integration, data analysis, custom processing
请求示例 Request Examples
cURL
Python
JavaScript
Java
Go
# 基础用法:生成英文原文 SRT 字幕
curl -X POST https://api.itranslator.cc/v1/subtitle/generate \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "video=@presentation.mp4" \
-F "source_lang=en"
# 生成双语合并字幕:英文 → 中文
curl -X POST https://api.itranslator.cc/v1/subtitle/generate \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "video=@lecture.mp4" \
-F "source_lang=en" \
-F "target_lang=zh" \
-F "output_format=srt" \
-F "merge=true" \
-F "max_chars_per_line=36"
# 高级用法:URL 输入 + ASS 格式 + 术语库 + 说话人分离
curl -X POST https://api.itranslator.cc/v1/subtitle/generate \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "video_url=https://cdn.example.com/movie.mp4" \
-F "source_lang=en" \
-F "target_lang=ja" \
-F "output_format=ass" \
-F "formality=formal" \
-F "glossary_id=gls_abc123" \
-F "enable_diarization=true" \
-F "speaker_count=3"
import requests
token = "YOUR_ACCESS_TOKEN"
url = "https://api.itranslator.cc/v1/subtitle/generate"
# 基础用法:生成原文字幕
with open("presentation.mp4", "rb") as f:
resp = requests.post(
url,
headers={"Authorization": f"Bearer {token}"},
files={"video": f},
data={"source_lang": "en"}
)
with open("output.srt", "wb") as out:
out.write(resp.content)
# 高级用法:双语字幕 + 术语库
with open("lecture.mp4", "rb") as f:
resp = requests.post(
url,
headers={"Authorization": f"Bearer {token}"},
files={"video": f},
data={
"source_lang": "en",
"target_lang": "zh",
"output_format": "srt",
"merge": True,
"max_chars_per_line": 36,
"formality": "formal",
"glossary_id": "gls_abc123",
"enable_diarization": True,
"speaker_count": 3
}
)
result = resp.json()
print(f"字幕文件: {result['subtitle_file']}")
print(f"共 {result['segments']} 条字幕")
# 异步模式
resp = requests.post(
url,
headers={"Authorization": f"Bearer {token}"},
data={
"video_url": "https://cdn.example.com/large-video.mp4",
"source_lang": "en",
"target_lang": "zh",
"callback_url": "https://my-server.com/webhook/subtitle"
}
)
print(f"任务已提交: {resp.json()['task_id']}")
const fs = require("fs");
const FormData = require("form-data");
const axios = require("axios");
async function generateSubtitles() {
const form = new FormData();
form.append("video", fs.createReadStream("presentation.mp4"));
form.append("source_lang", "en");
form.append("target_lang", "zh");
form.append("output_format", "vtt");
form.append("merge", "true");
form.append("max_chars_per_line", "36");
form.append("enable_diarization", "true");
form.append("speaker_count", "3");
const resp = await axios.post(
"https://api.itranslator.cc/v1/subtitle/generate",
form,
{
headers: {
...form.getHeaders(),
Authorization: `Bearer ${process.env.API_TOKEN}`
},
maxContentLength: Infinity,
maxBodyLength: Infinity
}
);
// 保存 JSON 结构化数据
const { subtitle_json, format, segments } = resp.data;
fs.writeFileSync("output.json", JSON.stringify(subtitle_json, null, 2));
console.log(`✅ 已生成 ${segments} 条 ${format} 字幕`);
// 逐条输出内容
subtitle_json.forEach(item => {
console.log(
`[${item.start} → ${item.end}] ${item.source}\n → ${item.target || "(原文)"}\n`
);
});
}
generateSubtitles().catch(console.error);
import okhttp3.*;
import java.io.File;
import java.io.IOException;
public class SubtitleGenerate {
public static void main(String[] args) throws IOException {
OkHttpClient client = new OkHttpClient();
RequestBody body = new MultipartBody.Builder()
.setType(MultipartBody.FORM)
.addFormDataPart("video", "presentation.mp4",
RequestBody.create(new File("presentation.mp4"),
MediaType.parse("video/mp4")))
.addFormDataPart("source_lang", "en")
.addFormDataPart("target_lang", "zh")
.addFormDataPart("output_format", "srt")
.addFormDataPart("merge", "true")
.addFormDataPart("max_chars_per_line", "36")
.addFormDataPart("formality", "formal")
.addFormDataPart("enable_diarization", "true")
.addFormDataPart("speaker_count", "3")
.build();
Request request = new Request.Builder()
.url("https://api.itranslator.cc/v1/subtitle/generate")
.header("Authorization",
"Bearer " + System.getenv("API_TOKEN"))
.post(body)
.build();
try (Response response = client.newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
package main
import (
"bytes"
"fmt"
"io"
"mime/multipart"
"net/http"
"os"
)
func main() {
token := os.Getenv("API_TOKEN")
url := "https://api.itranslator.cc/v1/subtitle/generate"
var buf bytes.Buffer
writer := multipart.NewWriter(&buf)
// 添加视频文件
file, _ := os.Open("presentation.mp4")
defer file.Close()
part, _ := writer.CreateFormFile("video", "presentation.mp4")
io.Copy(part, file)
// 添加参数
writer.WriteField("source_lang", "en")
writer.WriteField("target_lang", "zh")
writer.WriteField("output_format", "srt")
writer.WriteField("merge", "true")
writer.WriteField("max_chars_per_line", "36")
writer.WriteField("enable_diarization", "true")
writer.WriteField("speaker_count", "3")
writer.Close()
req, _ := http.NewRequest("POST", url, &buf)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
Copy
响应参数 Response Parameters
字段 Field 类型 Type 说明 Description
subtitle_file string 字幕文件的下载 URL(有效期 24 小时) Download URL for the subtitle file (valid 24 hours)
subtitle_json array JSON 格式的字幕数据,便于程序处理 Structured subtitle data in JSON format for programmatic use
subtitle_json[].index integer 字幕序号,从 1 开始 Subtitle index, starts from 1
subtitle_json[].start string 开始时间(HH:MM:SS,mmm 格式) Start time in HH:MM:SS,mmm format
subtitle_json[].end string 结束时间(HH:MM:SS,mmm 格式) End time in HH:MM:SS,mmm format
subtitle_json[].source string 原始语言字幕文本 Source language subtitle text
subtitle_json[].target string 翻译后字幕文本(未指定 target_lang 时为空) Translated subtitle text (empty if no target_lang specified)
subtitle_json[].speaker string 说话人标识(开启 diarization 时返回) Speaker label (returned when diarization is enabled)
subtitle_json[].confidence number ASR 识别置信度(0-1) ASR confidence score (0-1)
format string 输出字幕格式:srt / vtt / ass / json Output subtitle format: srt / vtt / ass / json
segments integer 字幕总条数 Total number of subtitle segments
duration number 视频/音频时长(秒) Video/audio duration in seconds
source_lang string 检测到或指定的源语言 Detected or specified source language
billed_duration number 计费时长(秒) Billed duration in seconds
响应示例 Response Examples
原文 SRT 字幕(不翻译) Source-only SRT Subtitles (no translation)
{
"subtitle_file": "https://cdn.itranslator.cc/subtitles/abc123.srt",
"subtitle_json": [
{
"index": 1,
"start": "00:00:01,000",
"end": "00:00:04,000",
"source": "Hello everyone.",
"confidence": 0.98
},
{
"index": 2,
"start": "00:00:04,500",
"end": "00:00:08,000",
"source": "Welcome to our conference.",
"confidence": 0.97
}
],
"format": "srt",
"segments": 2,
"duration": 8.0,
"source_lang": "en"
}
双语合并字幕(翻译 + 原文) Merged Bilingual Subtitles (translation + source)
{
"subtitle_file": "https://cdn.itranslator.cc/subtitles/abc123.srt",
"subtitle_json": [
{
"index": 1,
"start": "00:00:01,000",
"end": "00:00:04,000",
"source": "Hello everyone.",
"target": "大家好。",
"confidence": 0.98
},
{
"index": 2,
"start": "00:00:04,500",
"end": "00:00:08,000",
"source": "Welcome to our conference.",
"target": "欢迎参加我们的会议。",
"confidence": 0.97
}
],
"format": "srt",
"segments": 24,
"duration": 125.3,
"source_lang": "en",
"target_lang": "zh",
"billed_duration": 130.0
}
ASS 格式 + 说话人分离 ASS Format + Speaker Diarization
{
"subtitle_file": "https://cdn.itranslator.cc/subtitles/xyz789.ass",
"subtitle_json": [
{
"index": 1,
"start": "00:00:01,000",
"end": "00:00:05,500",
"source": "So let's begin with the quarterly results.",
"target": "那我们首先来看季度业绩。",
"speaker": "speaker_0",
"confidence": 0.99
},
{
"index": 2,
"start": "00:00:06,000",
"end": "00:00:12,000",
"source": "Revenue increased by 15% compared to last year.",
"target": "与去年相比收入增长了15%。",
"speaker": "speaker_0",
"confidence": 0.96
},
{
"index": 3,
"start": "00:00:12,500",
"end": "00:00:18,000",
"source": "That's great news. What drove the growth?",
"target": "太好了。增长的主要驱动力是什么?",
"speaker": "speaker_1",
"confidence": 0.98
}
],
"format": "ass",
"segments": 156,
"duration": 1205.0,
"source_lang": "en",
"target_lang": "zh",
"billed_duration": 1210.0
}
字幕格式转换 Format Conversion
POST /v1/subtitle/convert
支持 SRT ↔ VTT ↔ ASS 之间的任意格式互转,可同时进行语言翻译和时间轴调整。
Convert between SRT, VTT, and ASS formats, with optional translation and timeline adjustment.
请求参数 Request Parameters
参数 Parameter 类型 Type 必填 Required 说明 Description
file file required 原始字幕文件(.srt / .vtt / .ass),最大 50MB Source subtitle file (.srt / .vtt / .ass), max 50MB
source_format string required 源格式:srt / vtt / ass Source format: srt / vtt / ass
target_format string required 目标格式:srt / vtt / ass Target format: srt / vtt / ass
source_lang string optional 字幕源语言代码,需要翻译时必填 Subtitle source language, required if translating
target_lang string optional 翻译目标语言代码,不填则仅转换格式不做翻译 Target language code; only convert format if omitted
time_offset number optional 时间轴偏移量(秒),正数延迟、负数提前 Timeline offset in seconds; positive delays, negative advances
encoding string optional 输出编码:utf-8 / utf-8-bom / gbk Output encoding: utf-8 / utf-8-bom / gbk
fps number optional 帧率(fps),用于 ASS 字幕时间码转换,默认 23.976 Frame rate for ASS timecode conversion, default 23.976
转换请求示例 Conversion Request Example
# SRT → VTT,并偏移时间轴 +1.5秒
curl -X POST https://api.itranslator.cc/v1/subtitle/convert \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@subtitles.srt" \
-F "source_format=srt" \
-F "target_format=vtt" \
-F "time_offset=1.5"
转换响应示例 Conversion Response Example
{
"converted_file": "https://cdn.itranslator.cc/subtitles/conv_abc.vtt",
"source_format": "srt",
"target_format": "vtt",
"segments": 52,
"time_offset": 1.5
}
错误码 Error Codes
HTTP Code 错误码 Error Code 说明 Description
200 0成功 Success
400 1001参数错误,请检查必填参数和参数格式 Invalid parameter; check required fields and format
400 1002不支持的输出格式,仅支持 srt/vtt/ass/json Unsupported output format, only srt/vtt/ass/json allowed
400 1003不支持的语言对 Unsupported language pair
400 1004字幕文件格式解析失败 Subtitle file parsing failed
401 2001认证失败,Token 无效或已过期 Authentication failed; invalid or expired token
403 2003无权限访问该资源 Access denied; insufficient permissions
413 3001文件大小超出限制(生成最大 500MB,转换最大 50MB) File size exceeds limit (500MB for generate, 50MB for convert)
415 3002不支持的文件格式 Unsupported file format
429 4001请求频率超限,请稍后重试 Rate limit exceeded; please retry later
456 4002套餐配额已用尽,请升级或等待重置 Plan quota exhausted; upgrade or wait for reset
500 5001服务器处理失败,请重试或联系技术支持 Server processing failed; retry or contact support
503 5002服务暂时不可用,建议稍后重试 Service temporarily unavailable; retry later
最佳实践 Best Practices
选择合适的格式: 通用场景使用 SRT,网页播放使用 VTT(支持 HTML5 track 标签),专业后期使用 ASS。
Choose the right format: SRT for general use, VTT for web playback (HTML5 track tag), ASS for professional post-production.
指定源语言: 已知源语言时务必显式传入 source_lang,避免自动检测带来的识别偏差。
Specify source language: Always provide source_lang when known to avoid auto-detection errors.
合理设置行宽: 中文建议 max_chars_per_line=20,英文建议 max_chars_per_line=42,保证观影舒适度。
Set appropriate line width: Recommend 20 chars for Chinese, 42 for English for comfortable reading.
术语库配合使用: 涉及人名、地名、专业术语时,通过术语库统一管理,避免翻译不一致。
Use glossaries: Manage names, places, and technical terms via glossaries for translation consistency.
编码处理: 中文内容推荐 utf-8-bom,确保 Windows 上的兼容性。
Encoding: Use utf-8-bom for Chinese content to ensure Windows compatibility.
大视频异步处理: 超过 10 分钟的视频建议使用 callback_url 异步回调,避免同步请求超时。
Async for large files: Use callback_url for videos over 10 minutes to avoid timeouts.
安全提醒: 请勿在客户端代码中暴露 Access Token,建议通过后端代理调用。
Security: Do not expose Access Token in client-side code; use a backend proxy.
应用场景 Use Cases
场景 Scenario 推荐配置 Recommended Config 说明 Notes
📹 视频字幕制作
📹 Video Subtitling
output_format=srt + max_chars=42
自动生成时间轴对齐的字幕,直接导入视频编辑软件
Auto-generate time-aligned subtitles, import directly into video editors
🌍 多语视频分发
🌍 Multilingual Distribution
target_lang 多语种 + merge=true
同一视频生成多语言字幕,满足国际化分发需求
Generate multilingual subtitles from the same video for global distribution
🎓 在线教育
🎓 Online Education
output_format=vtt + 术语库
VTT 适配网页播放器,术语库保证学科术语翻译一致
VTT for web players, glossary ensures consistent academic terminology
🎬 影视后期
🎬 Post-Production
output_format=ass + 说话人分离
ASS 支持丰富样式和定位,说话人分离便于区分角色
ASS supports rich styling and positioning, diarization for character distinction
📱 短视频平台
📱 Short Video Platforms
output_format=srt + max_chars=20(中文)
适合手机屏幕阅读,短行字幕提升观看体验
Short lines optimized for mobile reading, enhanced viewing experience
♿ 无障碍合规
♿ Accessibility Compliance
output_format=vtt + 原文字幕
满足 WCAG 无障碍标准,为听障用户提供字幕
Meet WCAG accessibility standards with captions for hearing-impaired users
使用说明
Notes
文件上传使用 multipart/form-data 编码,Content-Type 请勿手动设置,让 HTTP 客户端自动生成。
Use multipart/form-data encoding; let the HTTP client auto-generate Content-Type.
大文件建议分片上传或使用异步任务模式,避免请求超时。
For large files, use chunked upload or async task mode to avoid timeouts.
请勿在客户端代码中暴露 Access Token,建议通过后端代理调用。
Do not expose your Access Token in client-side code; use a backend proxy.
生成字幕时,视频中的背景音乐和噪音可能影响识别精度,建议使用语音清晰的音视频素材。
Background music and noise may affect transcription accuracy; use clear audio/video sources.