Developer API
视频去字幕开放 API
把 AI 去字幕能力直接接入你的剪辑系统、矩阵号工具或内容 SaaS。标准 REST + JSON 接口，API Key 鉴权，按视频实际秒数计费，网页端、小程序与 API 共用同一份时长余额。
为什么用它
为规模化字幕清理设计的接口
API Key 鉴权
支持 Authorization: Bearer 和 X-API-Key 两种传递方式，密钥可随时在控制台重新生成，旧密钥立即失效。
按秒计费，用多少扣多少
提交任务时按视频实际时长秒数扣除余额，无最低消费、无包月门槛，时长包余额永久有效。
两步接入，无需第三方 SDK
直接把视频 POST 上传，服务端代你完成云端上传并返回地址，再提交任务即可。不用接腾讯云 VOD SDK，纯 HTTP 就能跑通。
接入流程
四步完成对接
创建 API Key
在时长版「API 接入」页创建密钥，妥善保存在服务端环境变量中，不要暴露在前端。
上传视频
以 multipart/form-data 上传视频与字幕区域，服务端代传云端并返回视频地址和封面。
提交去字幕任务
视频上传完成后提交任务，系统按视频实际秒数扣除时长余额并返回任务 ID。
轮询并取回结果
按任务 ID 查询进度，状态为 SUCCESS 时返回处理后的视频地址，直接下载或回写业务库。
status 取值：SUBMITTED（已受理）→ DOING（处理中）→ SUCCESS / FAILED。提交接口通常直接返回 DOING。扣费以 billableSeconds 为准，billableMinutes 只是账单口径的向上取整。
鉴权
请求鉴权方式
所有开放接口都需要在请求头中携带 API Key，二选一即可。
Authorization: Bearer dsk_xxxxxxxxxxxxxxxx # 或 X-API-Key: dsk_xxxxxxxxxxxxxxxx
接口基址：https://www.xxd33.cn/openapi/v1/，请求与响应均为 JSON。请勿在浏览器前端或公开仓库中暴露密钥。
统一响应结构为 { "code": 200, "result": {...}, "msg": "" }。result 是 JSON 对象，直接取字段即可，不需要二次解析；失败时 code 非 200、result 为 null、失败原因在 msg。
接口参考
四个核心接口
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /openapi/v1/account/balance | 查询账户时长余额、累计充值与累计消耗 |
| POST | /openapi/v1/subtitle/uploadVideo | 上传视频与字幕区域，服务端代传云端，返回视频地址与封面 |
| POST | /openapi/v1/subtitle/submitRemoveSubtitleTask | 提交去字幕任务，按视频实际秒数扣费 |
| GET | /openapi/v1/subtitle/getRemoveSubtitleProgress | 查询任务状态与结果视频地址 |
1. 查询账户时长余额
curl "https://www.xxd33.cn/openapi/v1/account/balance" \
-H "Authorization: Bearer dsk_xxx"
{
"code": 200,
"result": {
"balanceSeconds": 1200,
"totalRechargeSeconds": 1200,
"totalConsumeSeconds": 0
}
}
2. 上传视频
以 multipart/form-data 把视频文件和字幕区域一起 POST 上来，文件字段名固定为 file。
服务端会代你完成云端上传，返回的 url 和 videoName 就是第 3 步要用的值。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | file | 是 | 视频文件，支持 mp4 / mov / m4v / avi / mkv / webm 等常见格式 |
duration | number | 是 | 视频时长，单位秒，最大 1800 |
fileSize | string | 是 | 视频大小，单位 MB，例如 12.45 |
resolution | string | 是 | 视频分辨率，例如 1080x1920 |
l / t / w / h | number | 是 | 字幕区域左上角坐标与宽高（像素） |
curl -X POST "https://www.xxd33.cn/openapi/v1/subtitle/uploadVideo" \
-H "X-API-Key: dsk_xxx" \
-F "file=@/path/to/video.mp4" \
-F "duration=58" -F "fileSize=12.45" -F "resolution=1080x1920" \
-F "l=80" -F "t=1420" -F "w=920" -F "h=180"
{
"code": 200,
"result": {
"url": "https://1500041884.vod-qcloud.com/xxxx/xxxx/v.f100030.mp4",
"coverUrl": "https://1500041884.vod-qcloud.com/xxxx/xxxx/cover.jpg",
"fileId": "243791581………",
"videoName": "huangcustomer_1788308416_48_272_664_432",
"fileSize": "13053184"
}
}
说明：封面由云端自动生成，不用自己处理。
videoName 由服务端按字幕区域生成，第 3 步必须原样回传——处理引擎靠它定位字幕区域。
旧的 getRemoveSubtitleVodSign 接口仍然可用，但不再推荐；新接入直接用本接口即可，不需要引入腾讯云 VOD SDK。
3. 提交去字幕任务
url 和 videoName 都必须是第 2 步返回的值。
外部链接会被拒绝——服务端只接受上传接口产出的云端地址，传第三方地址会直接返回错误。
curl -X POST "https://www.xxd33.cn/openapi/v1/subtitle/submitRemoveSubtitleTask" \
-H "X-API-Key: dsk_xxx" \
-H "Content-Type: application/json" \
-d '{"url":"https://1500041884.vod-qcloud.com/xxxx/xxxx/v.f100030.mp4","videoName":"huangcustomer_1788308416_48_272_664_432",
"duration":58,"fileSize":"12.45","resolution":"1080x1920",
"l":80,"t":1420,"w":920,"h":180}'
{
"code": 200,
"result": { "localTaskId": "dsa_xxx", "status": "DOING", "billableSeconds": 58,
"billableMinutes": 1, "unitPriceFen": 100, "amountFen": 97 }
}
4. 查询任务进度
curl "https://www.xxd33.cn/openapi/v1/subtitle/getRemoveSubtitleProgress?taskId=dsa_xxx&refresh=true" \
-H "Authorization: Bearer dsk_xxx"
{
"code": 200,
"result": { "localTaskId": "dsa_xxx", "status": "SUCCESS",
"resultUrl": "https://example.com/result.mp4" }
}
错误码
| code | 含义 | 处理建议 |
|---|---|---|
| 200 | 成功 | 正常读取 result |
| 401 | API Key 无效或缺失 | 检查请求头与密钥是否已被重新生成 |
| -1 | 业务失败 | 如余额不足、任务不存在、处理异常，按 msg 提示处理 |
FAQ
API 常见问题
怎么获取 API Key？
在去字幕时长版用微信扫码登录后，进入「API 接入」页面点击创建。每个账户同时只保留一把有效密钥，重新生成后旧密钥立即失效，请及时更新调用方配置。
API 怎么计费？余额和网页端是分开的吗？
按视频实际时长秒数扣费。API、时长版网页端和时长版小程序共用同一份时长余额，任意一端购买时长包后三端都可使用，余额不过期。
支持多长、多大的视频？
单条视频最长 30 分钟（1800 秒），文件大小 1GB 以内，最高 1080P，支持 MP4、MOV 等常见格式。超出限制的视频请先分段处理。
处理需要多久？有回调吗？
处理时间与视频时长和分辨率相关，1 分钟视频通常 30 秒左右完成。当前通过进度查询接口轮询状态，建议 3–5 秒轮询一次；如需要回调通知，可联系客服微信 dxd_gl 沟通。
字幕区域坐标怎么确定？
坐标以视频原始像素为准，l、t 是字幕区域左上角的 X、Y 坐标，w、h 是区域宽高。全屏去字幕可传入整个画面的坐标范围。建议先在时长版网页端框选一次确认效果，再把参数固化到程序里。