Video Translation V4 API

Last Updated: 2026-06-03

Video Translation V4

Service Overview

• Creates a video translation task and retrieves the video translation processing result by task ID.
• Supports task creation, task status polling, translated video URL, translated audio URL, source subtitle URL, target subtitle URL, and other result fields.
• This is an asynchronous task flow: after a task is created, the API returns a taskId; the client then polls the result retrieval API for task status and output results.

Service Access

The Video Translation API uses a console-based project access model. You can register and activate services on the ViiTor AI official website, then create a project in the console to obtain required authentication credentials.

The business service endpoint is provided by the project gateway. This document uses the following gateway as an example:

https://video-translation.viitor.com

1. Create Video Translation Task API

Integration

Parameter Specification

• Request URL: https://video-translation.viitor.com/videoTranslate/create
• Method: POST
• Content-Type: application/json
• Response Format: {code, message, data}

HTTP Headers

Notes:

• The server uses X-User-Id, X-Channel, and X-App-Source from the headers to overwrite fields with the same names in the request body.
• Missing X-User-Id or X-Channel returns code=2000.
• The token in Authorization can be obtained after registering and logging in on the ViiTor AI official website. Pass it in the format Bearer <token>.

Request Method: POST

Request Body

Field Definitions

Validation Rules

1. sourceVideoUrl, targetLanguage, videoName, and costPoint cannot be empty.
2. targetLanguage and sourceLanguage must be supported language codes.
3. subtitle only allows 0/1/2/3.
4. costPoint must be greater than or equal to 500.
5. After successful creation, the initial task status is created, and the task is processed asynchronously.

targetLanguage Enum

targetLanguage must use a supported language code. If sourceLanguage is provided, it is validated using the same language code list.

costPoint Calculation Rules

costPoint is the number of points pre-deducted for this task. When creating a task, the client needs to estimate and pass the value based on video duration. The server first pre-deducts points based on this value. After preprocessing obtains the real video duration, the server validates whether the submitted costPoint is lower than the actual required points.

Current base point rules for video translation:

videoDurationSeconds = ceil(sourceVideoDurationMs / 1000)
billingUnitCount = ceil(videoDurationSeconds / VIDEO_TRANSLATE_UNIT)
costPoint = billingUnitCount * VIDEO_TRANSLATE_POINT

Default billing configuration:

Calculation examples:

Notes:

• Durations shorter than one billing unit are billed as one billing unit.
• If the client submits a costPoint lower than the value calculated by the server based on the real video duration, the server returns an inaccurate points error. The typical error code is 10039.
• Billing rules may be dynamically adjusted by backend configuration. Client-side price display should follow online configuration or server-returned rules.

Response Body

Standard Response Schema

data Fields on Success

Examples

cURL Request

curl -X POST "https://video-translation.viitor.com/videoTranslate/create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json;charset=UTF-8" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-User-Id: 123456" \
  -H "X-Channel: 100" \
  -H "X-App-Source: official_web" \
  -d '{
    "sourceVideoUrl": "https://cdn.example.com/video/source.mp4",
    "videoName": "Video Translation Task 001",
    "sourceLanguage": "zh-CN",
    "targetLanguage": "en",
    "costPoint": 1250,
    "subtitle": 2,
    "timeLinePattern": 1
  }'

Success Response Example

{
  "code": 0,
  "message": "OK",
  "data": {
    "taskId": "ViiTor_AI_50C7A13A74DC46D8B31EAEF3382895BA"
  }
}

Failure Response Example (Invalid Parameters)

{
  "code": 2001,
  "message": "Invalid Parameter",
  "data": null
}

2. Video Translation Result Retrieval API

Integration

Parameter Specification

• Request URL: https://video-translation.viitor.com/videoTranslate/result
• Method: POST
• Content-Type: application/json
• Response Format: {code, message, data}

HTTP Headers

Notes:

• This API only uses X-User-Id from the headers as the query user.
• Only tasks created by the current user and not deleted can be queried.
• The token in Authorization can be obtained after registering and logging in on the ViiTor AI official website. Pass it in the format Bearer <token>.

Request Method: POST

Request Body

Field Definitions

Validation Rules

1. taskId cannot be empty.
2. taskId must belong to the current user and must not be deleted.
3. If the task does not exist, the API returns code=10022.

Response Body

Standard Response Schema

data Fields on Success

taskStatus Codes

Examples

cURL Request

curl -X POST "https://video-translation.viitor.com/videoTranslate/result" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json;charset=UTF-8" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "X-User-Id: 123456" \
  -d '{
    "taskId": "ViiTor_AI_50C7A13A74DC46D8B31EAEF3382895BA"
  }'

Success Response Example (Processing)

{
  "code": 0,
  "message": "OK",
  "data": {
    "taskId": "ViiTor_AI_50C7A13A74DC46D8B31EAEF3382895BA",
    "videoName": "Video Translation Task 001",
    "taskStatus": 3,
    "taskProcessStatus": 40,
    "errorCode": 0,
    "sourceLanguage": "zh-CN",
    "targetLanguage": "en",
    "sourceVideoUrl": "https://cdn.example.com/video/source.mp4",
    "targetVideoUrl": null,
    "subtitle": 2,
    "createTime": 1779696000000
  }
}

Success Response Example (Finished)

{
  "code": 0,
  "message": "OK",
  "data": {
    "taskId": "ViiTor_AI_50C7A13A74DC46D8B31EAEF3382895BA",
    "videoName": "Video Translation Task 001",
    "taskStatus": 4,
    "errorCode": 0,
    "taskProcessStatus": 9999,
    "sourceLanguage": "zh-CN",
    "targetLanguage": "en",
    "targetVideoUrl": "https://cdn.example.com/video/target.mp4",
    "targetAudioUrl": "https://cdn.example.com/audio/target.mp3",
    "sourceSubtitleUrl": "https://cdn.example.com/subtitle/source.srt",
    "targetSubtitleUrl": "https://cdn.example.com/subtitle/target.srt",
    "sourceThumbnailUrl": "https://cdn.example.com/image/cover.jpg",
    "videoDuration": 60000,
    "subtitle": 2,
    "createTime": 1779696000000
  }
}

Failure Response Example (Task Not Found)

{
  "code": 10022,
  "message": "taskid is not exist",
  "data": null
}

Common Error Codes

Client Integration Recommendations

1. Call /videoTranslate/create first to create a task and obtain taskId.
2. Then call /videoTranslate/result to poll task status.
3. When taskStatus=4 and taskProcessStatus=9999, the task is considered finished. The client can read result fields such as targetVideoUrl, targetAudioUrl, sourceSubtitleUrl, and targetSubtitleUrl.
4. When taskStatus=5, the task is considered failed. The client should read errorCode and display the failure reason.
5. Apply unified exception handling for code != 0, especially parameter errors, task not found, and insufficient points.