视频翻译Video Translation

上传视频文件,自动提取音轨、进行语音识别(ASR)并翻译,生成多语言字幕文件(SRT/VTT/ASS)或直接输出翻译后的视频。支持硬字幕烧录、AI 配音、说话人分离等高级功能,满足影视字幕、课程翻译、企业宣传片等多场景需求。Upload video files for automatic audio extraction, ASR, translation and multilingual subtitle (SRT/VTT/ASS) generation. Supports hard subtitle burning, AI dubbing, speaker diarization and more for film subtitling, course translation, corporate videos, etc.

快速概览

Quick Overview

属性Attribute说明Description
端点EndpointPOST /v1/video/translate
认证AuthenticationBearer Token(Authorization 请求头)Bearer Token in Authorization header
输入方式Input Method本地文件上传(multipart/form-data)或视频 URLLocal file upload (multipart/form-data) or video URL
视频上限Video Limit最大 500MB,最长 3 小时Max 500MB, max 3 hours
处理模式Processing Mode异步任务(返回 task_id 轮询)+ 可选 Webhook 回调Async task (poll with task_id) + optional Webhook callback
输出形式Output Types纯字幕文件(SRT/VTT/ASS)、硬字幕视频、AI 配音视频、双语字幕Subtitle files (SRT/VTT/ASS), burned-in subtitle video, AI dubbed video, bilingual subtitles
字幕样式Subtitle Styles可自定义字体、大小、颜色、位置、背景、描边等Customizable font, size, color, position, background, stroke, etc.
支持语言Languages中文、英语、日语、韩语、法语、德语、西班牙语等 50+ 种语言Chinese, English, Japanese, Korean, French, German, Spanish and 50+ more
处理时长Processing Time约为视频时长的 30%~60%(取决于视频长度和所选功能)Approximately 30%-60% of video duration (varies by video length and features selected)

请求端点

Endpoint

POST/v1/video/translate

认证

Authentication

Authorization: Bearer {access_token}

请求参数

Request Parameters

⏰ 异步任务
视频翻译为异步任务,首次请求返回 task_id,可通过任务查询接口获取处理进度和结果。也支持 callback_url Webhook 回调通知。Video translation is an async task. Returns a task_id immediately; poll or use callback_url webhook for results.

基础参数

Basic Parameters

参数Parameter类型Type必填Required说明Description
filefileconditional视频文件(与 video_url 二选一),最大 500MB,最长 3 小时Video file (use with video_url), max 500MB, max 3 hours
video_urlstringconditional视频的公开可访问 URL(与 file 二选一)Publicly accessible video URL (use with file)
target_langstringrequired目标翻译语言代码Target language code
source_langstringoptional源语言代码,不传或 auto 则自动检测Source language, auto-detected if omitted or auto
output_formatstringoptionalsrt(默认)/ vtt / ass / burned_video(硬字幕视频)/ all。详见输出模式srt(default)/vtt/ass/burned_video/all. See Output Modes
bilingualbooleanoptional是否生成双语字幕,默认 falseGenerate bilingual subtitles, default false
enginestringoptionalstandard(通用,默认)/ professional(专业,影视/法律/医学内容,更高准确率)standard(default)/professional(film/legal/medical, higher accuracy)
callback_urlstringoptionalWebhook 回调地址,任务完成后向该地址 POST 结果Webhook URL to receive POST when task completes
glossary_idstringoptional术语库 ID,确保特定词汇翻译一致性(品牌名、专业术语等)Glossary ID for consistent term translation (brands, technical terms)

字幕样式参数(output_format=burned_video 时适用)

Subtitle Style Parameters (for burned_video)

