保利威文档中心

帮助中心

点播JAVA SDK

subtitleService

更新时间：2026-03-09 16:11:55

1、上传点播视频字幕文件

描述

通过视频id上传点播视频字幕文件
接口地址（仅做说明使用）：https://api.polyv.net/v2/video/%s/srt/upload

调用约束

1、接口调用有频率限制，详细请查看，调用常见异常，详细请查看

单元测试

    @Test
    public void testUploadSubtitle() throws IOException, NoSuchAlgorithmException {
        VodUploadSubtitleRequest vodUploadSubtitleRequest = new VodUploadSubtitleRequest();
        Boolean vodUploadSubtitleResponse = null;
        try {
            String srtCN = getClass().getResource("/subtitle/srt(zh_CN).srt").getPath();
            vodUploadSubtitleRequest.setVideoId("1b448be3234406608b7838c7ef6b597c_1")
                    .setFile(new File(srtCN))
                    .setAsDefault("N")
                    .setTitle("subtitle")
                    .setLanguage(null);
            vodUploadSubtitleResponse = new VodSubtitleServiceImpl().uploadSubtitle(vodUploadSubtitleRequest);
            Assert.assertTrue(vodUploadSubtitleResponse);
            if (vodUploadSubtitleResponse) {
                log.debug("测试上传点播视频字幕文件成功");
            }
        } catch (PloyvSdkException e) {
            //参数校验不合格 或者 请求服务器端500错误，错误信息见PloyvSdkException.getMessage()
            log.error(e.getMessage(), e);
            // 异常返回做B端异常的业务逻辑，记录log 或者 上报到ETL 或者回滚事务
            throw e;
        } catch (Exception e) {
            log.error("SDK调用异常", e);
            throw e;
        }
    }

单元测试说明

1、请求正确，返回Boolean对象，B端依据此对象处理业务逻辑；

2、请求参数校验不合格，抛出PloyvSdkException，错误信息见PloyvSdkException.getMessage()，如 [ 输入参数 [xxx.chat.VodxxxRequest]对象校验失败，失败字段 [pic不能为空 / msg不能为空] ]

3、服务器处理异常，抛出PloyvSdkException，错误信息见PloyvSdkException.getMessage()，如 [ 保利威请求返回数据错误，请求流水号：66e7ad29fd04425a84c2b2b562d2025b，错误原因： invalid signature. ]

请求入参描述

参数名 必选 类型 说明
videoId true String 视频ID【对应api文档的vid字段】
title true String 字幕名称
file true File 字幕文件，支持utf-8编码
asDefault false String 是否作为默认字幕，Y：是，N:否。默认为N:否。首次上传字幕为Y：是
language false String 语言，默认自动检测，支持语言：中文、繁体中文 、英语、日语、韩语、法语、德语、俄语、西班牙语、阿拉伯语、葡萄牙语、其他

返回对象描述

true为上传成功，false为上传失败



2、查询视频字幕

描述

通过视频id查询视频字幕
接口地址（仅做说明使用）：https://api.polyv.net/v2/video/%s/srt/list

调用约束

1、接口调用有频率限制，详细请查看，调用常见异常，详细请查看

单元测试

    @Test
    public void testGetSubtitleList() throws IOException, NoSuchAlgorithmException {
        VodGetSubtitleListRequest vodGetSubtitleListRequest = new VodGetSubtitleListRequest();
        VodGetSubtitleListResponse vodGetSubtitleListResponse = null;
        try {
            vodGetSubtitleListRequest.setVideoId(super.getTestVideoId());
            vodGetSubtitleListResponse = new VodSubtitleServiceImpl().getSubtitleList(vodGetSubtitleListRequest);
            Assert.assertNotNull(vodGetSubtitleListResponse);
            if (vodGetSubtitleListResponse != null) {
                log.debug("测试查询视频字幕成功,{}", JSON.toJSONString(vodGetSubtitleListResponse));
            }
        } catch (PloyvSdkException e) {
            //参数校验不合格 或者 请求服务器端500错误，错误信息见PloyvSdkException.getMessage()
            log.error(e.getMessage(), e);
            // 异常返回做B端异常的业务逻辑，记录log 或者 上报到ETL 或者回滚事务
            throw e;
        } catch (Exception e) {
            log.error("SDK调用异常", e);
            throw e;
        }
    }

单元测试说明

1、请求正确，返回VodGetSubtitleListResponse对象，B端依据此对象处理业务逻辑；

