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 IFLY_API_KEY="your_api_key"
export IFLY_API_SECRET="your_api_secret"

兼容说明：设置任意 IFLY_* 凭证变量（包括空值）后，仅使用该组，缺项报错；未设置标准组时，依次尝试 XFYUN_*、XFEI_*，不跨组拼接。旧前缀会在 stderr 输出一次不含凭证值的迁移提示。

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
IFLY_API_KEY and IFLY_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

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