保利威文档中心

幫助中心

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 為刪除失敗

联系客服，在线咨询