参数Parameter类型Type必填Required默认值Default说明Description
subtitle_fontstringoptionalPingFang SC字幕字体名称。支持系统内置字体和已上传的自定义字体Font name for subtitles. Supports system & custom fonts
subtitle_sizeintegeroptional24字幕字号(px),推荐 18–36Subtitle font size (px), 18–36 recommended
subtitle_colorstringoptional#FFFFFF字幕文字颜色(HEX 格式)Text color in HEX
subtitle_outlinestringoptional#000000字幕描边颜色。设为空字符串则无描边Outline/stroke color. Empty = no stroke
subtitle_outline_widthfloatoptional2.0描边宽度(px),1.0–4.0Stroke width (px), 1.0–4.0
subtitle_bgstringoptional字幕背景色(含透明度),如 #00000080Background color with alpha, e.g. #00000080
subtitle_positionstringoptionalbottombottom(底部)/ top(顶部)/ middle(居中)bottom/top/middle

AI 配音参数

AI Dubbing Parameters

参数Parameter类型Type必填Required默认值Default说明Description
enable_dubbingbooleanoptionalfalse是否启用 AI 配音,将翻译后文本用合成语音替换原音轨Enable AI dubbing to replace original audio with synthesized speech
dubbing_voicestringoptionaldefault-femaledefault-female / default-male / professional-female / professional-maledefault-female/default-male/professional-female/professional-male
dubbing_speedfloatoptional1.0配音语速,0.5–2.0Dubbing speed, 0.5–2.0
dubbing_bg_musicfloatoptional0.3保留原视频背景音乐音量比例,0.0–1.0。0 则替换全部音轨Background music retention ratio, 0.0–1.0. 0 = replace all audio

高级参数

Advanced Parameters

参数Parameter类型Type必填Required默认值Default说明Description
enable_diarizationbooleanoptionalfalse启用说话人分离,在字幕中标注 [Speaker 1][Speaker 2]Enable speaker diarization with labels like [Speaker 1], [Speaker 2]
speaker_countintegeroptional预期说话人数,不指定则自动推断Expected number of speakers, auto-detected if omitted
max_subtitle_lengthintegeroptional42每行字幕最大字符数,超出自动换行或拆分Max chars per subtitle line, auto-wrap or split if exceeded
subtitle_max_durationfloatoptional5.0单条字幕最长秒数,2.0–10.0,超时自动切分Max subtitle duration in seconds, 2.0–10.0, auto-split if exceeded
profanity_filterbooleanoptionalfalse启用敏感词过滤,用 *** 替换不雅词汇Enable profanity filter, replace offensive words with ***
start_timefloatoptional0仅翻译从指定秒数开始的片段Start time in seconds for partial translation
end_timefloatoptional仅翻译到指定秒数为止的片段End time in seconds for partial translation

输出模式

Output Modes

output_format 参数决定了最终产物的形式:

The output_format parameter determines the output type:

输出内容Output适用场景Use Case
srtSRT 字幕文件SRT subtitle file通用字幕,兼容几乎所有播放器和编辑软件Universal, compatible with almost all players
vttWebVTT 字幕文件WebVTT subtitle fileWeb 播放器(HTML5)、YouTube 等在线平台首选Preferred for web players, YouTube, etc.
assASS/SSA 高级字幕ASS/SSA advanced subtitle丰富样式(字体、颜色、动画、卡拉OK),适合影视后期和特效字幕Rich styling for film post-production and special effects
burned_video带硬字幕的视频文件Video with burned-in subtitles字幕不可关闭,适合社交媒体分发、短视频平台上传Permanent subtitles for social media, short videos
all以上全部格式All formats above一次性获取所有格式,适合多用途场景Get all formats at once for multi-purpose use

支持视频格式

Supported Video Formats

格式Format视频编码Video Codec音频编码Audio Codec推荐Recommend
.mp4H.264, H.265AAC, MP3首选Best
.movH.264, ProResAAC, PCMApple 常用Apple ecosystem
.mkvH.264, H.265, VP9AAC, Opus, FLAC多音轨取第一条First audio track
.aviMJPEG, H.264MP3, PCM需确保音轨可解析Ensure parseable audio
.webmVP8, VP9Opus, VorbisWeb 常用Web common
.flvH.264AAC, MP3直播录制常见Live recordings
.wmvWMVWMA建议先转 MP4Convert to MP4 first

