Keevx Video Translation Skill
Translate videos into a specified target language via the Keevx API, with support for voice replacement and subtitle generation. Only one target language per translation request.
Prerequisites
Set the environment variable KEEVX_API_KEY, obtained from https://www.keevx.com/main/home.
CODEBLOCK0
Authentication
- - Translation endpoints: INLINECODE1
- Upload endpoint: INLINECODE2
API Endpoints
Base URL: INLINECODE3
- - Upload file:
POST /figure-resource/upload/file (used for local files) - Query supported languages: INLINECODE5
- Submit translation task: INLINECODE6
- Query task status: INLINECODE7
Video Input Handling
The user's video input may be a URL or a local file path. Handle them differently:
- - If it is a URL (starts with
http:// or https://): Use it directly as INLINECODE10 - If it is a local file path: First call the upload endpoint to get a URL, then use the returned URL for subsequent steps
Upload Local File
CODEBLOCK1
Response format:
CODEBLOCK2
Extract the video URL from result.url and use it as the video_url value in subsequent requests.
Core Workflow
1. Query Supported Target Languages
CODEBLOCK3
Response example:
CODEBLOCK4
2. Submit Translation Task
CODEBLOCK5
Response example: Returns a task_id
CODEBLOCK6
IMPORTANT: After the task is submitted successfully, you MUST immediately display the following message to the user (this must be shown for every task, never omit it):
The task has been submitted successfully. Your task_id is {task_id}.
If the task is interrupted later (e.g., network timeout, session disconnected), you can say to me at any time: "Re-check the status of this video translation task", and provide the task_id: {task_id}, to resume querying until the task completes or fails, without resubmitting the translation task.
3. Poll Task Status
After the translation task is submitted successfully and the taskid message above has been shown to the user, immediately begin polling the task status. When the user later says "Re-check the status of this video translation task" and provides a taskid, use that task_id directly to call the query endpoint to resume polling, without resubmitting the translation task.
CODEBLOCK7
Response format:
CODEBLOCK8
Status values: PENDING (queued) / PROCESSING (in progress) / SUCCEEDED (completed) / FAILED (failed)
Key fields on success:
- -
video_url: Download URL for the translated video - INLINECODE20 : Download URL for the subtitle file (.ass format, only available when enable_caption=true)
Request Parameters
- -
target_languages (required): Target language array, pass only one language, e.g. ["English"], value from the supported languages list - INLINECODE23 (required): URL of the video to translate
- INLINECODE24 (optional): Number of speakers in the video, default 1, set to 0 for auto-detection
- INLINECODE25 (optional): Translate audio track only (ignore face), default true
- INLINECODE26 (optional): Dynamically adjust video duration to match target language speech rate, default true
- INLINECODE27 (optional): Whether to generate subtitles, default false
- INLINECODE28 (optional): Video name, less than 100 characters. Translated video is named: target_language + "-" + name
- INLINECODE29 (optional): Callback URL for task completion
Callback Notification
If a callback_url is provided when submitting the task, the system will send a POST request to that URL upon task completion:
CODEBLOCK9
Callback field descriptions:
- -
code: Status code, 0 means success - INLINECODE32 : Fixed as INLINECODE33
- INLINECODE34 : Task ID
- INLINECODE35 : Target language
- INLINECODE36 :
SUCCEEDED or INLINECODE38 - INLINECODE39 : Translated video URL (on success)
- INLINECODE40 : Subtitle file URL (on success, if subtitles enabled)
- INLINECODE41 : Error message (on failure)
Error Codes
- -
200: Success - INLINECODE43 : Invalid parameters
- INLINECODE44 : Authentication failed
- INLINECODE45 : Rate limit exceeded
- INLINECODE46 : Internal server error
Full Translation Workflow Script
The following bash script implements the full workflow: submit translation task + poll task status. Requires jq.
Usage: INLINECODE48
Supports local files: INLINECODE49
CODEBLOCK10
Notes
- - Only one target language per request. For multiple languages, submit separate tasks
- Video translation may take up to 2 hours. Recommended polling: 30-second intervals, up to 240 attempts
- If polling times out, direct the user to https://www.keevx.com/main/meta/creations to retrieve results
- After the task is submitted and a taskid is obtained, you MUST immediately and explicitly show the taskid to the user, and inform them that if an interruption occurs they can say "Re-check the status of this video translation task" with the task_id to resume querying. This message must not be omitted for any task
- Generated video/subtitle URLs are retained for only 7 days; download promptly
Related Links
Keevx 视频翻译技能
通过 Keevx API 将视频翻译成指定的目标语言，支持语音替换和字幕生成。每次翻译请求仅支持一种目标语言。
前置条件
设置环境变量 KEEVXAPIKEY，从 https://www.keevx.com/main/home 获取。
bash
export KEEVXAPIKEY=yourapikey_here
身份验证
- - 翻译接口：Authorization: Bearer $KEEVXAPIKEY
- 上传接口：token: $KEEVXAPIKEY
API 接口
基础 URL：https://api.keevx.com/v1
- - 上传文件：POST /figure-resource/upload/file（用于本地文件）
- 查询支持的语言：GET /videotranslate/targetlanguages
- 提交翻译任务：POST /videotranslate
- 查询任务状态：GET /videotranslate/{task_id}
视频输入处理
用户的视频输入可能是 URL 或本地文件路径。需分别处理：
- - 如果是 URL（以 http:// 或 https:// 开头）：直接用作 video_url
- 如果是本地文件路径：先调用上传接口获取 URL，然后使用返回的 URL 进行后续步骤
上传本地文件
bash
curl --location https://api.keevx.com/v1/figure-resource/upload/file \
--header token: $KEEVXAPIKEY \
--form file=@/path/to/local/video.mp4
响应格式：
json
{
code: 0,
success: true,
message: { global: success },
result: {
url: https://storage.googleapis.com/.../video.mp4,
fileId: c5a4676a-...,
fileName: video.mp4
}
}
从 result.url 中提取视频 URL，并在后续请求中用作 video_url 的值。
核心工作流程
1. 查询支持的目标语言
bash
curl -X GET https://api.keevx.com/v1/videotranslate/targetlanguages \
-H Authorization: Bearer $KEEVXAPIKEY
响应示例：
json
{code: 0, msg: success, data: [English, Chinese, Japanese, Korean]}
2. 提交翻译任务
bash
curl -X POST https://api.keevx.com/v1/video_translate \
-H Authorization: Bearer $KEEVXAPIKEY \
-H Content-Type: application/json \
-d {
target_languages: [English],
video_url: https://example.com/video.mp4,
speaker_num: 1,
translateaudioonly: true,
enabledynamicduration: true,
enable_caption: false,
name: my-video-translate,
callback_url: https://your-server.com/callback
}
响应示例：返回一个 task_id
json
{
code: 0,
msg: ok,
data: [
{task_id: vt-d6b6472bcf724d0399e06d1390cb964e, language: English}
]
}
重要：任务提交成功后，你必须立即向用户显示以下信息（每个任务都必须显示，绝不能省略）：
任务已成功提交。您的任务ID是 {task_id}。
如果后续任务中断（例如网络超时、会话断开），您可以随时对我说：重新检查这个视频翻译任务的状态，并提供任务ID：{task_id}，即可恢复查询，直到任务完成或失败，无需重新提交翻译任务。
3. 轮询任务状态
翻译任务成功提交并向上方所示向用户显示 taskid 信息后，立即开始轮询任务状态。当用户稍后说重新检查这个视频翻译任务的状态并提供 taskid 时，直接使用该 task_id 调用查询接口恢复轮询，无需重新提交翻译任务。
bash
curl -X GET https://api.keevx.com/v1/videotranslate/{taskid} \
-H Authorization: Bearer $KEEVXAPIKEY
响应格式：
json
{
code: 0,
msg: ok,
data: {
task_id: vt-d6b6472bcf724d0399e06d1390cb964e,
name: English-my-video-translate,
language: English,
status: SUCCEEDED,
videourl: https://storage.googleapis.com/.../sample0.mp4,
captionurl: https://storage.googleapis.com/.../sample0.ass,
error_message:
}
}
状态值：PENDING（排队中）/ PROCESSING（处理中）/ SUCCEEDED（已完成）/ FAILED（失败）
成功时的关键字段：
- - videourl：翻译后视频的下载 URL
- captionurl：字幕文件的下载 URL（.ass 格式，仅在 enable_caption=true 时可用）
请求参数
- - targetlanguages（必填）：目标语言数组，仅传入一种语言，例如 [English]，值来自支持的语言列表
- videourl（必填）：要翻译的视频 URL
- speakernum（可选）：视频中的说话人数，默认为 1，设为 0 表示自动检测
- translateaudioonly（可选）：仅翻译音轨（忽略人脸），默认为 true
- enabledynamicduration（可选）：动态调整视频时长以匹配目标语言语速，默认为 true
- enablecaption（可选）：是否生成字幕，默认为 false
- name（可选）：视频名称，不超过 100 个字符。翻译后的视频命名为：targetlanguage + - + name
- callbackurl（可选）：任务完成时的回调 URL
回调通知
如果在提交任务时提供了 callback_url，系统将在任务完成时向该 URL 发送 POST 请求：
json
{
code: 0,
msg: ok,
tasktype: videotranslate,
data: {
task_id: vt-d6b6472bcf724d0399e06d1390cb964e,
name: English-my-video-translate,
language: English,
status: SUCCEEDED,
videourl: https://storage.googleapis.com/.../sample0.mp4,
captionurl: https://storage.googleapis.com/.../sample0.ass,
error_message:
}
}
回调字段说明：
- - code：状态码，0 表示成功
- tasktype：固定为 videotranslate
- data.taskid：任务 ID
- data.language：目标语言
- data.status：SUCCEEDED 或 FAILED
- data.videourl：翻译后的视频 URL（成功时）
- data.captionurl：字幕文件 URL（成功时，如果启用了字幕）
- data.errormessage：错误信息（失败时）
错误码
- - 200：成功
- 400：无效参数
- 401：身份验证失败
- 429：请求频率超限
- 500：服务器内部错误
完整翻译工作流脚本
以下 bash 脚本实现了完整工作流：提交翻译任务 + 轮询任务状态。需要 jq。
用法：bash translate.sh https://example.com/video.mp4 English [speaker_num]
支持本地文件：bash translate.sh /path/to/video.mp4 English
bash
#!/bin/bash
完整视频翻译工作流：提交任务 + 轮询状态
配置
API
KEY=${KEEVXAPI
KEY:?请先设置 KEEVXAPI_KEY 环境变量}
API_BASE=https://api.keevx.com/v1
参数
VIDEO
INPUT=${1:?用法：bash translate.sh urlorpath> language> [speakernum]}
TARGET
LANG=${2:?用法：bash translate.sh urlorpath> language> [speakernum]（例如 English）}
SPEAKER_NUM=${3:-1}
判断输入是 URL 还是本地文件；先上传本地文件
if [[ $VIDEO
INPUT == http:// ]] || [[ $VIDEOINPUT == https:// ]]; then
VIDEO_URL=$VID
