duix-cli

duix-cli 是一个在命令行里创建和管理 Duix 对口型合成任务的工具。

你提供一个本地视频和一个本地音频，它会上传素材、创建合成任务、查询进度，并在任务完成后把生成的视频下载到本地。

准备工作

1. 安装 Bun

运行 duix-cli 需要先安装 Bun。建议使用 Bun 1.3 或更新版本。

安装完成后可以检查版本：

bun --version

2. 安装 duix-cli

npm install -g duix-cli

安装后检查是否可用：

duix-cli --help
duix-cli --version

3. 设置密钥

所有 compose 命令都需要先设置 DUIX_API_KEY。

Windows PowerShell 临时设置：

$env:DUIX_API_KEY="sk-你的密钥"

Windows PowerShell 永久设置：

setx DUIX_API_KEY "sk-你的密钥"

永久设置后，需要重新打开终端才会生效。

macOS / Linux 临时设置：

export DUIX_API_KEY="sk-你的密钥"

macOS / Linux 永久设置：

echo 'export DUIX_API_KEY="sk-你的密钥"' >> ~/.zshrc
source ~/.zshrc

检查当前密钥是否已被读取：

duix-cli --token

快速开始

Windows PowerShell

duix-cli compose create --video "D:\input\video.mp4" --audio "D:\input\audio.wav" --output "D:\output"

创建成功后，输出里会包含 taskId。后续命令都使用这个任务 ID。

duix-cli compose status 795416705633029
duix-cli compose status 795416705633029 -c
duix-cli compose download 795416705633029

macOS / Linux

duix-cli compose create --video "$HOME/input/video.mp4" --audio "$HOME/input/audio.wav" --output "$HOME/output"

创建成功后，输出里会包含 taskId。

duix-cli compose status 795416705633029
duix-cli compose status 795416705633029 -c
duix-cli compose download 795416705633029

常用命令

查看帮助和版本

duix-cli --help
duix-cli --version

创建合成任务

duix-cli compose create --video <视频文件路径> --audio <音频文件路径> [--output <输出目录>]

也可以使用短参数：

duix-cli compose create -v <视频文件路径> -a <音频文件路径> -o <输出目录>

参数说明：

| 参数 | 必填 | 说明 | | --- | --- | --- | | --video, -v | 是 | 本地视频文件路径 | | --audio, -a | 是 | 本地音频文件路径 | | --output, -o | 否 | 生成视频下载后的保存目录 |

说明：

• 当前只支持本地文件路径，不支持直接传 URL。
• 如果不传 --output，生成视频会保存到系统默认下载目录。
• 如果视频或音频格式不符合要求，工具会自动尝试转换，并在原文件目录生成转换后的文件。
• 创建成功后，请保存输出中的 taskId。

查询单个任务

duix-cli compose status <taskId>

这个命令只查询一次当前状态。

等待任务完成

duix-cli compose status <taskId> -c

加上 -c 后，工具会每 3 秒查询一次，直到任务成功或失败。

查看任务列表

duix-cli compose status ls

这个命令会列出当前密钥创建过的任务，并刷新未完成任务的状态。

下载生成视频

duix-cli compose download <taskId>

下载前会先确认任务是否成功。只有任务成功并且返回了生成视频地址时，才会下载到本地。

下载成功后，工具会自动尝试删除云端合成结果。如果自动删除失败，可以手动执行：

duix-cli compose delete <taskId>

删除任务和云端结果

duix-cli compose delete <taskId>

删除成功后，本地任务记录也会被清理。

完整使用流程

# 1. 设置密钥
export DUIX_API_KEY="sk-你的密钥"

# 2. 创建任务
duix-cli compose create --video "$HOME/input/video.mp4" --audio "$HOME/input/audio.wav" --output "$HOME/output"

# 3. 等待任务完成
duix-cli compose status 795416705633029 -c

# 4. 下载结果
duix-cli compose download 795416705633029

# 5. 如有需要，手动删除云端结果和本地记录
duix-cli compose delete 795416705633029

Windows PowerShell 示例：

$env:DUIX_API_KEY="sk-你的密钥"

duix-cli compose create --video "D:\input\video.mp4" --audio "D:\input\audio.wav" --output "D:\output"
duix-cli compose status 795416705633029 -c
duix-cli compose download 795416705633029
duix-cli compose delete 795416705633029

输出说明

compose 命令会输出 JSON，方便复制任务 ID 或在脚本里读取。

常见字段：

| 字段 | 说明 | | --- | --- | | ok | 命令是否成功 | | exitCode | 退出码 | | command | 当前执行的命令 | | data | 命令返回的数据 | | messages | 执行过程中的提示信息 |

创建任务时，重点关注：

| 字段 | 说明 | | --- | --- | | data.taskId | 任务 ID，后续查询、下载、删除都要用 | | data.status | 当前任务状态 | | data.progress | 当前进度 | | data.outputDir | 下载结果保存目录 |

查询任务时，重点关注：

| 字段 | 说明 | | --- | --- | | data.status | 当前任务状态 | | data.progress | 当前进度 | | data.outputUrl | 任务成功后的生成视频地址 | | data.failureReason | 失败原因 |

常见任务状态：

| 状态 | 说明 | | --- | --- | | PENDING | 等待处理 | | QUEUED | 排队中 | | RUNNING | 处理中 | | SUCCEEDED | 已成功 | | FAILED | 已失败 |

文件保存位置

生成视频的保存位置由 --output 决定。

如果创建任务时没有传 --output，默认会保存到系统下载目录：

• Windows：通常是 Downloads 或 下载
• macOS / Linux：通常是 ~/Downloads

工具还会在本地保存任务记录，用于后续查询、下载和删除。默认目录：

Windows: %USERPROFILE%\.duix-cli
macOS:   ~/.duix-cli
Linux:   ~/.duix-cli

如需修改任务记录保存目录，可以设置 DUIX_STORE_DIR：

Windows PowerShell：

$env:DUIX_STORE_DIR="D:\work\duix-data"

macOS / Linux：

export DUIX_STORE_DIR="$HOME/.duix-data"

注意：DUIX_STORE_DIR 只影响本地任务记录，不影响生成视频的下载目录。生成视频目录仍由 --output 控制。

退出码

| 退出码 | 说明 | | --- | --- | | 0 | 成功 | | 1 | 一般错误，例如参数或本地文件问题 | | 2 | 用法错误，例如缺少必填参数 | | 3 | 认证或授权失败 | | 4 | 服务端错误 | | 5 | 资源不存在，例如任务 ID 无效 |

常见问题

提示没有检测到 DUIX_API_KEY

先设置密钥，再重新执行命令：

export DUIX_API_KEY="sk-你的密钥"

Windows PowerShell 使用：

$env:DUIX_API_KEY="sk-你的密钥"

创建任务后怎么拿到任务 ID？

创建任务命令会输出 JSON，任务 ID 在 data.taskId。

任务还没完成时可以下载吗？

不可以。请先用下面的命令等待任务完成：

duix-cli compose status <taskId> -c

状态为 SUCCEEDED 后再下载。

--output 传文件还是目录？

--output 是目录。生成视频会下载到这个目录下。

可以直接传视频 URL 或音频 URL 吗？

当前版本只支持本地文件路径。