Java SDK 使用教程

创建项目
   ↓
取上传凭证 ──→ COS 直传视频文件 ──→ 上传完成回调
   ↓
视频入库
   ↓
设置字幕区域（翻译前的最后一步，指定原字幕位置，
   供擦除阶段精准识别与擦除原字幕）
   ↓
开始翻译（计费）
   ↓
轮询翻译进度（擦除 → 校准 → 翻译 → 压制 四阶段）
   ↓
校对/编辑字幕（可选）
   ↓
下载成片 / 获取字幕

import com.jiyou.base.sdk.request.ProjectAddRequest;
import com.jiyou.base.sdk.response.ProjectAddResponse;

// name: 项目名称；sourceLanguage: 源语言；targetLanguage: 目标语言（多个用逗号分隔）；
// fontSize: 字号，0 表示自动计算，可传 null
ProjectAddRequest request = new ProjectAddRequest("我的短剧", "Simplified Chinese", "English", 0);
ProjectAddResponse response = client.execute(request, ProjectAddResponse.class);

import com.jiyou.base.sdk.model.CosUploadCredentialsModel;
import com.jiyou.base.sdk.request.VideoUploadCredentialsRequest;
import com.jiyou.base.sdk.response.VideoUploadCredentialsResponse;

VideoUploadCredentialsRequest request = new VideoUploadCredentialsRequest("projectId");
VideoUploadCredentialsResponse response = client.execute(request, VideoUploadCredentialsResponse.class);

CosUploadCredentialsModel sts = response.getData();

import com.qcloud.cos.ClientConfig;
import com.qcloud.cos.auth.BasicSessionCredentials;
import com.qcloud.cos.region.Region;
import com.qcloud.cos.transfer.TransferManager;
import com.qcloud.cos.transfer.Upload;

// 使用临时密钥三元组（sessionToken 必传）
BasicSessionCredentials cred = new BasicSessionCredentials(
        sts.getTmpSecretId(), sts.getTmpSecretKey(), sts.getSessionToken());
ClientConfig config = new ClientConfig(new Region(sts.getRegion()));
TransferManager tm = new TransferManager(new com.qcloud.cos.COSClient(cred, config));

// 上传到凭证指定的 bucket + key（不可修改目标位置）
File localFile = new File("/path/to/video.mp4");
Upload upload = tm.upload(sts.getBucket(), sts.getKey(), localFile);
upload.waitForUploadResult();  // 大文件自动分片并发上传
tm.shutdownNow();

// 调用方后端自己的 Controller 方法，内部使用 SDK 取凭证后返回给前端
public CosUploadCredentialsModel getUploadCredentials(String projectId) {
    VideoUploadCredentialsRequest request = new VideoUploadCredentialsRequest(projectId);
    VideoUploadCredentialsResponse response = client.execute(request, VideoUploadCredentialsResponse.class);
    return response.getData();  // 前端拿到 fileId/密钥三元组/bucket/region/key/maxSizeBytes
}

import COS from 'cos-js-sdk-v5'

const sts = await api.getUploadCredentials(projectId)  // 调用方自己的后端接口

// 上传前校验文件大小
if (file.size > sts.maxSizeBytes) {
  throw new Error(`文件大小超过等级限制（最大 ${Math.round(sts.maxSizeBytes / 1024 / 1024)}MB）`)
}

// 上传前计算文件 sha256（回调时需要，Web Crypto API）
const sha256 = await calcFileSha256(file)

// 使用临时密钥三元组直传（密钥有效期内无需续签）
const cos = new COS({
  getAuthorization(options, callback) {
    callback({
      TmpSecretId: sts.tmpSecretId,
      TmpSecretKey: sts.tmpSecretKey,
      SecurityToken: sts.sessionToken,
      StartTime: sts.startTime,
      ExpiredTime: sts.expiredTime,
    })
  },
})

// 分片上传到凭证指定的 bucket + key（不可修改目标位置）
await new Promise((resolve, reject) => {
  cos.sliceUploadFile({
    Bucket: sts.bucket,
    Region: sts.region,
    Key: sts.key,
    Body: file,
    SliceSize: 1024 * 1024,
    onProgress: (p) => console.log(`进度：${Math.round((p.percent || 0) * 100)}%`),
  }, err => (err ? reject(err) : resolve()))
})

