保利威文档中心

幫助中心

uploadService

更新時間：2026-01-15 16:33:56

1、上傳本地影片

描述

1、快捷上传多种格式的媒体文件。
2、支持上传时的各种设置，如文件标题、描述、标签、上传目录、是否开启课件优化处理等。
3、采用分片并发上传的方式，支持断点续传，续传请查看当前文档下一个方法。
4、PolyvUploadClient.uploadVideo()方法三个参数分别为 分片上传本地视频请求实体、上传回调、是否打印日志
接口地址（仅做说明使用）：https://api.polyv.net/

呼叫限制

1、介面呼叫有頻率限制，詳細請查看，呼叫常見異常，詳細請查看

單元測試

    @Test
    public void testUploadVideoPart() {
        VodUploadVideoRequest vodUploadVideoRequest = new VodUploadVideoRequest();
        Boolean vodUploadVideoResponse;
        String videoFile = getClass().getResource("/file/polyv.mp4").getPath();
        //构建视频上传客户端，可传入分片大小（默认为1MB,大小限定为100KB~5GB），分片文件夹路径（默认为checkpoint_location），上传线程数（默认为5个），此对象全局唯一
        PolyvUploadClient client = new PolyvUploadClient(1024 * 1024, "checkpoint_location", 5);
        vodUploadVideoRequest.setFile(new File(videoFile))
                .setTitle("保利威宣传视频")
                .setDescribe("保利威是全球领先的企业直播服务商，隶属于广州易方信息科技股份有限公司，致力于通过可集成、可定制的视频直播技术，为企业搭建自主私域直播系统，并提供直播全流程运营与现场执行服务。")
                .setTag("宣传视频")
                //.setCategoryId("1622165542751")
                .setScreenCap(0)
                .setKeepSource(0)
                .setState("junitTest")
                .setWatermarkLocation("1")
                .setWatermark("https://water/1/146b754735/water_146b7547351767584889357_1.png");
        vodUploadVideoResponse = client.buildOSSService(vodUploadVideoRequest).upload(new UploadCallBack() {
            @Override
            public void start(String videoPoolId) {
                log.debug("开始分片上传视频，videoId：{}", videoPoolId);
            }
            @Override
            public void process(String videoPoolId, long hasUploadBytes, long totalFileBytes) {
                log.debug("分片上传成功，videoId：{}，已上传分片大小：{}，总视频大小{}", videoPoolId, hasUploadBytes, totalFileBytes);
            }
            @Override
            public void complete(String videoPoolId) {
                log.debug("所有分片上传成功，videoId：{}", videoPoolId);
            }
            @Override
            public void success(String videoPoolId) {
                log.debug("所有分片上传成功并处理完成，请等待后台审核，videoId：{}", videoPoolId);
            }
            @Override
            public void error(String videoPoolId, UploadErrorMsg errorMsg) {
                log.error("上传视频失败，videoId：{}，错误信息：{}", videoPoolId, errorMsg);
            }
        }, false);
    }

單元測試說明

1、請求正確，回傳 Boolean 物件，B 端依據此物件處理業務邏輯；

2、請求參數驗證不合格，拋出 PloyvSdkException，錯誤資訊見 PloyvSdkException.getMessage()，如 [ 輸入參數 [xxx.chat.VodxxxRequest] 物件驗證失敗，失敗欄位 [pic不能為空 / msg不能為空] ]

3、伺服器處理異常，拋出 PloyvSdkException，錯誤資訊見 PloyvSdkException.getMessage()，如 [ 保利威請求回傳資料錯誤，請求流水號：66e7ad29fd04425a84c2b2b562d2025b，錯誤原因： invalid signature. ]

請求參數說明

參數名 必選 類型 說明
title false String 影片標題，預設使用帶副檔名的檔案名稱，如：test.mp4
describe false String 影片簡介，預設為空
tag false String 影片標籤，多個使用英文逗號分隔，預設為空
categoryId false String 影片所屬分類，預設為「預設分類」
screenCap false Integer 是否錄影優化。當值為1時，上傳的影片不再採用預設的壓縮編碼機制，影片尺寸不再壓縮，保證影片的清晰度。預設值為0
keepSource false Integer 原始檔案播放，1為開啟，0為關閉；開啟時不對影片進行轉碼（僅對新上傳影片有效），預設值為0:非原始檔案播放
file true File 上傳的影片檔案
state false String 如果提交了該欄位，會在上傳完成的事件回呼中透傳回傳
watermark false string 自訂浮水印圖片位址，圖片格式必須是png格式，支援http、https
watermarkLocation false string 自訂浮水印圖片位置，如無該參數，則自訂浮水印的顯示情況跟隨分類和帳號。1：左上角；2：右上角；3：左下角；4：右下角

回傳物件說明

上傳成功回傳 true，上傳失敗回傳 false，回呼 error 方法回傳影片 id，可以呼叫「斷點續傳本地影片」進行續傳影片。



2、斷點續傳本地影片

描述

断点续传未上传成功的本地视频文件
PolyvUploadClient.uploadVideo()方法三个参数分别为 分片上传本地视频请求实体、上传回调、是否打印日志
接口地址（仅做说明使用）：https://api.polyv.net/