💡 建议:使用 H.264 + AAC 编码的 MP4 格式,分辨率 ≥ 720p,帧率 ≥ 25fps,可获得最佳处理速度和识别准确率。💡 Tip: Use H.264 + AAC MP4 at ≥ 720p, ≥ 25fps for best speed and accuracy.

请求示例

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

提交任务后立即返回:

Immediate response after task submission:

字段Field类型Type说明Description
task_idstring任务唯一标识,用于轮询进度Unique task ID for polling progress
statusstring初始状态为 queuedInitial status: queued
created_atstring任务创建时间(ISO 8601)Task creation time (ISO 8601)
estimated_secondsinteger预计处理时长(秒)Estimated processing time (seconds)

任务完成后 result 字段包含:

After completion, result contains:

字段Field类型Type说明Description
subtitle_urlstring字幕文件下载链接(output_format 为 srt/vtt/ass 时)Subtitle file download URL (for srt/vtt/ass)
video_urlstring处理后视频下载链接(output_format 为 burned_video 或启用配音时)Processed video download URL (for burned_video or dubbing)
filesobjectoutput_format 为 all 时,按格式分组的下载链接字典When output is all, download URLs grouped by format
durationfloat视频时长(秒)Video duration (seconds)
char_countinteger翻译总字符数Total translated characters
source_langstring检测到的源语言代码Detected source language code

查询任务状态

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 字段了解当前处理进度:

Video translation consists of the following stages, trackable via the stage field:

Stage说明Description预估耗时占比Estimated Share
validating校验视频格式、大小和音轨Validating video format, size, and audio track~2%
extracting从视频中提取音频轨道Extracting audio track from video~10%
recognizing对提取的音频进行语音识别(ASR)Running ASR on extracted audio~30%
diarizing说话人分离(仅 enable_diarization=true 时)Speaker diarization (only if enabled)~15%
translating对识别文本进行翻译Translating recognized text~25%
synthesizing生成字幕文件或烧录字幕/AI 配音合成(仅启用配音时)Generating subtitles, burning-in, or synthesizing dubbing audio~18%
packaging打包输出文件并上传至 CDNPackaging output and uploading to CDN~5%

回调通知(Webhook)

Callback Notifications (Webhook)

提交任务时指定 callback_url,任务完成后会向该地址 POST 结果,避免轮询:

Specify callback_url when submitting to receive results via POST when the task completes:

POST https://your-server.com/webhook/translate
Content-Type: application/json
X-Signature: sha256=abcd1234...  ← 用于验证请求来源← for verifying source

