字幕 APISubtitle 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 EndpointPOST /v1/subtitle/generate
转换端点Convert EndpointPOST /v1/subtitle/convert
认证AuthenticationBearer Token(Authorization 请求头)Bearer Token in Authorization header
输入方式Input Method本地文件上传(multipart/form-data)或视频/音频 URLLocal file upload (multipart/form-data) or video/audio URL
文件上限File Limit最大 500MB,视频最长 4 小时Max 500MB, max 4 hours video
输出格式Output FormatSRT / VTT / ASS / JSON,默认为 SRTSRT / VTT / ASS / JSON, default SRT
支持语言Supported Languages30+ 种语言,支持自动检测和指定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
videofilerequired视频/音频文件,最大 500MB,最长 4 小时Video/audio file, max 500MB, max 4 hours
video_urlstringoptional视频/音频文件的公网可访问 URL(与 video 二选一)Publicly accessible URL of the video/audio file (alternative to video)
source_langstringrequired源语言代码,如 enzh,也支持 auto 自动检测Source language code, e.g. en, zh. Also supports auto for detection
target_langstringoptional翻译目标语言代码,不填则仅生成原文字幕Target language code; omit for source-only subtitles
output_formatstringoptional输出格式:srt / vtt / ass / json,默认 srtOutput format: srt / vtt / ass / json; default srt
mergebooleanoptional是否生成双语合并字幕(原文+译文在同一字幕条),默认 falseGenerate merged bilingual subtitles, default false
max_chars_per_lineintegeroptional每行最大字符数,超出自动换行分割,默认 42Max characters per line, auto-wraps if exceeded, default 42
min_durationnumberoptional每条字幕最短显示时长(秒),默认 1.0Minimum display duration per subtitle in seconds, default 1.0
max_durationnumberoptional每条字幕最长显示时长(秒),默认 7.0Maximum display duration per subtitle in seconds, default 7.0
formalitystringoptional翻译语气:default / formal / informalTranslation tone: default / formal / informal
glossary_idstringoptional关联术语库 ID,翻译时应用自定义术语Glossary ID for custom term mappings during translation
enable_diarizationbooleanoptional是否开启说话人分离,默认 falseEnable speaker diarization, default false
speaker_countintegeroptional预期说话人数量(1-10),配合 diarization 使用Expected speaker count (1-10), used with diarization
subtitle_encodingstringoptional字幕文件编码:utf-8 / utf-8-bom / gbk,默认 utf-8Subtitle file encoding: utf-8 / utf-8-bom / gbk, default utf-8
callback_urlstringoptional异步回调地址,处理完成后 POST 结果到此 URLAsync 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

# 基础用法:生成英文原文 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"

响应参数

Response Parameters

字段Field类型Type说明Description
subtitle_filestring字幕文件的下载 URL(有效期 24 小时)Download URL for the subtitle file (valid 24 hours)
subtitle_jsonarrayJSON 格式的字幕数据,便于程序处理Structured subtitle data in JSON format for programmatic use
subtitle_json[].indexinteger字幕序号,从 1 开始Subtitle index, starts from 1
subtitle_json[].startstring开始时间(HH:MM:SS,mmm 格式)Start time in HH:MM:SS,mmm format
subtitle_json[].endstring结束时间(HH:MM:SS,mmm 格式)End time in HH:MM:SS,mmm format
subtitle_json[].sourcestring原始语言字幕文本Source language subtitle text
subtitle_json[].targetstring翻译后字幕文本(未指定 target_lang 时为空)Translated subtitle text (empty if no target_lang specified)
subtitle_json[].speakerstring说话人标识(开启 diarization 时返回)Speaker label (returned when diarization is enabled)
subtitle_json[].confidencenumberASR 识别置信度(0-1)ASR confidence score (0-1)
formatstring输出字幕格式:srt / vtt / ass / jsonOutput subtitle format: srt / vtt / ass / json
segmentsinteger字幕总条数Total number of subtitle segments
durationnumber视频/音频时长(秒)Video/audio duration in seconds
source_langstring检测到或指定的源语言Detected or specified source language
billed_durationnumber计费时长(秒)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
filefilerequired原始字幕文件(.srt / .vtt / .ass),最大 50MBSource subtitle file (.srt / .vtt / .ass), max 50MB
source_formatstringrequired源格式:srt / vtt / assSource format: srt / vtt / ass
target_formatstringrequired目标格式:srt / vtt / assTarget format: srt / vtt / ass
source_langstringoptional字幕源语言代码,需要翻译时必填Subtitle source language, required if translating
target_langstringoptional翻译目标语言代码,不填则仅转换格式不做翻译Target language code; only convert format if omitted
time_offsetnumberoptional时间轴偏移量(秒),正数延迟、负数提前Timeline offset in seconds; positive delays, negative advances
encodingstringoptional输出编码:utf-8 / utf-8-bom / gbkOutput encoding: utf-8 / utf-8-bom / gbk
fpsnumberoptional帧率(fps),用于 ASS 字幕时间码转换,默认 23.976Frame 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
2000成功Success
4001001参数错误,请检查必填参数和参数格式Invalid parameter; check required fields and format
4001002不支持的输出格式,仅支持 srt/vtt/ass/jsonUnsupported output format, only srt/vtt/ass/json allowed
4001003不支持的语言对Unsupported language pair
4001004字幕文件格式解析失败Subtitle file parsing failed
4012001认证失败,Token 无效或已过期Authentication failed; invalid or expired token
4032003无权限访问该资源Access denied; insufficient permissions
4133001文件大小超出限制(生成最大 500MB,转换最大 50MB)File size exceeds limit (500MB for generate, 50MB for convert)
4153002不支持的文件格式Unsupported file format
4294001请求频率超限,请稍后重试Rate limit exceeded; please retry later
4564002套餐配额已用尽,请升级或等待重置Plan quota exhausted; upgrade or wait for reset
5005001服务器处理失败,请重试或联系技术支持Server processing failed; retry or contact support
5035002服务暂时不可用,建议稍后重试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
使用说明
  • 文件上传使用 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.