呼叫限制

1、介面呼叫有頻率限制，詳細請查看，呼叫常見異常，詳細請查看

單元測試

    @Test
    public void testUploadVideoPartSequel() {
        VodUploadVideoPartsRequest vodUploadVideoPartsRequest = new VodUploadVideoPartsRequest();
        Boolean vodUploadVideoResponse;
        String videoFile = getClass().getResource("/file/polyv.mp4").getPath();
        String videoId = "ac59aff03d153b3ed5d7f64194279af9_a";
        vodUploadVideoPartsRequest.setFile(new File(videoFile)).setVideoId(videoId);
        try {
            PolyvUploadClient client = new PolyvUploadClient(1024 * 1024, "checkpoint_location", 5);
            vodUploadVideoResponse = client.buildOSSService(vodUploadVideoPartsRequest).upload(new UploadCallBack() {
                @Override
                public void start(String videoPoolId) {
                    log.debug("开始分片上传视频，videoId：{}", videoPoolId);
                }
                @Override
                public void process(String videoPoolId, long hasUploadBytes, long totalFileBytes) {
                    log.debug("分片上传成功，videoId：{}，已上传分片大小：{}，总视频大小{}", videoPoolId, hasUploadBytes, totalFileBytes);
                }
                @Override
                public void complete(String videoPoolId) {
                    log.debug("所有分片上传成功，videoId：{}", videoPoolId);
                }
                @Override
                public void success(String videoPoolId) {
                    log.debug("所有分片上传成功并处理完成，请等待后台审核，videoId：{}", videoPoolId);
                }
                @Override
                public void error(String videoPoolId, UploadErrorMsg errorMsg) {
                    log.error("上传视频失败，videoId：{}，错误信息：{}", videoPoolId, errorMsg);
                }
            }, false);
            log.debug("测试续传视频返回状态:{}", vodUploadVideoResponse);
        } 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. ]

請求參數說明

參數名 必選 類型 說明
file true File 上傳的影片檔案
videoId true String 續傳的影片 id
state false String 如果提交了該欄位，會在上傳完成的事件回呼中透傳回傳

回傳物件說明

上傳成功回傳影片 id，上傳失敗回呼也回傳影片 id



3、上傳遠端影片

描述

上传远程视频（异步上传），具体上传情况可调用“分页查询视频同步列表”查看
接口地址（仅做说明使用）：https://api.polyv.net/v2/video/grab/%s/upload/multi

呼叫限制

1、介面呼叫有頻率限制，詳細請查看，呼叫常見異常，詳細請查看

2、浮水印連結必須為 png 格式

3、uploadInfos 和 （fileUrl、title）必傳其一，並且 uploadInfos 的優先級高於 （fileUrl、title），建議使用 uploadInfos

