全部文档
当前文档
最近更新时间：2026-11-03 19:37:39
通过 GET 请求携带 x-kss-process=video/info 查询参数获取视频的元信息，服务端直接返回 JSON 格式的处理结果，不修改 KS3 上的原始视频对象。适合在转码前获取视频时长、分辨率、编码格式、码率等信息的场景。私有文件需携带签名，SDK 会自动将 x-kss-process 参数纳入签名计算。
public void getVideoInfo() {
// 初始化 Ks3Client，参见"初始化"文档
Ks3Client ks3Client = initKs3Client();
String bucketName = "bucketName";
String objectKey = "video/source.mp4";
try {
// 创建获取对象请求
GetObjectRequest request = new GetObjectRequest(bucketName, objectKey);
// 设置获取视频元信息的处理参数
// 等价于 GET /video/source.mp4?x-kss-process=video/info
request.withProcess("video/info");
// 获取处理后的 JSON 文本，SDK 会自动处理流式读取、字节转字符串与关闭流等操作
String videoInfo = ks3Client.getObjectAsString(request);
System.out.println("视频元信息获取成功:");
System.out.println(videoInfo);
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} catch (IOException e) {
System.out.println("IOException occurred, which means an I/O error occurred while reading the video info response.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}通过 GET 请求携带 x-kss-process 参数对视频进行实时截帧，处理结果（图片）直接作为响应体返回，不修改 KS3 上的原始视频对象。适合获取视频封面、关键帧等场景。私有文件需携带签名，SDK 会自动将 x-kss-process 参数纳入签名计算。
public void getObjectWithProcess() {
// 初始化 Ks3Client，参见"初始化"文档
Ks3Client ks3Client = initKs3Client();
String bucketName = "bucketName";
String objectKey = "video/source.mp4";
String fileName = "/path/to/snapshot.jpg";
try {
// 创建获取对象请求
GetObjectRequest request = new GetObjectRequest(bucketName, objectKey);
// 设置视频截帧处理参数：截取第 7 秒（7000 毫秒）画面，输出宽度 800px 的 JPG 图片
request.withProcess("video/snapshot,t_7000,w_800");
// 获取处理后的图片并下载到本地文件
ObjectMetadata metadata = ks3Client.getObjectToFile(request, new File(fileName));
System.out.println("视频截帧成功，已保存到: " + fileName);
System.out.println("截图大小: " + metadata.getContentLength() + " bytes");
System.out.println("Content Type: " + metadata.getContentType());
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} catch (IOException e) {
System.out.println("IOException occurred, which means an I/O error occurred while writing the processed file.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}通过 POST 请求携带 x-kss-process 提交处理指令，并配合 sys/saveas 将处理结果持久化保存到指定桶，适合需要保留处理结果的场景。注意 sys/saveas 的 b_（桶名）、o_（objectKey）需经 URL 安全 Base64 编码后拼接，直接使用明文会导致服务端解析失败。
public void processObject() {
// 初始化 Ks3Client，参见"初始化"文档
Ks3Client ks3Client = initKs3Client();
String bucketName = "bucketName";
String objectKey = "video/source.mp4";
try {
String saveAsBucket = "mybucket";
String saveAsKey = "output/snapshot.png";
// 处理参数：截取第 10 秒画面，输出 800x600 的 PNG，并另存到指定桶
// sys/saveas 的 b_(桶名) 与 o_(objectKey) 必须经过 URL 安全 Base64 编码后拼接
String process = "video/snapshot,t_10000,f_png,w_800,h_600"
+ "|sys/saveas,b_" + urlSafeBase64(saveAsBucket)
+ ",o_" + urlSafeBase64(saveAsKey);
// 提交同步持久化处理请求
ProcessObjectResult result = ks3Client.processObject(bucketName, objectKey, process);
System.out.println("同步持久化处理完成");
System.out.println("状态: " + result.getStatus());
System.out.println("目标桶: " + result.getBucket());
System.out.println("目标对象: " + result.getObject());
System.out.println("文件大小: " + result.getFileSize());
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}通过 POST x-async-kss-process 提交视频转码等耗时任务，接口立即返回 processId，用于后续查询任务状态，服务端异步执行。转码为异步处理，必须通过 sys/saveas 指定输出位置，处理完成后结果持久化到 KS3。任务记录在任务完成 15 天后自动删除。sys/saveas 的 b_/o_ 与 callback 的 url_ 均需经 URL 安全 Base64 编码后拼接。
public void asyncProcessObject() {
// 初始化 Ks3Client，参见"初始化"文档
Ks3Client ks3Client = initKs3Client();
String bucketName = "bucketName";
String objectKey = "video/source.avi";
try {
String saveAsBucket = "mybucket";
String saveAsKey = "output/sample.mp4";
String callbackUrl = "https://biz.example.com/ks3/callback";
// 处理参数：将 AVI 转码为 MP4，H.265 编码，1080p，30fps，2Mbps 视频码率，AAC 音频 100Kbps，禁用字幕
// sys/saveas 的 b_/o_ 与 callback 的 url_ 都必须经过 URL 安全 Base64 编码后拼接
String process = "video/convert,f_mp4,vcodec_h265,s_1920x1080,vb_2000000,fps_30,acodec_aac,ab_100000,sn_1"
+ "|sys/saveas,b_" + urlSafeBase64(saveAsBucket)
+ ",o_" + urlSafeBase64(saveAsKey)
+ "|callback,url_" + urlSafeBase64(callbackUrl);
// 提交异步处理请求
AsyncProcessObjectResult result = ks3Client.asyncProcessObject(bucketName, objectKey, process);
System.out.println("异步转码任务已提交");
System.out.println("processId: " + result.getProcessId());
System.out.println("requestId: " + result.getRequestId());
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}根据 processId 查询单个异步任务的执行状态与详情，processId 来自异步处理接口的返回。
public void getAsyncProcess() {
// 初始化 Ks3Client，参见"初始化"文档
Ks3Client ks3Client = initKs3Client();
String bucketName = "bucketName";
// processId 来自 asyncProcessObject 的返回
String processId = "MediaConvert-b3b70350-abce-4f46-80f1-db5bdbe9a57d";
try {
// 查询异步任务详情
GetAsyncProcessResult result = ks3Client.getAsyncProcess(bucketName, processId);
System.out.println("任务 ID: " + result.getProcessId());
System.out.println("任务状态: " + result.getStatus());
System.out.println("错误码: " + result.getCode());
System.out.println("错误信息: " + result.getMessage());
System.out.println("处理类型: " + result.getProcessType());
System.out.println("开始时间: " + result.getStartTime());
System.out.println("结束时间: " + result.getEndTime());
System.out.println("源桶: " + result.getBucketName());
System.out.println("源对象: " + result.getObjectKey());
System.out.println("回调地址: " + result.getCallbackUrl());
// 打印处理参数
Map<String, Object> params = result.getParams();
if (params != null) {
System.out.println("处理参数:");
for (Map.Entry<String, Object> entry : params.entrySet()) {
System.out.println(" " + entry.getKey() + " = " + entry.getValue());
}
}
// 打印输出文件列表
List<GetAsyncProcessResult.Output> outputs = result.getOutputs();
if (outputs != null) {
System.out.println("输出文件:");
for (GetAsyncProcessResult.Output output : outputs) {
System.out.println(" " + output.getBucketName() + "/" + output.getObjectKey());
}
}
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}列举指定桶下的异步处理任务，支持按处理类型、对象 key 前缀、任务状态过滤，并通过 nextToken 分页拉取。仅 asyncProcess 子资源参与签名，过滤/分页参数不参与签名。
public void listAsyncProcess() {
// 初始化 Ks3Client，参见"初始化"文档
Ks3Client ks3Client = initKs3Client();
String bucketName = "bucketName";
try {
// 循环分页拉取所有"失败"的媒体转码任务
String nextToken = null;
int pageIndex = 1;
do {
// 构造列举请求，设置过滤与分页参数
ListAsyncProcessRequest request = new ListAsyncProcessRequest(bucketName)
.withProcessType("MediaConvert")
.withStatus("Failed")
.withMaxResults("100")
.withNextToken(nextToken);
// 发起列举请求
ListAsyncProcessResult result = ks3Client.listAsyncProcess(request);
List<GetAsyncProcessResult> tasks = result.getAsyncProcess();
System.out.println("第 " + pageIndex + " 页，本页任务数: "
+ (tasks == null ? 0 : tasks.size()));
// 遍历本页任务
if (tasks != null) {
for (GetAsyncProcessResult task : tasks) {
System.out.println(" processId=" + task.getProcessId()
+ ", status=" + task.getStatus()
+ ", objectKey=" + task.getObjectKey()
+ ", code=" + task.getCode());
}
}
// 取下一页 token，为空表示已到最后一页
nextToken = result.getNextToken();
pageIndex++;
} while (nextToken != null && !nextToken.isEmpty());
System.out.println("列举完成");
} catch (Ks3ServiceException e) {
System.out.println("Ks3ServiceException occurred, which means the request was made to KS3, but KS3 returned an error response for some reason.");
System.out.println("Error Message: " + e.getErrorMessage());
System.out.println("Error Code: " + e.getErrorCode());
System.out.println("Request ID: " + e.getRequestId());
} catch (Ks3ClientException e) {
System.out.println("Ks3ClientException occurred, which means the client encountered an internal error while trying to communicate with KS3.");
System.out.println("Error Message: " + e.getMessage());
} finally {
// 不再使用时，关闭 Ks3Client
ks3Client.shutdown();
}
}纯净模式