2、请求参数校验不合格，抛出PloyvSdkException，错误信息见PloyvSdkException.getMessage()，如 [ 输入参数 [xxx.chat.VodxxxRequest]对象校验失败，失败字段 [pic不能为空 / msg不能为空] ]

3、服务器处理异常，抛出PloyvSdkException，错误信息见PloyvSdkException.getMessage()，如 [ 保利威请求返回数据错误，请求流水号：66e7ad29fd04425a84c2b2b562d2025b，错误原因： invalid signature. ]

请求入参描述

参数名 必选 类型 说明
videoId true String 视频ID【对应api文档的vid字段】

返回对象描述

参数名 类型 说明
subtitles Array 查询的结果列表【对应api文档的srts字段】【详见Subtitle参数描述】
Subtitle参数描述
参数名 类型 说明
rank Integer 序号，从1开始
name String 字幕名称





3、合并字幕文件

描述

通过视频id与字幕信息合并字幕文件
接口地址（仅做说明使用）：https://api.polyv.net/v2/video/%s/srt/merge

调用约束

1、接口调用有频率限制，详细请查看，调用常见异常，详细请查看

单元测试

    @Test
    public void testMergeSubtitle() throws IOException, NoSuchAlgorithmException {
        VodMergeSubtitleRequest vodMergeSubtitleRequest = new VodMergeSubtitleRequest();
        Boolean vodMergeSubtitleResponse = null;
        try {
            String videoId = super.getTestVideoId();
            //准备测试数据
            String sourceSubtitleNames = super.getSourceSubtitleNames(videoId);
            vodMergeSubtitleRequest.setVideoId(videoId)
                    .setSourceSubtitleNames(sourceSubtitleNames)
                    .setMergedSubtitleName("双语")
                    .setSetAsDefault(Boolean.TRUE);
            vodMergeSubtitleResponse = new VodSubtitleServiceImpl().mergeSubtitle(vodMergeSubtitleRequest);
            Assert.assertTrue(vodMergeSubtitleResponse);
            if (vodMergeSubtitleResponse) {
                log.debug("测试合并字幕文件成功");
            }
        } catch (PloyvSdkException e) {
            //参数校验不合格 或者 请求服务器端500错误，错误信息见PloyvSdkException.getMessage()
            log.error(e.getMessage(), e);
            // 异常返回做B端异常的业务逻辑，记录log 或者 上报到ETL 或者回滚事务
            throw e;
        } catch (Exception e) {
            log.error("SDK调用异常", e);
            throw e;
        }
    }

单元测试说明

1、请求正确，返回Boolean对象，B端依据此对象处理业务逻辑；

2、请求参数校验不合格，抛出PloyvSdkException，错误信息见PloyvSdkException.getMessage()，如 [ 输入参数 [xxx.chat.VodxxxRequest]对象校验失败，失败字段 [pic不能为空 / msg不能为空] ]

3、服务器处理异常，抛出PloyvSdkException，错误信息见PloyvSdkException.getMessage()，如 [ 保利威请求返回数据错误，请求流水号：66e7ad29fd04425a84c2b2b562d2025b，错误原因： invalid signature. ]

请求入参描述

参数名 必选 类型 说明
videoId true String 视频ID【对应api文档的vid字段】
sourceSubtitleNames true String 原始字幕名称，必须传两个值。以英文逗号分隔，合并后第一个字幕的内容在上方显示。【对应api文档的sourceSrtNames字段】
mergedSubtitleName false String 合并字幕的名称，默认：双语。不超过5个中文字符。【对应api文档的mergedSrtName字段】
setAsDefault false Boolean 是否设置为默认显示的字幕。默认值：true。

返回对象描述

true为合并字幕文件成功，false为合并字幕文件失败



4、删除视频字幕

描述

通过视频id与字幕序号列表删除视频字幕
接口地址（仅做说明使用）：https://api.polyv.net/v2/video/%s/srt/delete

调用约束

1、接口调用有频率限制，详细请查看，调用常见异常，详细请查看

