调用Transcoder API转码带字幕视频时出现Internal error错误

常见报错原因 #

• 轨道映射配置错误：多音轨、多字幕MKV源文件未在转码任务配置中明确指定选中音轨、字幕轨的输入索引，API因轨道匹配冲突触发内部错误
• 输出字幕封装格式不兼容：选中字幕为PGS/VobSub等位图字幕，未配置烧录或转换为WebVTT格式直接封装进HLS，触发编码链路崩溃
• 源文件元数据损坏：MKV容器的轨道索引标识不规范，API读取轨道元数据失败触发内部错误
• 权限配置缺失：输出GCS存储桶写入权限、源文件读取权限不完整，部分场景下会被API返回为Internal Error而非明确的权限错误

解决方案 #

1. 查看任务完整错误详情 #

执行以下gcloud命令获取任务的全量错误信息，将命令中占位符替换为你实际的项目编号、任务ID：
gcloud transcoder jobs describe JOB-ID --location asia-east1 --project PROJECT-NUMBER
优先查看error.details字段的具体报错内容，确认是否属于轨道匹配、封装格式相关错误。

2. 修正转码任务配置 #

如果需要保留单条音轨+单条字幕，参考以下核心配置片段（仅展示轨道映射核心部分）：

注意：输入轨道索引从0开始计数，你需要提前执行ffprobe 源文件路径确认需要保留的音轨、字幕轨对应的索引值

"editList": [
  {
    "inputs": ["video_input0", "audio_input1", "subtitle_input2"],
    "key": "editted_stream"
  }
],
"elementaryStreams": [
  {
    "key": "video_stream",
    "h264": {
      "widthPixels": 1920,
      "heightPixels": 1080,
      "bitrateBps": 5000000
    }
  },
  {
    "key": "audio_stream",
    "aac": {
      "bitrateBps": 128000,
      "channelCount": 2,
      "sampleRateHertz": 48000
    }
  },
  {
    "key": "subtitle_stream",
    "text": {
      "codec": "webvtt"
    }
  }
],
"muxStreams": [
  {
    "key": "hls_video",
    "container": "ts",
    "elementaryStreams": ["video_stream", "audio_stream"]
  },
  {
    "key": "hls_subtitle",
    "container": "vtt",
    "elementaryStreams": ["subtitle_stream"]
  }
],
"manifests": [
  {
    "fileName": "master.m3u8",
    "type": "HLS",
    "muxStreams": ["hls_video", "hls_subtitle"]
  }
]

3. 特殊场景适配 #

• 如果你选中的是位图字幕，无法直接封装为WebVTT格式，需要在视频编码配置中开启字幕烧录：在h264配置节点下增加"burnInSubtitle": "subtitle_input2"（替换为你实际的字幕输入key），同时删除字幕流单独的elementaryStream和muxStream配置
• 提前用ffprobe验证源文件轨道元数据是否正常，确认对应索引的音轨、字幕轨编码格式属于Transcoder API支持范围

4. 权限校验 #

确认Transcoder API服务账号拥有源GCS对象的storage.objects.get权限，以及输出GCS路径的storage.objects.create权限。

内容的提问来源于stack exchange，提问作者joe-gardner