單元測試

    @Test
    public void testUploadHttpVideoList() throws IOException, NoSuchAlgorithmException {
        VodUploadHttpVideoListRequest vodUploadHttpVideoListRequest = new VodUploadHttpVideoListRequest();
        Boolean vodUploadHttpVideoListResponse = null;
        try {
            VodUploadHttpVideoListRequest.UploadInfos uploadInfo = new VodUploadHttpVideoListRequest.UploadInfos();
            List<VodUploadHttpVideoListRequest.UploadInfos> uploadInfos = new ArrayList<>(Arrays.asList(uploadInfo));
            uploadInfo.setFileUrl("http://sadboytest.oss-cn-shenzhen.aliyuncs.com/test.mp4")
                    .setTitle("junit-远程批量上传视频")
                    .setState("state");
            vodUploadHttpVideoListRequest.setCategoryId("1622165542751")
                    .setScreenCap(0)
                    .setWatermark("http://sadboytest.oss-cn-shenzhen.aliyuncs.com/a.png")
                    .setWatermarkLocation("1")
                    .setUploadInfos(uploadInfos);
            vodUploadHttpVideoListResponse = new VodUploadServiceImpl().uploadHttpVideoList(
                    vodUploadHttpVideoListRequest);
            Assert.assertTrue(vodUploadHttpVideoListResponse);
            if (vodUploadHttpVideoListResponse) {
                //to do something ......
                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. ]

請求參數說明

參數名 必選 類型 說明
categoryId false String 設定上傳影片的分類，當 categoryId 值為1時，表示使用者上傳空間的根目錄。【對應 api 文件的 cataid 欄位】
screenCap false Integer 是否錄影優化。當值為1時，上傳的影片不再採用預設的壓縮編碼機制，影片尺寸不再壓縮，保證影片的清晰度。預設值為0【對應 api 文件的 luping 欄位】
watermark false String 自訂浮水印圖片位址，圖片格式必須是 png 格式，支援 http、https。
watermarkLocation false String 自訂浮水印圖片位置，如無該參數，則自訂浮水印的顯示情況跟隨分類或帳號設定。1：左上角；2：右上角；3：左下角；4：右下角
uploadInfos false Array 上傳影片資訊 json 陣列，最多100個【詳見UploadInfos參數描述】
UploadInfos參數描述
參數名 類型 說明
fileUrl String 待上傳影片的 URL，支援 http、https 協定，長度限制：1000 個字元
title String 影片標題，長度限制：100 個字元
state String 自訂資料，長度限制：100 個字元，如果提交了該欄位，會在上傳完成回呼時透傳回傳

回傳物件說明

true 提交非同步上傳成功，false 提交非同步上傳失敗，具體是否上傳成功以回呼為準。



4、上傳影片封面圖

描述

通过图片文件或http链接上传视频或多个分类的预览图
接口地址（仅做说明使用）：https://api.polyv.net/v2/video/upload-cover-image

呼叫限制

1、介面呼叫有頻率限制，詳細請查看，呼叫常見異常，詳細請查看

2、當傳了 videoIds 參數，以 videoIds 為準，當 videoIds 不傳，以 categoryIds 為準，兩個參數不能同時為空。

3、圖片上傳形式，三者任選其一即可，傳了多個則按 imageFile, imageUrl, imageBase64 順序選取第一個不為空的形式。

4、圖片格式僅支援 png、jpg、jpeg、gif、bmp，且圖片大小不得超過 5MB。

單元測試

    @Test
    public void testUploadVideoCoverImage() throws IOException, NoSuchAlgorithmException {
        VodUploadVideoCoverImageRequest vodUploadVideoCoverImageRequest = new VodUploadVideoCoverImageRequest();
        VodUploadVideoCoverImageResponse vodUploadVideoCoverImageResponse = null;
        try {
            String path = getClass().getResource("/img/cover.jpg").getPath();
            vodUploadVideoCoverImageRequest.setVideoIds(
                    "1b448be32345b255cabc3fe8d65a4d00_1,1b448be3234406608b7838c7ef6b597c_1")
                    .setCategoryIds("1615286323771,1615536384688")
                    .setImageFile(new File(path));
            vodUploadVideoCoverImageResponse = new VodUploadServiceImpl().uploadVideoCoverImage(
                    vodUploadVideoCoverImageRequest);
            Assert.assertTrue(vodUploadVideoCoverImageResponse != null);
            if (vodUploadVideoCoverImageResponse != null) {
                log.debug("测试上传视频封面图成功{}", JSON.toJSONString(vodUploadVideoCoverImageResponse));
            }
        } 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、請求正確，回傳 VodUploadVideoCoverImageResponse 物件，B 端依據此物件處理業務邏輯；

2、請求參數驗證不合格，拋出 PloyvSdkException，錯誤資訊見 PloyvSdkException.getMessage()，如 [ 輸入參數 [xxx.chat.VodxxxRequest] 物件驗證失敗，失敗欄位 [pic不能為空 / msg不能為空] ]

3、伺服器處理異常，拋出 PloyvSdkException，錯誤資訊見 PloyvSdkException.getMessage()，如 [ 保利威請求回傳資料錯誤，請求流水號：66e7ad29fd04425a84c2b2b562d2025b，錯誤原因： invalid signature. ]

請求參數說明

參數名 必選 類型 說明
videoIds false String 影片 id，多個影片 id 用英文逗號隔開，例如 e2e85038_e, e2e85039_e【對應 api 文件的 vids 欄位】
categoryIds false String 分類 id，多個分類 id 用逗號隔開【對應 api 文件的 cateIds 欄位】
imageFile false File 圖片檔案
imageUrl false String 圖片 http url
imageBase64 false String 圖片檔案的 base64 形式

回傳物件說明

參數名 類型 說明
imageUrlSmall String 小圖 url
imageUrlBig String 大圖 url





5、上傳影片浮水印

描述

上传某一级分类或用户级别的视频水印，设置成功后对新上传的视频生效
水印图片需要为png格式，图片宽或高的尺寸超过256px时会被等比缩放
接口地址（仅做说明使用）：https://api.polyv.net/v2/video/%s/watermarkSetting

呼叫限制

1、介面呼叫有頻率限制，詳細請查看，呼叫常見異常，詳細請查看

單元測試

    @Test
    public void testUploadWatermark() throws IOException, NoSuchAlgorithmException {
        VodUploadWatermarkRequest vodUploadWatermarkRequest = new VodUploadWatermarkRequest();
        Boolean vodUploadWatermarkResponse = null;
        try {
            String path = getClass().getResource("/img/water.png").getPath();
            vodUploadWatermarkRequest.setImage(new File(path)).setCategoryId("1602300731843");
            vodUploadWatermarkResponse = new VodUploadServiceImpl().uploadWatermark(vodUploadWatermarkRequest);
            Assert.assertTrue(vodUploadWatermarkResponse);
            if (vodUploadWatermarkResponse) {
                //to do something ......
                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. ]

請求參數說明

參數名 必選 類型 說明
image true File 上傳的浮水印圖片
categoryId false String 分類 ID，僅一級分類能設定浮水印。不傳為設定使用者級別的浮水印【對應 api 文件的 cataid 欄位】
watermarkLocation false String 浮水印顯示的位置：1：左上角；2：右上角；3：左下角；4：右下角；0：不顯示浮水印

回傳物件說明

true：上傳成功；false：上傳失敗

联系客服，在线咨询