Back to Details

auto-dubbing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Sonilo Dubbing

Sonilo视频配音

Dub a video into one or more other languages: the speech is translated and re-voiced, producing a new 
.mp4
per target language (not just an audio track or subtitles).
Setup: See the setup-api-key skill.
⚠️ Cost — read before calling: this is billed per language, with zero free-trial runs — even a trial account is charged from the very first call, unlike every other Sonilo tool. Requesting four languages costs four times as much as one. Confirm the exact language list with the user before calling; do not guess a long list "to be helpful."
⏱ This call is slow. It polls for at least two hours internally regardless of any shorter 
TIME_OUT_SECONDS
— that's the backend's own ceiling for the dubbing pipeline. A call that sits for an hour or more is normal, not a hang. Do not cancel it: the job keeps running and charging either way, and cancelling just loses the easy path to the result (use 
get_sfx_task
, or 
get_generation_task
on the hosted server, to recover it instead).
将视频配音成一种或多种其他语言：语音会被翻译并重新配音，每种目标语言生成一个新的
.mp4
文件（而非仅生成音轨或字幕）。
设置： 查看setup-api-key技能。
⚠️ 费用说明——调用前必读： 本服务按语言计费，无免费试用次数——与其他Sonilo工具不同，即使是试用账户，从第一次调用开始就会收费。请求四种语言的费用是一种语言的四倍。调用前请与用户确认确切的语言列表，不要为了“提供帮助”而猜测一个长列表。
⏱ 调用耗时较长。无论设置的
TIME_OUT_SECONDS
有多短，内部至少会轮询两小时——这是配音流水线后端的上限。调用耗时一小时或更久属于正常情况，并非卡顿。请勿取消调用：无论是否取消，任务都会继续运行并产生费用，取消只会失去获取结果的便捷路径（改用
get_sfx_task
，或在托管服务器上使用
get_generation_task
来恢复任务）。

Transport: MCP or CLI

传输方式：MCP或CLI

Pick one at the start of the session and stay on it. Do not mix the two inside a single job, and do not announce the choice.
  1. Sonilo MCP tools visible in this session (
    dubbing
    and friends) — use them. This is the preferred path: it needs no shell, and it is the only one that survives a very long generation. If a call fails to authenticate — rather than failing on its inputs — this transport is not usable in this session: go to 2 instead of retrying it.
  2. No usable Sonilo MCP tools, but 
    sonilo account
    exits 0     — use the CLI commands below. Same API, same account, same credential file. Probe with 
    sonilo account
    , not 
    sonilo whoami
    : whoami exits 0 even when signed out, so it cannot tell the two states apart.
  3. Neither — stop and run the setup-api-key skill. Do not call 
    api.sonilo.com
    with curl to work around it; both transports handle uploads, polling and retries that a bare request does not.
⏱ On the CLI path this call cannot be one command. The backend polls for up to two hours, while a host's shell tool is capped far below that (ten minutes in Claude Code), so 
sonilo dubbing
run in the foreground will be killed with the job still running and already charged. Submit it and poll separately instead:
bash
# --timeout is the CLI's own wait, not the job's: this returns before a host
# shell can kill the process. The id comes from the "Submitted task ..." line.
sonilo dubbing --video-url https://example.com/clip.mp4 --languages es,fr --timeout 300
sonilo tasks wait <task-id>   # repeat until it finishes
The MCP path has no such limit and is the better transport for dubbing.
在会话开始时选择其中一种并保持使用。不要在单个任务中混合使用两种方式，也无需告知用户你的选择。
  1. 本次会话中可见的Sonilo MCP工具（
    dubbing
    及相关工具）——使用这些工具。这是首选路径：无需使用shell，并且是唯一能支持长时间生成任务的方式。如果调用因认证失败（而非输入错误），则本次会话无法使用此传输方式：请改用第2种方式，不要重试。
  2. 无可用的Sonilo MCP工具，但
    sonilo account
    命令返回0    ——使用下方的CLI命令。使用相同的API、账户和凭证文件。请用
    sonilo account
    命令检测状态，而非
    sonilo whoami
    ：即使已登出，
    whoami
    仍会返回0，无法区分两种状态。
  3. 上述两种方式都不可用——停止操作并运行setup-api-key技能。请勿使用curl调用
    api.sonilo.com
    来规避：两种传输方式都能处理上传、轮询和重试，而裸请求无法做到这些。