单元测试

    @Test
    public void testDeleteSubtitle() throws IOException, NoSuchAlgorithmException {
        VodDeleteSubtitleRequest vodDeleteSubtitleRequest = new VodDeleteSubtitleRequest();
        Boolean vodDeleteSubtitleResponse = null;
        try {
            //准备测试数据
            String videoId = super.getTestVideoId();
            if (super.getSubtitleList(videoId).isEmpty()) {
                uploadSubtitle(videoId, false);
            }
            String ranks = getRanks(videoId);
            vodDeleteSubtitleRequest.setVideoId(videoId).setRanks(ranks);
            vodDeleteSubtitleResponse = new VodSubtitleServiceImpl().deleteSubtitle(vodDeleteSubtitleRequest);
            Assert.assertTrue(vodDeleteSubtitleResponse);
            if (vodDeleteSubtitleResponse) {
                log.debug("测试删除视频字幕成功");
            }
        } catch (PloyvSdkException e) {
            //参数校验不合格 或者 请求服务器端500错误，错误信息见PloyvSdkException.getMessage()
            log.error(e.getMessage(), e);
            // 异常返回做B端异常的业务逻辑，记录log 或者 上报到ETL 或者回滚事务
            throw e;
        } catch (Exception e) {
            log.error("SDK调用异常", e);
            throw e;
        }
    }

单元测试说明

1、请求正确，返回Boolean对象，B端依据此对象处理业务逻辑；

2、请求参数校验不合格，抛出PloyvSdkException，错误信息见PloyvSdkException.getMessage()，如 [ 输入参数 [xxx.chat.VodxxxRequest]对象校验失败，失败字段 [pic不能为空 / msg不能为空] ]

3、服务器处理异常，抛出PloyvSdkException，错误信息见PloyvSdkException.getMessage()，如 [ 保利威请求返回数据错误，请求流水号：66e7ad29fd04425a84c2b2b562d2025b，错误原因： invalid signature. ]

请求入参描述

参数名 必选 类型 说明
videoId true String 视频ID【对应api文档的vid字段】
ranks true String 字幕序号列表，序号从1开始，多个以英文逗号分隔，例如 2,3

返回对象描述

true为删除字幕成功，false为删除字幕失败



5、创建智能字幕任务

描述

通过视频id创建智能字幕任务，为视频自动生成一份智能字幕文件
接口地址（仅做说明使用）：https://api.polyv.net/vod/v4/smart-subtitle/create

调用约束

1、接口调用有频率限制，详细请查看，调用常见异常，详细请查看
2、创建智能字幕任务依赖点播视频已发布且时长不超过接口限制，详细说明参考 API 文档

单元测试

    @Test
    public void testCreateSmartSubtitleTask() throws IOException, NoSuchAlgorithmException {
        VodSubtitleServiceImpl service = new VodSubtitleServiceImpl();
        String videoId = super.getTestVideoId();
        Long taskId = null;
        try {
            VodCreateSmartSubtitleTaskRequest createRequest = new VodCreateSmartSubtitleTaskRequest()
                    .setVid(videoId)
                    .setLanguage("chinese")
                    .setAutoApplyEnabled("N")
                    .setRepetitionEnabled("Y");
            taskId = service.createSmartSubtitleTask(createRequest);
            Assert.assertNotNull(taskId);
            log.debug("测试创建智能字幕任务成功, taskId={}", taskId);
        } catch (PloyvSdkException e) {
            log.error(e.getMessage(), e);
            throw e;
        } catch (Exception e) {
            log.error("SDK调用异常", e);
            throw e;
        }
    }

单元测试说明

1、请求正确，返回 Long 类型的字幕任务ID，B端依据此ID后续查询、更新或发布智能字幕；
2、请求参数校验不合格，抛出 PloyvSdkException；
3、服务器处理异常，抛出 PloyvSdkException。

请求入参描述

参数名 必选 类型 说明
vid true String 视频ID，对应 API 文档中的 vid 字段
autoApplyEnabled false String 是否在字幕生成后自动应用字幕到对应的视频上，Y 或 N，默认按后端配置
language false String 智能识别语种，支持枚举值详见 API 文档，未传或传入不支持值时按中文处理
repetitionEnabled false String 是否允许重复任务，Y-允许，N-不允许，默认Y

返回对象描述

返回 Long 类型，表示创建成功的智能字幕任务ID





6、查询智能字幕内容

描述

通过字幕任务id，查询智能字幕的下载链接及逐条字幕内容
接口地址（仅做说明使用）：https://api.polyv.net/vod/v4/smart-subtitle/get

调用约束

1、接口调用有频率限制，详细请查看，调用常见异常，详细请查看
2、需确保字幕任务已完成解析，未完成时接口会返回相应错误码

