Xfei Video Translation#

Translate videos with AI-powered dubbing using iFlytek's Video Translation service.

API Endpoints#

Base URL: https://spark-api-test.xf-yun.com/api/v1/video-translate

EndpointMethodDescription/tasksPOSTCreate video translation task/tasksGETList all tasks/tasks/:taskIdGETGet task details

Features#

• Video Translation: Translate video audio to different languages
• AI Dubbing: Generate natural-sounding voiceovers
• Multi-language: Support for English, Chinese, Japanese, Korean, etc.
• Task Management: Create tasks, list tasks, get task details
• Lip Sync: Automatic face matching for translated audio

Usage Scenarios#

Scenario 1: Create Video Translation Task#

Submit a video for translation.

Use this when: User provides a video URL and wants to translate it.

bash

# Create task - translate English video to Chinese
python3 scripts/xfei_video_translate.py --action create_task \
    --file_url "https://example.com/video.mp4" \
    --src_lang en --dest_lang zh

# Translate Chinese to English
python3 scripts/xfei_video_translate.py --action create_task \
    --file_url "https://example.com/video.mp4" \
    --src_lang zh --dest_lang en

# Translate Japanese to Chinese
python3 scripts/xfei_video_translate.py --action create_task \
    --file_url "https://example.com/video.mp4" \
    --src_lang ja --dest_lang zh

Scenario 2: List All Tasks#

View all video translation tasks.

Use this when: User wants to see all translation tasks.

bash

# List all tasks
python3 scripts/xfei_video_translate.py --action list_tasks

Scenario 3: Get Task Details#

View detailed information about a specific task.

Use this when: User wants to check the status and details of a specific task.

bash

# Get task details
python3 scripts/xfei_video_translate.py --action get_task \
    --task_id "xxx-xxx-xxx"

Setup#

1. Install Dependency#

bash

pip install requests>=2.31.0

2. Configure Environment Variables#

bash

export XFYUN_API_KEY="your_api_key"
export XFYUN_API_SECRET="your_api_secret"

Parameters#

create_task (POST /tasks)#

ParameterTypeRequiredDescription--file_url / -ustringYesVideo file OSS URL (视频文件 OSS 地址)--src_lang / -fstringYesSource language code (e.g., en, zh, ja, ko)--dest_lang / -tstringYesTarget language code

list_tasks (GET /tasks)#

No parameters required.

get_task (GET /tasks/:taskId)#

ParameterTypeRequiredDescription--task_id / -istringYesTask ID

Response Format#

Standard response: {"code": 0, "message": "success", "request_id": "xxx", "data": {}}

create_task Response (data)#

json

{
  "task_id": "xxx-xxx-xxx",
  "status": "waiting_parsing",
  "created_at": "2025-01-17T10:30:45Z"
}

list_tasks Response (data)#

json

[
  {
    "task_id": "xxx-xxx-xxx",
    "task_name": "我的翻译任务",
    "status": "completed",
    "src_lang": "en",
    "dest_lang": "zh",
    "created_at": "2025-01-17T10:30:45Z",
    "updated_at": "2025-01-17T11:30:45Z"
  }
]

get_task Response (data)#

json

{
  "task_id": "xxx-xxx-xxx",
  "task_name": "我的翻译任务",
  "status": "completed",
  "created_at": "2025-01-17T10:30:45Z",
  "updated_at": "2025-01-17T11:30:45Z",
  "task_params": {
    "file_url": "https://example.com/video.mp4",
    "src_lang": "en",
    "dest_lang": "zh"
  },
  "output": {
    "subtitle_url": "https://example.com/output.srt",
    "output_video_url": "https://example.com/output.mp4"
  }
}

Task Status Values#

StatusDescriptionrunningTask in progresscompletedTask completed successfullyfailedTask failedcancelledTask cancelledwaiting_manual_intervention_segmentWaiting for transcript editingwaiting_manual_intervention_refineWaiting for translation editing

Language Codes#

CodeLanguagezhChinese (中文)enEnglish (英文)jaJapanese (日文)koKorean (韩文)ruRussian (俄文)frFrench (法文)arArabic (阿拉伯语)esSpanish (西班牙语)yueCantonese (粤语)

Input Video Requirements#

• Format: MP4
• Duration: Max 5 minutes
• Resolution: 720p - 4k
• FPS: Recommended 25
• Audio: Single audio track only

Error Handling#

ErrorCauseSolutionXFYUN_API_KEY and XFYUN_API_SECRET are requiredNo credentials configuredSet environment variables--file_url is requiredNo video URL providedProvide valid OSS video URL--task_id is requiredNo task ID providedProvide valid task IDAPI error XXXXRequest failedCheck message in response

鉴权失败错误提示 (๑•̀ㅂ•́)و✧#

哎呀呀～遇到鉴权错误啦！ (⊙_⊙) 快来看看是哪里出问题了吧～

HTTP Code错误描述原因处理建议401{"message":"Unauthorized"}缺少 authorization 参数哎呀～检查一下有没有正确带上传入的 authorization 参数哦～401{"message":"HMAC signature cannot be verified"}签名参数解析失败嗯嗯～ (°∀°)ﾉ 检查一下各签名参数是否完整，确认 APIKey 是不是正确呀～401{"message":"HMAC signature does not match"}签名校验失败嘿呀～ (｡•́︿•̀｡) 检查一下 APIKey/APISecret 是否正确呢～还要看看 host、date、request-line 拼接对不对哦～signature 的 Base64 长度正常应该是 44 字节呢～403{"message":"HMAC signature cannot be verified, a valid date or x-date header is required"}时钟偏移校验失败嗯嗯？ (⊙_⊙) 服务器时钟可能有偏差哦～偏差超过 300 秒就会被拒绝啦！快去校准一下时间吧～

小贴士 💡：

• 如果遇到签名不匹配的错误，首先检查 APIKey 和 APISecret 是否正确～
• 确保服务器的日期时间准确，偏差太大会导致 403 错误哦～
• 签名中的 path 需要和实际请求的路径完全一致才可以呢～

Tips#

1. Video URL: Must be an OSS (Aliyun Object Storage Service) URL accessible by iFlytek
2. Task status: Use get_task to check task progress
3. Completed tasks: When status is "completed", the output_video_url contains the translated video
4. Manual intervention: Some videos may require human review for transcript or translation