⏱ CLI路径无法通过单个命令完成调用。后端最多轮询两小时，而主机的shell工具上限远低于此（Claude Code中为十分钟），因此在前台运行
sonilo dubbing
会被终止，但任务仍会继续运行并已产生费用。请改为提交任务后单独轮询：
bash
# --timeout是CLI自身的等待时间，而非任务的等待时间：这会在主机shell终止进程前返回结果。任务ID来自“Submitted task ...”行。
sonilo dubbing --video-url https://example.com/clip.mp4 --languages es,fr --timeout 300
sonilo tasks wait <task-id>   # 重复执行直到任务完成
MCP路径无此限制，是配音任务的更佳传输方式。

Quick Start

快速开始

MCP tool call (recommended)

MCP工具调用（推荐）

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

Python (
pip install sonilo
)

Python（
pip install sonilo
）

python
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)
python
from sonilo import Sonilo

with Sonilo() as client:  # 读取SONILO_API_KEY
    result = client.dubbing.generate(
        video="product-demo.mp4",
        languages=["es", "fr"],
        timeout=7200,  # 秒——与后端自身约2小时的上限匹配
    )
    for language, path in result.save_all("./dubbed").items():
        print(language, path)

JavaScript / TypeScript (
npm install sonilo
)

JavaScript / TypeScript（
npm install sonilo
）

ts
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);
}
ts
import { SoniloClient } from "sonilo";
import type { DubbingResult } from "sonilo";

const client = new SoniloClient(); // 读取SONILO_API_KEY

const result = await client.dubbing.generate(
  { video: "./product-demo.mp4", languages: ["es", "fr"] },
  { timeout: 7_200_000 }, // 毫秒——与后端自身约2小时的上限匹配
);
for (const [language, url] of Object.entries((result as DubbingResult).outputs ?? {})) {
  console.log(language, url);
}

CLI (
npm install -g sonilo-cli
or 
pip install sonilo-cli
)

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

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

writes dubbed.es.mp4 and dubbed.fr.mp4

生成 dubbed.es.mp4 和 dubbed.fr.mp4


`--timeout` defaults to 7200 seconds already, matching the backend's ceiling. That is fine in a normal terminal; inside an agent host shell, use the shorter submit-and-poll pattern above so the shell tool does not kill the foreground command.

`--timeout`默认已设置为7200秒，与后端上限匹配。在普通终端中使用无问题；在代理主机shell中，请使用上述较短的“提交并轮询”模式，避免shell工具终止前台命令。

cURL (raw REST API, no MCP host)

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

bash
curl -X POST "https://api.sonilo.com/v1/dubbing" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  -F "video=@product-demo.mp4" \
  -F 'languages=["es","fr"]'
bash
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

-> {"task_id": "..."} 轮询 GET /v1/tasks/{task_id} ——可能需要约2小时


`video_url` is also accepted instead of an uploaded file, but **must be https** — the dubbing pipeline fetches the source itself and rejects plain http.

也接受`video_url`代替上传文件，但**必须为https**——配音流水线会自行获取源文件，拒绝普通http链接。

Tool

工具

ToolDescription
dubbing(video_path? | video_url?, languages?, output_directory?)
Dub a video into each requested language; one 
.mp4
saved per language.
工具描述
dubbing(video_path? | video_url?, languages?, output_directory?)
将视频配音成每种请求的语言；每种语言保存一个
.mp4
文件。

Parameters

参数

