视频文本擦除创建接口
更新时间：2026-05-11
视频文本擦除
服务概述
- 创建视频文本擦除任务，提交源视频与擦除区域后由服务端异步处理。
服务申请
视频文本擦除 API 采用控制台项目接入模式。用户可前往ViiTor AI官网 (https://www.viitor.com/) 注册并开通服务，在控制台创建项目后可获得鉴权所需信息。
业务服务地址由项目网关提供；本文档示例基于当前业务网关：
https://video-translation.ilivedata.com
接入方式
参数规范
- 请求 URL：
https://video-translation.ilivedata.com/textRemoval/add - 请求方法：
POST - Content-Type：
application/json - 返回结构：
{code, message, data}
HTTP请求头
| Header | 必填 | 类型 | 说明 |
|---|---|---|---|
Content-Type | 是 | String | application/json;charset=UTF-8 |
Accept | 是 | String | application/json;charset=UTF-8 |
Authorization | 是 | String | 登录态令牌（Bearer Token） |
X-User-Id | 是 | Long | 用户ID，服务端会覆盖 body 中 userId |
X-Channel | 是 | Integer | 渠道编码：100=Web，200=Android，300=iOS |
X-App-Source | 否 | String | 来源标识，最长20字符 |
说明：
- 服务端会以 Header 中的
X-User-Id、X-Channel、X-App-Source为准。
请求方法：POST
请求体
字段定义
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
url | String | 是 | 源视频URL（需可访问） |
taskName | String | 是 | 任务名称，超过50字符会自动截断 |
textDetectROI | Array<Array | 否 | 文本检测擦除区域，如 [[x1,y1,x2,y2], ...] |
fullEraseROI | Array<Array | 否 | 整块擦除区域，如 [[x1,y1,x2,y2], ...] |
参数规则
textDetectROI与fullEraseROI不能同时为空。- 每种 ROI 最多支持 5 个区域。
响应体
统一返回结构
| 字段 | 类型 | 说明 |
|---|---|---|
code | Integer | 0 表示成功，非 0 表示失败 |
message | String | 返回信息 |
data | Object | 业务数据 |
成功时 data 字段
| 字段 | 类型 | 说明 |
|---|---|---|
userId | Long | 用户ID |
taskId | String | 任务ID（后续查询状态/结果使用） |
调用示例
请求示例（cURL）
curl -X POST "https://video-translation.ilivedata.com/textRemoval/add" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-H "X-User-Id: 123456" \
-H "X-Channel: 100" \
-H "X-App-Source: official_web" \
-d '{
"url": "https://cdn.example.com/input/video.mp4",
"taskName": "去字幕-001",
"textDetectROI": [[120, 640, 1180, 700]],
"fullEraseROI": []
}'
成功响应示例
{
"code": 0,
"message": "OK",
"data": {
"userId": 123456,
"taskId": "ViiTor_AI_202605110001"
}
}
失败响应示例（参数错误）
{
"code": 2001,
"message": "Invalid Parameter",
"data": null
}
常见错误码
| 错误码 | 含义 | 典型原因 |
|---|---|---|
2000 | Missing Parameter | 缺少必填 Header 或 Body 参数 |
2001 | Invalid Parameter | 参数不合法（如 url/taskName 为空、渠道值非法） |
10091 | insufficient points | 用户积分不足 |
10093 | task creation failed | 任务创建内部异常 |
客户端接入建议
- 调用
/textRemoval/add获取taskId。 - 使用
taskId调用任务状态接口轮询进度。 - 对
code != 0做统一异常处理，重点处理参数错误与积分不足。