// 上传完成，将 fileId/sha256/fileName 回传给调用方后端，由后端执行第三步回调
await api.notifyUploadComplete({ fileId: sts.fileId, sha256, fileName: file.name })

import com.jiyou.base.sdk.model.VideoUploadResultModel;
import com.jiyou.base.sdk.request.VideoUploadCompleteRequest;
import com.jiyou.base.sdk.response.VideoUploadCompleteResponse;

// fileId: 第一步凭证中的 fileId；sha256: 文件 sha256（模式二由前端计算回传，必填）；
// fileName: 文件名（请勿包含逗号）
VideoUploadCompleteRequest request =
        new VideoUploadCompleteRequest(sts.getFileId(), "projectId", sha256, "video.mp4");
VideoUploadCompleteResponse response = client.execute(request, VideoUploadCompleteResponse.class);

VideoUploadResultModel result = response.getData();
String sourceFileId = result.getFileId();      // 源视频文件id（入库时使用）
String previewFileId = result.getPreviewFileId(); // 360P预览视频文件id

import java.util.Arrays;
import com.jiyou.base.sdk.request.VideoAddRequest;
import com.jiyou.base.sdk.response.VideoAddResponse;

// fileIds: 源视频文件id列表（必填）；后三个列表可传 null，
// 但如果传了则数量必须与 fileIds 一致
VideoAddRequest request = new VideoAddRequest("projectId",
        Arrays.asList("fileId1", "fileId2"),   // fileIds
        null,                                    // previewFileIds：360P预览视频
        Arrays.asList("sha256_1", "sha256_2"),   // fileSha256s
        Arrays.asList("第01集.mp4", "第02集.mp4")); // fileNames
VideoAddResponse response = client.execute(request, VideoAddResponse.class);

import java.util.Arrays;
import com.jiyou.base.sdk.request.VideoSubtitleRegionSaveRequest;
import com.jiyou.base.sdk.response.VideoSubtitleRegionSaveResponse;

// ids: 视频id列表；regions: 字幕区域JSON串（0-1 相对坐标，可多个区域）
VideoSubtitleRegionSaveRequest request = new VideoSubtitleRegionSaveRequest(
        Arrays.asList("videoId1", "videoId2"),
        "[{\"x\":0.1,\"y\":0.80,\"width\":0.8,\"height\":0.12}]");
VideoSubtitleRegionSaveResponse response = client.execute(request, VideoSubtitleRegionSaveResponse.class);

import com.jiyou.base.sdk.request.VideoTranslateRequest;
import com.jiyou.base.sdk.response.VideoTranslateResponse;

// projectId: 项目id；ids: 视频id列表，传 null 表示翻译项目下全部未翻译视频
VideoTranslateRequest request = new VideoTranslateRequest("projectId", null);
VideoTranslateResponse response = client.execute(request, VideoTranslateResponse.class);

import com.jiyou.base.sdk.model.PageModel;
import com.jiyou.base.sdk.model.ProjectVideoModel;
import com.jiyou.base.sdk.request.VideoListRequest;
import com.jiyou.base.sdk.response.VideoListResponse;

// dataEqual 为精确过滤条件 JSON 串：按项目查询
VideoListRequest request = new VideoListRequest(1, 100, "{\"projectId\":\"xxx\"}", null, null, null);
VideoListResponse response = client.execute(request, VideoListResponse.class);

PageModel<ProjectVideoModel> page = response.getData();
for (ProjectVideoModel video : page.getRecords()) {
    String eraseStatus = video.getEraseStatus();         // 擦除状态
    String reviewStatus = video.getReviewStatus();       // 校准状态
    String translateStatus = video.getTranslateStatus(); // 翻译状态
    String embedStatus = video.getEmbedStatus();         // 压制状态
}

import com.jiyou.base.sdk.request.VideoGetSrtRequest;
import com.jiyou.base.sdk.response.VideoGetSrtResponse;

VideoGetSrtRequest request = new VideoGetSrtRequest("videoId");
VideoGetSrtResponse response = client.execute(request, VideoGetSrtResponse.class);
String srtText = response.getData();

import com.jiyou.base.sdk.request.VideoGetTranslateSrtRequest;
import com.jiyou.base.sdk.response.VideoGetTranslateSrtResponse;