单元测试

    @Test
    public void testQuerySmartSubtitle() throws IOException, NoSuchAlgorithmException {
        VodSubtitleServiceImpl service = new VodSubtitleServiceImpl();
        // 这里依赖调用方预先准备好的有效 taskId
        Long taskId = 1L;
        try {
            VodQuerySmartSubtitleRequest queryRequest = new VodQuerySmartSubtitleRequest()
                    .setTaskId(taskId);
            VodQuerySmartSubtitleResponse queryResponse = service.querySmartSubtitle(queryRequest);
            Assert.assertNotNull(queryResponse);
            log.debug("测试查询智能字幕内容成功,{}", JSON.toJSONString(queryResponse));
        } catch (PloyvSdkException e) {
            log.error(e.getMessage(), e);
            throw e;
        } catch (Exception e) {
            log.error("SDK调用异常", e);
            throw e;
        }
    }

单元测试说明

1、请求正确，返回 VodQuerySmartSubtitleResponse 对象，B端依据此对象中的 link 和 subtitles 字段处理业务逻辑；
2、请求参数校验不合格，抛出 PloyvSdkException；
3、服务器处理异常，抛出 PloyvSdkException。

请求入参描述

参数名 必选 类型 说明
taskId true Long 智能字幕任务ID，创建任务时返回

返回对象描述

参数名 类型 说明
taskId Long 智能字幕任务ID
link String 字幕文件下载链接
autoApplyEnabled String 是否在字幕生成后自动应用到视频上，Y/N
subtitleName String 字幕标题
preferenceEnabled String 是否为默认首选字幕，Y/N
subtitles Array 字幕内容列表，逐条字幕信息

其中 subtitles 元素结构：

参数名 类型 说明
start Long 单条字幕相对视频播放的开始时间，单位毫秒
end Long 单条字幕相对视频播放的结束时间，单位毫秒
content String 单条字幕内容





7、查询智能字幕链接

描述

通过视频id查询该视频关联的智能字幕任务及字幕链接列表
接口地址（仅做说明使用）：https://api.polyv.net/vod/v4/smart-subtitle/subtitle-link/get

调用约束

1、接口调用有频率限制，详细请查看，调用常见异常，详细请查看

单元测试

    @Test
    public void testQuerySmartSubtitleLink() throws IOException, NoSuchAlgorithmException {
        VodSubtitleServiceImpl service = new VodSubtitleServiceImpl();
        String videoId = super.getTestVideoId();
        try {
            VodQuerySmartSubtitleLinkRequest linkRequest = new VodQuerySmartSubtitleLinkRequest()
                    .setVid(videoId);
            List<VodQuerySmartSubtitleLinkResponse> linkResponseList = service.querySmartSubtitleLink(linkRequest);
            Assert.assertNotNull(linkResponseList);
            log.debug("测试查询智能字幕链接成功,{}", JSON.toJSONString(linkResponseList));
        } catch (PloyvSdkException e) {
            log.error(e.getMessage(), e);
            throw e;
        } catch (Exception e) {
            log.error("SDK调用异常", e);
            throw e;
        }
    }

单元测试说明

1、请求正确，返回智能字幕链接列表；
2、请求参数校验不合格或服务器异常时抛出 PloyvSdkException。

请求入参描述

参数名 必选 类型 说明
vid true String 视频ID

返回对象描述

返回 List<VodQuerySmartSubtitleLinkResponse>，每个元素结构：

参数名 类型 说明
taskId Long 智能字幕任务ID
link String 字幕文件下载链接
vid String 视频ID





8、更新智能字幕内容

描述

通过字幕任务id更新智能字幕内容，可用于人工校对后覆盖原有字幕
接口地址（仅做说明使用）：https://api.polyv.net/vod/v4/smart-subtitle/update

调用约束

1、接口调用有频率限制，详细请查看，调用常见异常，详细请查看
2、字幕任务需处于可更新状态，具体限制详见 API 文档

单元测试

    @Test
    public void testUpdateSmartSubtitle() throws IOException, NoSuchAlgorithmException {
        VodSubtitleServiceImpl service = new VodSubtitleServiceImpl();
        Long taskId = 1L;
        try {
            VodUpdateSmartSubtitleRequest.SubtitleItem item = new VodUpdateSmartSubtitleRequest.SubtitleItem()
                    .setStart(0L)
                    .setEnd(1000L)
                    .setContent("智能字幕测试");
            VodUpdateSmartSubtitleRequest updateRequest = new VodUpdateSmartSubtitleRequest()
                    .setTaskId(taskId)
                    .setSubtitleName("智能字幕测试")
                    .setAutoApplyEnabled("N")
                    .setPreferenceEnabled("Y")
                    .setSubtitles(Collections.singletonList(item));
            Boolean updateResult = service.updateSmartSubtitle(updateRequest);
            Assert.assertTrue(updateResult);
            log.debug("测试更新智能字幕内容成功");
        } catch (PloyvSdkException e) {
            log.error(e.getMessage(), e);
            throw e;
        } catch (Exception e) {
            log.error("SDK调用异常", e);
            throw e;
        }
    }

