视频翻译
上传视频文件,自动提取音轨、进行语音识别(ASR)并翻译,生成多语言字幕文件(SRT/VTT/ASS)或直接输出翻译后的视频。支持硬字幕烧录、AI 配音、说话人分离等高级功能,满足影视字幕、课程翻译、企业宣传片等多场景需求。
快速概览
Quick Overview
| 属性 | 说明 |
|---|---|
| 端点 | POST /v1/video/translate |
| 认证 | Bearer Token(Authorization 请求头) |
| 输入方式 | 本地文件上传(multipart/form-data)或视频 URL |
| 视频上限 | 最大 500MB,最长 3 小时 |
| 处理模式 | 异步任务(返回 task_id 轮询)+ 可选 Webhook 回调 |
| 输出形式 | 纯字幕文件(SRT/VTT/ASS)、硬字幕视频、AI 配音视频、双语字幕 |
| 字幕样式 | 可自定义字体、大小、颜色、位置、背景、描边等 |
| 支持语言 | 中文、英语、日语、韩语、法语、德语、西班牙语等 50+ 种语言 |
| 处理时长 | 约为视频时长的 30%~60%(取决于视频长度和所选功能) |
请求端点
Endpoint
POST/v1/video/translate
认证
Authentication
Authorization: Bearer {access_token}请求参数
Request Parameters
⏰ 异步任务
视频翻译为异步任务,首次请求返回
视频翻译为异步任务,首次请求返回
task_id,可通过任务查询接口获取处理进度和结果。也支持 callback_url Webhook 回调通知。基础参数
Basic Parameters
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | file | conditional | 视频文件(与 video_url 二选一),最大 500MB,最长 3 小时 |
| video_url | string | conditional | 视频的公开可访问 URL(与 file 二选一) |
| target_lang | string | required | 目标翻译语言代码 |
| source_lang | string | optional | 源语言代码,不传或 auto 则自动检测 |
| output_format | string | optional | srt(默认)/ vtt / ass / burned_video(硬字幕视频)/ all。详见输出模式 |
| bilingual | boolean | optional | 是否生成双语字幕,默认 false |
| engine | string | optional | standard(通用,默认)/ professional(专业,影视/法律/医学内容,更高准确率) |
| callback_url | string | optional | Webhook 回调地址,任务完成后向该地址 POST 结果 |
| glossary_id | string | optional | 术语库 ID,确保特定词汇翻译一致性(品牌名、专业术语等) |
字幕样式参数(output_format=burned_video 时适用)
Subtitle Style Parameters (for burned_video)
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| subtitle_font | string | optional | PingFang SC | 字幕字体名称。支持系统内置字体和已上传的自定义字体 |
| subtitle_size | integer | optional | 24 | 字幕字号(px),推荐 18–36 |
| subtitle_color | string | optional | #FFFFFF | 字幕文字颜色(HEX 格式) |
| subtitle_outline | string | optional | #000000 | 字幕描边颜色。设为空字符串则无描边 |
| subtitle_outline_width | float | optional | 2.0 | 描边宽度(px),1.0–4.0 |
| subtitle_bg | string | optional | — | 字幕背景色(含透明度),如 #00000080 |
| subtitle_position | string | optional | bottom | bottom(底部)/ top(顶部)/ middle(居中) |
AI 配音参数
AI Dubbing Parameters
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| enable_dubbing | boolean | optional | false | 是否启用 AI 配音,将翻译后文本用合成语音替换原音轨 |
| dubbing_voice | string | optional | default-female | default-female / default-male / professional-female / professional-male |
| dubbing_speed | float | optional | 1.0 | 配音语速,0.5–2.0 |
| dubbing_bg_music | float | optional | 0.3 | 保留原视频背景音乐音量比例,0.0–1.0。0 则替换全部音轨 |
高级参数
Advanced Parameters
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| enable_diarization | boolean | optional | false | 启用说话人分离,在字幕中标注 [Speaker 1]、[Speaker 2] |
| speaker_count | integer | optional | — | 预期说话人数,不指定则自动推断 |
| max_subtitle_length | integer | optional | 42 | 每行字幕最大字符数,超出自动换行或拆分 |
| subtitle_max_duration | float | optional | 5.0 | 单条字幕最长秒数,2.0–10.0,超时自动切分 |
| profanity_filter | boolean | optional | false | 启用敏感词过滤,用 *** 替换不雅词汇 |
| start_time | float | optional | 0 | 仅翻译从指定秒数开始的片段 |
| end_time | float | optional | — | 仅翻译到指定秒数为止的片段 |
输出模式
Output Modes
output_format 参数决定了最终产物的形式:
| 值 | 输出内容 | 适用场景 |
|---|---|---|
srt | SRT 字幕文件 | 通用字幕,兼容几乎所有播放器和编辑软件 |
vtt | WebVTT 字幕文件 | Web 播放器(HTML5)、YouTube 等在线平台首选 |
ass | ASS/SSA 高级字幕 | 丰富样式(字体、颜色、动画、卡拉OK),适合影视后期和特效字幕 |
burned_video | 带硬字幕的视频文件 | 字幕不可关闭,适合社交媒体分发、短视频平台上传 |
all | 以上全部格式 | 一次性获取所有格式,适合多用途场景 |
支持视频格式
Supported Video Formats
| 格式 | 视频编码 | 音频编码 | 推荐 |
|---|---|---|---|
.mp4 | H.264, H.265 | AAC, MP3 | 首选 |
.mov | H.264, ProRes | AAC, PCM | Apple 常用 |
.mkv | H.264, H.265, VP9 | AAC, Opus, FLAC | 多音轨取第一条 |
.avi | MJPEG, H.264 | MP3, PCM | 需确保音轨可解析 |
.webm | VP8, VP9 | Opus, Vorbis | Web 常用 |
.flv | H.264 | AAC, MP3 | 直播录制常见 |
.wmv | WMV | WMA | 建议先转 MP4 |
💡 建议:使用 H.264 + AAC 编码的 MP4 格式,分辨率 ≥ 720p,帧率 ≥ 25fps,可获得最佳处理速度和识别准确率。
请求示例
Request Examples
基础示例 — 上传本地文件翻译为 SRT 字幕
Basic — Upload file & translate to SRT
curl -X POST https://api.itranslator.cc/v1/video/translate \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F "file=@presentation.mp4" \ -F "target_lang=zh" \ -F "output_format=srt" \ -F "bilingual=true"
通过 URL 翻译在线视频
Translate via Video URL
curl -X POST https://api.itranslator.cc/v1/video/translate \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F "video_url=https://example.com/uploads/video.mp4" \ -F "target_lang=ja" \ -F "source_lang=en"
生成硬字幕视频 + 自定义样式
Burned-in Subtitles with Custom Style
curl -X POST https://api.itranslator.cc/v1/video/translate \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F "file=@tutorial.mp4" \ -F "target_lang=ko" \ -F "output_format=burned_video" \ -F "bilingual=true" \ -F "subtitle_font=Noto Sans SC" \ -F "subtitle_size=28" \ -F "subtitle_color=#FFFFFF" \ -F "subtitle_outline=#000000" \ -F "subtitle_bg=#00000060"
AI 配音 + 说话人分离
AI Dubbing + Speaker Diarization
curl -X POST https://api.itranslator.cc/v1/video/translate \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -F "file=@interview.mp4" \ -F "target_lang=en" \ -F "source_lang=zh" \ -F "enable_dubbing=true" \ -F "dubbing_voice=professional-female" \ -F "dubbing_speed=1.0" \ -F "dubbing_bg_music=0.2" \ -F "enable_diarization=true" \ -F "speaker_count=2" \ -F "callback_url=https://your-server.com/webhook/translate"
Python 轮询任务状态直到完成
Python Polling Until Completion
import requests, time
def translate_video(file_path, target_lang, token):
# 1. 提交任务
with open(file_path, "rb") as f:
resp = requests.post(
"https://api.itranslator.cc/v1/video/translate",
headers={"Authorization": f"Bearer {token}"},
files={"file": f},
data={"target_lang": target_lang, "output_format": "all"}
)
task = resp.json()
task_id = task["task_id"]
print(f"任务已提交: {task_id}")
# 2. 轮询状态
while True:
resp = requests.get(
f"https://api.itranslator.cc/v1/video/task/{task_id}",
headers={"Authorization": f"Bearer {token}"}
)
status = resp.json()
progress = status.get("progress", 0)
state = status["status"]
print(f"进度: {progress}%")
if state == "completed":
return status["result"]
elif state == "failed":
raise Exception(f"失败: {status.get('error')}")
time.sleep(5)
result = translate_video("presentation.mp4", "ja", token)
print(f"下载: {result['download_url']}")响应参数
Response Parameters
提交任务后立即返回:
| 字段 | 类型 | 说明 |
|---|---|---|
task_id | string | 任务唯一标识,用于轮询进度 |
status | string | 初始状态为 queued |
created_at | string | 任务创建时间(ISO 8601) |
estimated_seconds | integer | 预计处理时长(秒) |
任务完成后 result 字段包含:
| 字段 | 类型 | 说明 |
|---|---|---|
subtitle_url | string | 字幕文件下载链接(output_format 为 srt/vtt/ass 时) |
video_url | string | 处理后视频下载链接(output_format 为 burned_video 或启用配音时) |
files | object | output_format 为 all 时,按格式分组的下载链接字典 |
duration | float | 视频时长(秒) |
char_count | integer | 翻译总字符数 |
source_lang | string | 检测到的源语言代码 |
查询任务状态
Query Task Status
GET/v1/video/task/{task_id}
处理中响应
Processing Response
{
"task_id": "vt_20260720_abc123",
"status": "processing",
"progress": 65,
"stage": "translating",
"estimated_seconds": 48,
"created_at": "2026-07-20T10:30:00Z"
}完成响应
Completed Response
{
"task_id": "vt_20260720_abc123",
"status": "completed",
"progress": 100,
"result": {
"subtitle_url": "https://cdn.itranslator.cc/output/presentation_zh.srt",
"duration": 1840.5,
"char_count": 15230,
"source_lang": "en"
},
"created_at": "2026-07-20T10:30:00Z",
"completed_at": "2026-07-20T10:42:30Z"
}全部格式输出响应
All Formats Response
{
"task_id": "vt_20260720_abc123",
"status": "completed",
"progress": 100,
"result": {
"files": {
"srt": "https://cdn.itranslator.cc/output/vid_zh.srt",
"vtt": "https://cdn.itranslator.cc/output/vid_zh.vtt",
"ass": "https://cdn.itranslator.cc/output/vid_zh.ass",
"burned_video": "https://cdn.itranslator.cc/output/vid_zh.mp4"
},
"duration": 1840.5,
"char_count": 15230,
"source_lang": "en"
},
"created_at": "2026-07-20T10:30:00Z",
"completed_at": "2026-07-20T10:45:00Z"
}处理流水线
Processing Pipeline
视频翻译分为以下几个阶段,可通过任务查询中的 stage 字段了解当前处理进度:
| Stage | 说明 | 预估耗时占比 |
|---|---|---|
validating | 校验视频格式、大小和音轨 | ~2% |
extracting | 从视频中提取音频轨道 | ~10% |
recognizing | 对提取的音频进行语音识别(ASR) | ~30% |
diarizing | 说话人分离(仅 enable_diarization=true 时) | ~15% |
translating | 对识别文本进行翻译 | ~25% |
synthesizing | 生成字幕文件或烧录字幕/AI 配音合成(仅启用配音时) | ~18% |
packaging | 打包输出文件并上传至 CDN | ~5% |
回调通知(Webhook)
Callback Notifications (Webhook)
提交任务时指定 callback_url,任务完成后会向该地址 POST 结果,避免轮询:
POST https://your-server.com/webhook/translate Content-Type: application/json X-Signature: sha256=abcd1234... ← 用于验证请求来源 { "task_id": "vt_20260720_abc123", "status": "completed", "result": { "subtitle_url": "https://cdn.itranslator.cc/output/vid_zh.srt", "duration": 1840.5, "char_count": 15230 } }
🔐 验证签名:回调请求包含 X-Signature 请求头,值为 HMAC-SHA256(callback_url, YOUR_SECRET_KEY) 的十六进制结果。建议验证签名以防止伪造回调。
错误码
Error Codes
| Status | 错误码 | 说明 |
|---|---|---|
| 400 | UNSUPPORTED_VIDEO | 不支持的视频格式 |
| 400 | VIDEO_TOO_LARGE | 视频超过 500MB 或 3 小时限制 |
| 400 | NO_AUDIO_TRACK | 视频中未检测到音轨 |
| 400 | INVALID_LANG_CODE | 不支持的语言代码 |
| 400 | INVALID_URL | video_url 无效或无法访问 |
| 400 | GLOSSARY_NOT_FOUND | 指定的术语库不存在或无权限访问 |
| 401 | UNAUTHORIZED | 未提供认证信息或 Token 无效 |
| 402 | QUOTA_EXCEEDED | 配额不足,请升级套餐 |
| 429 | RATE_LIMITED | 请求过于频繁,请稍后重试 |
| 500 | INTERNAL_ERROR | 内部服务错误,可重试 |
| 503 | SERVICE_BUSY | 服务繁忙,任务排队中 |
最佳实践
Best Practices
- 指定源语言:如果已知视频的源语言,显式指定
source_lang而非依赖自动检测,可显著提高 ASR 识别准确率和翻译质量。 - 使用术语库:对于包含大量专业术语或品牌名称的视频,提前创建术语库并传入
glossary_id,确保翻译一致性。 - 选择合适的输出格式:社交分发推荐
burned_video+ 字幕样式定制;专业后期推荐ass格式;Web 播放推荐vtt。 - 视频预处理:确保视频音质清晰、背景噪音尽量低。嘈杂环境录制的视频建议先降噪处理。
- 优选 MP4 格式:MP4 (H.264 + AAC) 处理速度最快,复杂编码格式(如 ProRes)需要额外转码时间。
- Webhook 优于轮询:生产环境建议使用
callback_url接收结果,减少轮询开销和 API 消耗。 - 说话人分离场景:多人对话场景(访谈、会议、多人播客)建议启用
enable_diarization,如知道人数则指定speaker_count。
典型应用场景
Typical Use Cases
| 场景 | 推荐配置 |
|---|---|
| 📚 在线课程多语言发布 | output_format=srt, bilingual=true, engine=professional |
| 🎬 影视字幕翻译 | output_format=ass, enable_diarization=true, subtitle_max_duration=3.0 |
| 📱 短视频平台出海 | output_format=burned_video, custom subtitle styles, profanity_filter=true |
| 🎤 访谈/播客国际化 | enable_dubbing=true, dubbing_voice=professional-female, enable_diarization=true |
| 🏢 企业宣传片本地化 | output_format=all, engine=professional, glossary_id=xxx |
| 🎮 游戏预告/实况翻译 | output_format=burned_video, subtitle_position=top, bilingual subtitles |
使用说明
- 文件上传使用
multipart/form-data编码,Content-Type 请勿手动设置,让 HTTP 客户端自动生成 boundary。 - 大文件建议通过
video_url传入直链,或使用分片上传避免请求超时。 - 请勿在客户端代码中暴露 Access Token,建议通过后端代理调用。
- 输出文件下载链接有效期为 24 小时,请及时下载。如过期需重新提交任务。
- AI 配音功能会产生额外费用,按配音音频时长计费。标准音色和 Professional 音色价格不同。
- 说话人分离和 Professional 引擎也会产生额外费用,建议按需启用。
任务状态说明
Task Status Reference
| Status | 含义 | 下一步 |
|---|---|---|
queued | 任务已提交,等待处理 | 等待几秒后轮询 |
processing | 正在处理中 | 每 5–10 秒轮询一次 |
completed | 处理完成 | 从 result 中获取下载链接 |
failed | 处理失败 | 查看 error 字段了解原因,修正后可重新提交 |
expired | 任务已过期(超过 48 小时未完成) | 重新提交任务 |
iTranslator