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
| Endpoint | Method | Description |
|---|---|---|
/tasks |
POST | Create video translation task |
/tasks |
GET | List all tasks |
/tasks/:taskId |
GET | Get 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.
# 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.
# 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.
# Get task details
python3 scripts/xfei_video_translate.py --action get_task \
--task_id "xxx-xxx-xxx"
Setup
1. Install Dependency
pip install requests>=2.31.0
2. Configure Environment Variables
export XFYUN_API_KEY="your_api_key"
export XFYUN_API_SECRET="your_api_secret"
Parameters
create_task (POST /tasks)
| Parameter | Type | Required | Description |
|---|---|---|---|
--file_url / -u |
string | Yes | Video file OSS URL (视频文件 OSS 地址) |
--src_lang / -f |
string | Yes | Source language code (e.g., en, zh, ja, ko) |
--dest_lang / -t |
string | Yes | Target language code |
list_tasks (GET /tasks)
No parameters required.
get_task (GET /tasks/:taskId)
| Parameter | Type | Required | Description |
|---|---|---|---|
--task_id / -i |
string | Yes | Task ID |
Response Format
Standard response: {"code": 0, "message": "success", "request_id": "xxx", "data": {}}
create_task Response (data)
{
"task_id": "xxx-xxx-xxx",
"status": "waiting_parsing",
"created_at": "2025-01-17T10:30:45Z"
}
list_tasks Response (data)
[
{
"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)
{
"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
| Status | Description |
|---|---|
running |
Task in progress |
completed |
Task completed successfully |
failed |
Task failed |
cancelled |
Task cancelled |
waiting_manual_intervention_segment |
Waiting for transcript editing |
waiting_manual_intervention_refine |
Waiting for translation editing |
Language Codes
| Code | Language |
|---|---|
zh |
Chinese (中文) |
en |
English (英文) |
ja |
Japanese (日文) |
ko |
Korean (韩文) |
ru |
Russian (俄文) |
fr |
French (法文) |
ar |
Arabic (阿拉伯语) |
es |
Spanish (西班牙语) |
yue |
Cantonese (粤语) |
Input Video Requirements
- Format: MP4
- Duration: Max 5 minutes
- Resolution: 720p - 4k
- FPS: Recommended 25
- Audio: Single audio track only
Error Handling
| Error | Cause | Solution |
|---|---|---|
| XFYUN_API_KEY and XFYUN_API_SECRET are required | No credentials configured | Set environment variables |
| --file_url is required | No video URL provided | Provide valid OSS video URL |
| --task_id is required | No task ID provided | Provide valid task ID |
| API error XXXX | Request failed | Check 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
- Video URL: Must be an OSS (Aliyun Object Storage Service) URL accessible by iFlytek
- Task status: Use get_task to check task progress
- Completed tasks: When status is "completed", the output_video_url contains the translated video
- Manual intervention: Some videos may require human review for transcript or translation