单元测试说明

1、请求正确，返回 Boolean，true 表示更新成功；
2、请求参数校验不合格或服务器异常时抛出 PloyvSdkException。

请求入参描述

参数名 必选 类型 说明
taskId true Long 智能字幕任务ID
autoApplyEnabled false String 是否在修改完字幕内容后自动发布该字幕，Y/N，不传按任务预设值
subtitleName false String 字幕标题，长度限制20个字符
preferenceEnabled false String 发布后是否默认首选该字幕，Y/N，不传按任务预设值
subtitles true List 字幕内容列表

subtitles 元素结构：

参数名 必选 类型 说明
start true Long 单条字幕开始时间，单位毫秒
end true Long 单条字幕结束时间，单位毫秒
content true String 单条字幕内容

返回对象描述

true 为更新成功，false 为更新失败





9、发布智能字幕

描述

通过字幕任务id将智能字幕应用到视频上
接口地址（仅做说明使用）：https://api.polyv.net/vod/v4/smart-subtitle/publish

调用约束

1、接口调用有频率限制，详细请查看，调用常见异常，详细请查看
2、仅在任务状态允许的场景下才能发布

单元测试

    @Test
    public void testPublishSmartSubtitleTask() throws IOException, NoSuchAlgorithmException {
        VodSubtitleServiceImpl service = new VodSubtitleServiceImpl();
        Long taskId = 1L;
        try {
            VodPublishSmartSubtitleTaskRequest publishRequest = new VodPublishSmartSubtitleTaskRequest()
                    .setTaskId(taskId)
                    .setPreferenceEnabled("Y");
            Boolean publishResult = service.publishSmartSubtitleTask(publishRequest);
            Assert.assertTrue(publishResult);
            log.debug("测试发布智能字幕成功");
        } catch (PloyvSdkException e) {
            log.error(e.getMessage(), e);
            throw e;
        } catch (Exception e) {
            log.error("SDK调用异常", e);
            throw e;
        }
    }

单元测试说明

1、请求正确，返回 Boolean，true 表示发布成功；
2、请求参数校验不合格或服务器异常时抛出 PloyvSdkException。

请求入参描述

参数名 必选 类型 说明
taskId true Long 智能字幕任务ID
preferenceEnabled false String 是否默认首选当前字幕，Y/N，不传按任务预设值

返回对象描述

true 为发布成功，false 为发布失败





10、删除智能字幕任务

描述

通过字幕任务id删除智能字幕任务及对应字幕文件
接口地址（仅做说明使用）：https://api.polyv.net/vod/v4/smart-subtitle/delete

调用约束

1、接口调用有频率限制，详细请查看，调用常见异常，详细请查看
2、仅在任务状态允许的场景下才能删除

单元测试

    @Test
    public void testDeleteSmartSubtitleTask() throws IOException, NoSuchAlgorithmException {
        VodSubtitleServiceImpl service = new VodSubtitleServiceImpl();
        Long taskId = 1L;
        try {
            VodDeleteSmartSubtitleTaskRequest deleteRequest = new VodDeleteSmartSubtitleTaskRequest()
                    .setTaskId(taskId);
            Boolean deleteResult = service.deleteSmartSubtitleTask(deleteRequest);
            Assert.assertTrue(deleteResult);
            log.debug("测试删除智能字幕任务成功");
        } catch (PloyvSdkException e) {
            log.error(e.getMessage(), e);
            throw e;
        } catch (Exception e) {
            log.error("SDK调用异常", e);
            throw e;
        }
    }

单元测试说明

1、请求正确，返回 Boolean，true 表示删除成功；
2、请求参数校验不合格或服务器异常时抛出 PloyvSdkException。

请求入参描述

参数名 必选 类型 说明
taskId true Long 智能字幕任务ID

返回对象描述

true 为删除成功，false 为删除失败

联系客服，在线咨询