视频翻译-阿里云帮助中心

视频翻译 API 将视频画面中的嵌字（字幕、卖点文字等）翻译为目标语言，并擦除原文。适用于电商视频多语言分发、国际社交媒体营销、全球品牌广告投放等场景。API 采用异步调用模式：提交翻译任务后获取 task_id，通过查询接口轮询任务状态直至完成后获取结果。

适用场景

跨境电商视频本地化：将商品介绍视频中的卖点文字翻译为目标市场语言，助力海外平台推广。
国际社交媒体营销：针对 TikTok、Instagram、YouTube 等平台，将视频画面文字内容一键本地化，提升海外用户理解度与转化率。
全球品牌广告投放：根据投放地区语言自动生成对应版本视频，减少人工制作成本。
培训与产品说明：将培训课程或产品演示视频中的画面文字翻译为多语言版本，方便全球团队使用。

功能介绍

能力	标识码	说明
画面翻译	`visual`	翻译视频画面中的嵌字（字幕、卖点文字等），并擦除原文。

提交翻译任务

请求

POST /api/v1/video/translation

请求参数

参数名	类型	必填	说明
`videoUrl`	String	是	源视频 URL。支持 MP4 / MOV 格式，大小 ≤ 200 MB。
`capabilities`	Array<String>	是	翻译能力数组，当前可选值：`["visual"]`。
`targetLanguage`	String	是	目标语言代码，见下方「语言支持」。
`sourceLanguage`	String	否	源语言代码，默认 `auto` 自动识别。

请求示例

POST /api/v1/video/translation

{
  "videoUrl": "https://cdn.example.com/product-demo.mp4",
  "capabilities": ["visual"],
  "targetLanguage": "en",
  "sourceLanguage": "zh"
}

响应参数

参数名	类型	说明
`Code`	String	状态码，`Success` 表示成功。
`Message`	String	说明信息。
`RequestId`	String	请求追踪 ID。
`Data.TaskId`	String	任务唯一标识，用于查询结果。

响应示例

{
  "code": "Success",
  "message": "Translation task submitted successfully",
  "request_id": "req_20260608_abc123",
  "data": {
    "task_id": "task_7f3a9b2e-4c1d-4e8f-b6a5-1234567890ab"
  }
}

查询翻译结果

请求

GET /api/v1/video/translation/{task_id}

参数名	位置	类型	说明
`TaskId`	path	String	提交接口返回的任务 ID。

响应参数

参数名	类型	说明
`Code`	String	状态码。
`Message`	String	说明信息。
`RequestId`	String	请求追踪 ID。
`Data.TaskId`	String	任务 ID。
`Data.Status`	String	任务状态：`queued` / `in_progress` / `completed` / `failed`。
`Data.Progress`	Int	任务处理中。
`Data.Results`	Object	翻译结果（仅 `completed` 状态返回）。
`Data.Results.VideoUrl`	String	译后视频下载 URL（有效期 30 天）。
`Data.Results.Duration`	Number	输出视频时长（秒）。
`Data.Error`	Object	错误信息（仅 `failed` 状态返回）。含 `Data.Error.ErrorCode`（错误码，见错误码章节）、`Data.Error.ErrorMessage`（错误描述）、`Data.Error.Retryable`（是否支持重试，Bool）。

响应示例（任务处理中）

{
  "code": "Processing",
  "message": "Translation processing",
  "request_id": "req_20260608_jkl012",
  "data": {
    "task_id": "task_7f3a9b2e-4c1d-4e8f-b6a5-1234567890ab",
    "status": "in_progress"
  }
}

响应示例（完成）

{
  "code": "Success",
  "message": "Translation completed",
  "request_id": "req_20260608_ghi789",
  "data": {
    "task_id": "task_7f3a9b2e-4c1d-4e8f-b6a5-1234567890ab",
    "status": "completed",
    "results": {
      "video_url": "https://cdn.example.com/output/task_7f3a9b2e.mp4",
      "duration": 125.4
    }
  }
}

响应示例（失败）

{
  "code": "Success",
  "message": "Translation failed",
  "request_id": "req_20260608_jkl012",
  "data": {
    "task_id": "task_7f3a9b2e-4c1d-4e8f-b6a5-1234567890ab",
    "status": "failed",
    "error": {
      "error_code": "PROCESSING_TIMEOUT",
      "error_message": "任务处理超时，请重试",
      "retryable": true
    }
  }
}

语言支持

视频翻译当前支持 29 个源语言与 23 个目标语言，源语言与目标语言独立选择。sourceLanguage 不传或传 auto 时由系统自动识别；传具体语言代码时按该语言强制识别（跳过自动识别）。完整语言名称与代码见语向映射「视频翻译支持语言」。

错误码

错误码	Message	备注
`InvalidVideoFormat`	The video format is not supported, please use MP4/MOV.
`VideoTooLong`	The video duration exceeds the maximum limit (3 minutes).
`VideoTooLarge`	The video file size exceeds the maximum limit (200MB).
`VideoDownloadFailed`	Failed to download video from the provided URL.
`LangNotSupported`	The specified language combination is not supported.
`InvalidParameter`	Invalid request parameter: %s
`CallerTypeNotSupported`	Caller type not supported: %s (only main account 'customer' and sub-account 'sub' are allowed)
`UserStatusInvalid`	用户状态异常: %s
`ServiceNotOpened`	Service not activated, please activate the service first: %s
`ServiceStatusInvalid`	Service status abnormal, please contact the administrator: %s
`ServiceSuspended`	Service suspended due to overdue payment, please settle the payment and retry: %s
`FreeQuotaExhausted`	Free quota exhausted; disable the 'stop-when-exhausted' switch or purchase a package: %s
`PriorityUnavailable`	Request priority unavailable: %s
`InputContentBlocked`	Input content violates policy, please modify and retry: %s
`OutputContentBlocked`	Output content violates policy: %s
`DownstreamUnavailable`	Service temporarily unavailable, details: %s
`UsageParseFail`	Internal system error: %s
`BillingPushFail`	Internal system error: %s
`InternalError`	System is busy, please retry later: %s
`ServiceUnavailable`	The request has failed due to a temporary failure of the server.
`Throttling`	Request was denied due to flow control.
`Throttling.Api`	Request was denied due to api flow control.
`Throttling.User`	Request was denied due to user flow control.
`NoPermission`	You are not authorized to perform this action.
`UnknownError`	The request processing has failed due to some unknown error.
`InternalError`	The request processing has failed due to some unknown error.
`InvalidParameter`	The specified parameter “%s” is not valid.
`IncompleteSignature`	The request signature does not conform to Alibaba Cloud standards.
`MissingXXXXX`	XXXXX is mandatory for this action.

其他错误码参照 Aidge 平台统一错误码。

使用限制

项目	限制
视频格式	MP4、MOV
视频大小	≤ 200 MB
结果查询有效期	7 天（过期后需重新提交）

常见问题

提交任务后多久可以获取结果？

处理时长与视频时长相关，一般在视频时长的同量级范围内。可通过查询接口的 progress 字段了解实时进度。

任务失败后如何重试？

查询结果中 error.retryable = true 的错误可直接用相同参数重新提交任务。每次提交都会生成新的 task_id。