VideoGetTranslateSrtRequest request = new VideoGetTranslateSrtRequest("videoId");
VideoGetTranslateSrtResponse response = client.execute(request, VideoGetTranslateSrtResponse.class);
String srtText = response.getData();

import com.jiyou.base.sdk.request.VideoUpdateSourceSrtRequest;
import com.jiyou.base.sdk.response.VideoUpdateSourceSrtResponse;

VideoUpdateSourceSrtRequest request = new VideoUpdateSourceSrtRequest("videoId", srtText);
VideoUpdateSourceSrtResponse response = client.execute(request, VideoUpdateSourceSrtResponse.class);

import com.jiyou.base.sdk.request.VideoUpdateTranslateSrtRequest;
import com.jiyou.base.sdk.response.VideoUpdateTranslateSrtResponse;

VideoUpdateTranslateSrtRequest request = new VideoUpdateTranslateSrtRequest("videoId", srtText);
VideoUpdateTranslateSrtResponse response = client.execute(request, VideoUpdateTranslateSrtResponse.class);

import java.util.Arrays;
import com.jiyou.base.sdk.request.VideoRetryRequest;
import com.jiyou.base.sdk.response.VideoRetryResponse;

// fromStage: erase/review/translate/embed，传 null 默认 erase
VideoRetryRequest request = new VideoRetryRequest("projectId",
        Arrays.asList("videoId1"), "translate");
VideoRetryResponse response = client.execute(request, VideoRetryResponse.class);

import com.jiyou.base.sdk.request.VideoCancelTranslateRequest;
import com.jiyou.base.sdk.response.VideoCancelTranslateResponse;

VideoCancelTranslateRequest request = new VideoCancelTranslateRequest("projectId", null);
VideoCancelTranslateResponse response = client.execute(request, VideoCancelTranslateResponse.class);

import com.jiyou.base.sdk.request.FileSignRequest;
import com.jiyou.base.sdk.response.FileSignResponse;

// fileId: 源视频传 sourceFileId，成片传 embedFileId
FileSignRequest request = new FileSignRequest("embedFileId");
FileSignResponse response = client.execute(request, FileSignResponse.class);
String downloadUrl = response.getData().getUrl();

import com.jiyou.base.sdk.request.ProjectDownloadEoRequest;
import com.jiyou.base.sdk.response.ProjectDownloadEoResponse;

ProjectDownloadEoRequest request = new ProjectDownloadEoRequest("projectId");
ProjectDownloadEoResponse response = client.execute(request, ProjectDownloadEoResponse.class);

// state=packaging 打包中，需间隔轮询；state=success 后用 url 下载
String state = response.getData().getState();
String url = response.getData().getUrl();

import com.jiyou.base.sdk.request.ProjectListRequest;
import com.jiyou.base.sdk.response.ProjectListResponse;

// page 从 1 开始；dataEqual/dataLike/dataRange 为过滤条件 JSON 串（如 {"name":"xx"}）
ProjectListRequest request = new ProjectListRequest(1, 10, null, null, null, null, null);
ProjectListResponse response = client.execute(request, ProjectListResponse.class);
response.getData().getRecords(); // List<ProjectModel>
response.getData().getTotal();   // 总数

import com.jiyou.base.sdk.request.ProjectEditRequest;
import com.jiyou.base.sdk.response.ProjectEditResponse;

ProjectEditRequest request = new ProjectEditRequest("projectId", "新名称", 0);
ProjectEditResponse response = client.execute(request, ProjectEditResponse.class);

import java.util.Arrays;
import com.jiyou.base.sdk.request.ProjectDelRequest;
import com.jiyou.base.sdk.response.ProjectDelResponse;

ProjectDelRequest request = new ProjectDelRequest(Arrays.asList("projectId1"));
ProjectDelResponse response = client.execute(request, ProjectDelResponse.class);

import com.jiyou.base.sdk.request.VideoEditRequest;
import com.jiyou.base.sdk.response.VideoEditResponse;

VideoEditRequest request = new VideoEditRequest("videoId", "新文件名.mp4");
VideoEditResponse response = client.execute(request, VideoEditResponse.class);

import java.util.Arrays;
import com.jiyou.base.sdk.request.VideoDelRequest;
import com.jiyou.base.sdk.response.VideoDelResponse;

VideoDelRequest request = new VideoDelRequest(Arrays.asList("videoId1"));
VideoDelResponse response = client.execute(request, VideoDelResponse.class);