ParameterTypeDefaultNotes
video_path
string—
.mp4/.mov/.webm/.m4v/.gif
(gif must be animated). Max 180s (3 min), subject to the account's upload-size cap.
video_url
string—Must be https (not just http). Exactly one of 
video_path
/
video_url
.
languages
list[str]
["zh_cn", "es", "fr"]
Target language codes. Supported: 
en
, 
zh_cn
, 
ja
, 
ko
, 
pt
, 
es
, 
de
, 
fr
, 
it
, 
ru
. Omitting this still dubs into 3 languages and bills for 3 — pass an explicit single-element list if the user only wants one.
output_directory
string
SONILO_MCP_BASE_PATH
Absolute, or relative to the base path.
参数类型默认值说明
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
绝对路径，或相对于基础路径的相对路径。

Workflow Tips

工作流提示

  • Always ask which language(s) if the user hasn't said, rather than relying on the 
    ["zh_cn", "es", "fr"]
    default — that default silently bills for three languages.
  • This is not the music or SFX skills (text-to-music, video-to-music, text-to-sfx, video-to-sfx). It doesn't touch music/SFX at all — it translates and re-voices existing speech.
  • Set expectations on time. Tell the user up front this can take up to ~2 hours and that walking away is fine — the result is recoverable afterward.
  • Because there is no free trial here at all, if the account is self-serve and hasn't added a payment method, warn the user before calling rather than letting it fail with 
    trial_exhausted
    (which doesn't even apply — dubbing bills immediately regardless of trial status). Check 
    get_account_services
    (see account) if unsure about billing status.
  • 如果用户未说明，请务必询问所需语言，不要依赖
    ["zh_cn", "es", "fr"]
    的默认值——该默认值会自动按3种语言计费。
  • 本技能并非音乐或音效技能（text-to-music、video-to-music、text-to-sfx、video-to-sfx）。本技能完全不涉及音乐/音效——仅翻译并重新配音现有语音。
  • 提前告知用户耗时情况。提前告诉用户这可能需要约2小时，离开也无妨——之后仍可恢复结果。
  • 由于本服务完全没有免费试用，如果账户是自助式且未添加支付方式，请在调用前提醒用户，避免因
    trial_exhausted
    失败（实际上该情况不适用——配音服务无论试用状态如何都会立即计费）。若不确定计费状态，请查看
    get_account_services
    （见account技能）。

Recovering a Timed-Out Call

恢复超时的调用

If the call's own long poll is interrupted (e.g. the host itself times out or the session is closed), the error message — or the task id printed to stderr at submission time — gives you a 
task_id
. Call 
get_sfx_task(task_id)
— 
get_generation_task(task_id)
on the hosted server — to check status and download finished files once ready; see task-recovery.
如果调用的长轮询被中断（例如主机自身超时或会话关闭），错误消息——或提交时打印到stderr的任务ID——会提供一个
task_id
。调用
get_sfx_task(task_id)
——在托管服务器上使用
get_generation_task(task_id)
——来检查状态并在任务完成后下载文件；详情请见task-recovery。

Output Files

输出文件

One 
.mp4
per requested language, named 
dubbing-<first 8 chars of the task id>.<language>.mp4
— there's no prompt to name files after, so all dubbing output shares the task-id-based name.
每种请求的语言对应一个
.mp4
文件，命名为
dubbing-<任务ID前8位字符>.<language>.mp4
——没有提示输入文件名，因此所有配音输出都使用基于任务ID的名称。

Error Handling

错误处理

Common errors: 
401
invalid key, 
402
insufficient balance (dubbing has no trial to exhaust — it bills immediately), 
413
file too large, 
422
invalid parameters or unsupported language code (rejected before any charge), 
429
rate limit. See the account skill.
常见错误：
401
密钥无效，
402
余额不足（配音无试用额度——立即计费），
413
文件过大，
422
参数无效或语言代码不支持（计费前会被拒绝），
429
请求频率超限。请查看account技能。