{
  "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) 的十六进制结果。建议验证签名以防止伪造回调。🔐 Verify Signature: Callback includes X-Signature header = hex of HMAC-SHA256(callback_url, YOUR_SECRET_KEY). Verify to prevent forged callbacks.

错误码

Error Codes

Status错误码Code说明Description
400UNSUPPORTED_VIDEO不支持的视频格式Unsupported video format
400VIDEO_TOO_LARGE视频超过 500MB 或 3 小时限制Video exceeds 500MB or 3-hour limit
400NO_AUDIO_TRACK视频中未检测到音轨No audio track detected in video
400INVALID_LANG_CODE不支持的语言代码Unsupported language code
400INVALID_URLvideo_url 无效或无法访问Invalid or inaccessible video_url
400GLOSSARY_NOT_FOUND指定的术语库不存在或无权限访问Glossary not found or permission denied
401UNAUTHORIZED未提供认证信息或 Token 无效Missing or invalid access token
402QUOTA_EXCEEDED配额不足,请升级套餐Quota exceeded, please upgrade plan
429RATE_LIMITED请求过于频繁,请稍后重试Rate limited, please retry later
500INTERNAL_ERROR内部服务错误,可重试Internal server error, retryable
503SERVICE_BUSY服务繁忙,任务排队中Service busy, task queued

最佳实践

Best Practices

  1. 指定源语言:如果已知视频的源语言,显式指定 source_lang 而非依赖自动检测,可显著提高 ASR 识别准确率和翻译质量。
  2. Specify source language: Explicitly set source_lang instead of auto-detect when known, significantly improving ASR accuracy and translation quality.
  3. 使用术语库:对于包含大量专业术语或品牌名称的视频,提前创建术语库并传入 glossary_id,确保翻译一致性。
  4. Use glossary: For videos with technical terms or brand names, create a glossary in advance and pass glossary_id for consistent translation.
  5. 选择合适的输出格式:社交分发推荐 burned_video + 字幕样式定制;专业后期推荐 ass 格式;Web 播放推荐 vtt
  6. Choose right output: burned_video for social media; ass for post-production; vtt for web playback.
  7. 视频预处理:确保视频音质清晰、背景噪音尽量低。嘈杂环境录制的视频建议先降噪处理。
  8. Preprocess video: Ensure clear audio with minimal background noise. Consider denoising for noisy videos first.
  9. 优选 MP4 格式:MP4 (H.264 + AAC) 处理速度最快,复杂编码格式(如 ProRes)需要额外转码时间。
  10. Prefer MP4: MP4 with H.264+AAC has the fastest processing speed. Complex codecs like ProRes require extra transcoding.
  11. Webhook 优于轮询:生产环境建议使用 callback_url 接收结果,减少轮询开销和 API 消耗。
  12. Webhook over polling: In production, use callback_url to receive results, reducing polling overhead and API consumption.
  13. 说话人分离场景:多人对话场景(访谈、会议、多人播客)建议启用 enable_diarization,如知道人数则指定 speaker_count
  14. Speaker diarization: Enable for multi-speaker scenarios (interviews, meetings, multi-host podcasts). Specify speaker_count if known.

典型应用场景

Typical Use Cases

场景Scenario推荐配置Recommended Config
📚 在线课程多语言发布📚 Online course multilingual publishing output_format=srt, bilingual=true, engine=professional
🎬 影视字幕翻译🎬 Film subtitle translation output_format=ass, enable_diarization=true, subtitle_max_duration=3.0
📱 短视频平台出海📱 Short video platform export output_format=burned_video, custom subtitle styles, profanity_filter=true
🎤 访谈/播客国际化🎤 Interview/podcast internationalization enable_dubbing=true, dubbing_voice=professional-female, enable_diarization=true
🏢 企业宣传片本地化🏢 Corporate video localization output_format=all, engine=professional, glossary_id=xxx
🎮 游戏预告/实况翻译🎮 Game trailer/stream translation output_format=burned_video, subtitle_position=top, bilingual subtitles
使用说明
  • 文件上传使用 multipart/form-data 编码,Content-Type 请勿手动设置,让 HTTP 客户端自动生成 boundary。
  • Use multipart/form-data encoding; let the HTTP client auto-generate Content-Type with boundary.
  • 大文件建议通过 video_url 传入直链,或使用分片上传避免请求超时。
  • For large files, use video_url with a direct link or chunked upload to avoid timeouts.
  • 请勿在客户端代码中暴露 Access Token,建议通过后端代理调用。
  • Do not expose your Access Token in client-side code; use a backend proxy.
  • 输出文件下载链接有效期为 24 小时,请及时下载。如过期需重新提交任务。
  • Output download links expire after 24 hours. Re-submit the task if expired.
  • AI 配音功能会产生额外费用,按配音音频时长计费。标准音色和 Professional 音色价格不同。
  • AI dubbing incurs additional charges based on dubbed audio duration. Standard and Professional voices have different pricing.
  • 说话人分离和 Professional 引擎也会产生额外费用,建议按需启用。
  • Speaker diarization and Professional engine also incur additional charges; enable only when needed.

任务状态说明

Task Status Reference

Status含义Meaning下一步Next Step
queued任务已提交,等待处理Submitted, awaiting processing等待几秒后轮询Wait a few seconds then poll
processing正在处理中Processing in progress每 5–10 秒轮询一次Poll every 5–10 seconds
completed处理完成Successfully completedresult 中获取下载链接Retrieve download URLs from result
failed处理失败Processing failed查看 error 字段了解原因,修正后可重新提交Check error field, fix and resubmit
expired任务已过期(超过 48 小时未完成)Task expired (pending > 48 hours)重新提交任务Resubmit the task