dubbing

用途

Sonilo Dubbing 用于将一段视频配音成一种或多种其他语言：系统会翻译视频中的语音并重新配音，为每种目标语言生成一个新的 .mp4 视频文件，而不仅仅是生成音轨或字幕。

主要能力

将视频中的语音翻译并重新配音，输出每种语言一个独立的 .mp4 文件。
支持一次请求多种目标语言，每种语言单独计费。
支持的语言代码：en、zh_cn、ja、ko、pt、es、de、fr、it、ru。
输入视频格式支持 .mp4/.mov/.webm/.m4v/.gif（GIF 必须为动图），最长 180 秒（3 分钟），并受账户上传大小上限约束。
可通过 video_url 提供视频地址，但必须是 https（不接受纯 http），配音流程会自行抓取源视频。
输出文件为每种请求语言一个 .mp4，命名为 dubbing-<任务 ID 前 8 个字符>.<语言>.mp4。

使用方式

MCP 工具调用（推荐）

dubbing(
    video_path="~/Desktop/product-demo.mp4",
    languages=["es", "fr"]
)

Python（pip install sonilo）

from sonilo import Sonilo

with Sonilo() as client:  # reads SONILO_API_KEY
    result = client.dubbing.generate(
        video="product-demo.mp4",
        languages=["es", "fr"],
        timeout=7200,  # seconds — matches the backend's own ~2h ceiling
    )
    for language, path in result.save_all("./dubbed").items():
        print(language, path)

JavaScript / TypeScript（npm install sonilo）

import { SoniloClient } from "sonilo";
import type { DubbingResult } from "sonilo";

const client = new SoniloClient(); // reads SONILO_API_KEY

const result = await client.dubbing.generate(
  { video: "./product-demo.mp4", languages: ["es", "fr"] },
  { timeout: 7_200_000 }, // milliseconds — matches the backend's own ~2h ceiling
);
for (const [language, url] of Object.entries((result as DubbingResult).outputs ?? {})) {
  console.log(language, url);
}

CLI（npm install -g sonilo-cli 或 pip install sonilo-cli）

sonilo dubbing --video-url https://example.com/product-demo.mp4 --languages es,fr --output dubbed.mp4
# writes dubbed.es.mp4 and dubbed.fr.mp4

--timeout 默认已是 7200 秒，与后端上限一致，典型调用无需覆盖。

cURL（原始 REST API，无 MCP 主机）

curl -X POST "https://api.sonilo.com/v1/dubbing" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -F "video=@product-demo.mp4" \
  -F 'languages=["es","fr"]'
# -> {"task_id": "..."}  poll GET /v1/tasks/{task_id} — can take up to ~2 hours

工具与参数

工具：dubbing(video_path? | video_url?, languages?, output_directory?)，将视频配音为每种请求语言，每种语言保存一个 .mp4。

参数：

video_path：string，默认无。支持 .mp4/.mov/.webm/.m4v/.gif（GIF 必须为动图）。最长 180 秒（3 分钟），受账户上传大小上限约束。
video_url：string，默认无。必须是 https（不接受纯 http）。video_path 与 video_url 只能二选一。
languages：list[str]，默认 ["zh_cn", "es", "fr"]。目标语言代码，支持 en、zh_cn、ja、ko、pt、es、de、fr、it、ru。省略该参数仍会配音为 3 种语言并按 3 种计费；若用户只需要一种语言，请显式传入单元素列表。
output_directory：string，默认 SONILO_MCP_BASE_PATH。可为绝对路径，或相对于基础路径。

适用场景

需要将产品演示、宣传视频等内容快速本地化为多种语言版本。
需要为视频生成目标语言的配音视频文件（而非仅字幕或音轨）。
通过 MCP、Python、JavaScript/TypeScript、CLI 或 REST API 集成到自动化流程中。

限制与注意事项

计费：按语言计费，没有任何免费试用运行——即使是试用账户也从第一次调用起即收费，这一点与其他 Sonilo 工具不同。请求四种语言的费用是单一语言的四倍。调用前请与用户确认确切的语言列表，不要为了“帮忙”而猜测一长串语言。
耗时：该调用很慢。无论 TIME_OUT_SECONDS 设置多短，内部都会轮询至少两小时，这是后端配音流程自身的上限。调用等待一小时或更久属于正常现象，不是卡死。不要取消：任务无论如何都会继续运行并计费，取消只会失去获取结果的便捷路径（可改用 get_sfx_task，或在托管服务器上使用 get_generation_task 恢复）。
恢复超时调用：如果调用自身的长轮询被中断（例如主机超时或会话关闭），错误信息——或提交时打印到 stderr 的任务 ID——会给出 task_id。调用 get_sfx_task(task_id)（托管服务器上为 get_generation_task(task_id)）检查状态并在完成后下载文件。
该工具不涉及音乐或音效，不会处理音乐/音效，只翻译并重新配音现有语音。
若账户为自助服务且尚未添加支付方式，调用前应提醒用户，避免因 trial_exhausted 失败（该错误甚至不适用——配音无论试用状态如何都立即计费）。如不确定计费状态，可查看 get_account_services。
常见错误：401 无效密钥、402 余额不足（配音没有可耗尽的试用额度，立即计费）、413 文件过大、422 参数无效或不支持的语言代码（在产生任何费用前被拒绝）、429 速率限制。
设置：参见 setup-api-key 技能。

输出文件

每种请求语言一个 .mp4，命名为 dubbing-<任务 ID 前 8 个字符>.<语言>.mp4——没有用于命名文件的提示词，因此所有配音输出都共享基于任务 ID 的名称。