# UUToken CLI 快速上手

版本：0.2.2。命令采用即梦常用的生成、查询与下载习惯。

## 安装与初始化

需要 Node.js 22 或以上。在安装包所在目录运行：

```powershell
npm install --global --ignore-scripts ./uutoken-project-cli-0.2.2.tgz
uutoken init D:/my-video-project --url https://uutoken.sbs
```

在同一个 PowerShell 窗口隐藏输入客户自己的本站 Key，不把真实 Key 直接写在命令行里：

```powershell
$uutokenKey = Read-Host '请输入本站 Key（隐藏输入）' -AsSecureString
$uutokenKeyPointer = [IntPtr]::Zero
try {
    $uutokenKeyPointer = [Runtime.InteropServices.Marshal]::SecureStringToBSTR($uutokenKey)
    $env:UUTOKEN_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR($uutokenKeyPointer)
} finally {
    if ($uutokenKeyPointer -ne [IntPtr]::Zero) {
        [Runtime.InteropServices.Marshal]::ZeroFreeBSTR($uutokenKeyPointer)
    }
    $uutokenKey.Dispose()
    Remove-Variable uutokenKey, uutokenKeyPointer
}
```

Key 不写入 PowerShell 命令历史、提示词、项目文件或 MCP 配置；后续 CLI 从当前进程环境读取。环境变量仍是进程内明文，不代表能对本机管理员或同权限进程保密。请使用初始化命令中的 `--url https://uutoken.sbs` 显式指定站点；0.2.2 安装包保持原版本和校验值，不使用包内旧默认地址。

使用结束后，在同一个窗口清除 Key：

```powershell
Remove-Item Env:UUTOKEN_API_KEY -ErrorAction SilentlyContinue
```

## 找模型与看价格

```powershell
uutoken model list --type video --project D:/my-video-project
uutoken model find Seedance --type video --project D:/my-video-project --json
```

模型名和分组 ID 以实时目录为准。指定分组可加 `--group '<分组ID>'`；不指定则沿用本站自动路由。个人价、分组和最终积分扣费由本站 New API 负责，不作汇率换算。

## 文生视频

先预检，不上传素材、不提交生成、不扣费；此操作需要 Key 和联网读取模型目录：

```powershell
uutoken text2video --id shot-01 --model sd2.5-gf-720p --prompt "镜头缓慢推进" --duration 5 --project D:/my-video-project --dry-run
```

确认模型、分组和价格后，使用相同 ID 与参数正式生成。这条命令会提交收费任务：

```powershell
uutoken text2video --id shot-01 --model sd2.5-gf-720p --prompt "镜头缓慢推进" --duration 5 --project D:/my-video-project --poll 900 --download
```

## 图生视频

把参考图放进项目 `references/hero.png` 后预检：

```powershell
uutoken image2video --id shot-02 --model sd2.5-gf-720p --prompt "保持角色一致" --duration 5 --image references/hero.png --project D:/my-video-project --dry-run
```

正式生成时将 `--dry-run` 换成 `--poll 900 --download`。也支持 `frames2video`、`multimodal2video`、`text2image` 与 `image2image`；模型协议未适配时会在生成前拒绝，不自动换模型或丢弃参考图。

## 查结果与继续下载

```powershell
uutoken list_task --project D:/my-video-project
uutoken query_result --submit_id '<当前项目已记录的远程任务ID>' --project D:/my-video-project --poll 900 --download_dir outputs
uutoken assets --project D:/my-video-project --json
```

查询和下载不会重新生成。每次新生成要用新的 `--id`；同一项目已提交的 ID 会拦截重复提交。提交结果不明时先核对本站任务记录，不直接换 ID 重试。

0.2.2 同时兼容本站 content 接口授权的灵境及水库官方签名 MP4，以及本站已认证任务 `external` 返回的三个 `sd2.5-gf-*` 模型 TOS 成片、`seedance-2.5-zk`/`seedance-2.0-zk` 的两个已核实 COS 域名成片。按精确模型、域名和签名规则检查；COS 有效期来自签名时间，不另延长。不跟随外站二次跳转，不向外站发送本站 Key 或 Cookie，不从任意任务结果里的 URL 字段自行下载。

项目素材、提示词、任务记录和下载结果在客户电脑。本站镜像的远端成品最多保留 6 小时，容量不足可能提前淘汰；灵境等官方来源的文件以实际保存情况为准，已下载的本地文件不受影响。

灵境来源的视频：2026-11-07 实测新发放的签名链接有效期为签发后 24 小时（86400 秒），部分历史链接为 12 小时，以实际签名为准。签名期限不等于文件保留期，文件可能先被清理；上游仍建议成功后立即下载，尽量在 6 小时内保存。不要用该期限推断其他来源或本站参考素材的保存时间。

本站 content 下载接口会在签名临近到期或已到期时查询原任务，尝试获取新链接；不会重新生成或额外扣生成费用，也不会延长原文件生命周期。下载失败先用 `query_result` 查询原任务并重试下载，不要提交新的收费任务。直接保存的旧签名 URL 不会自动更新；已清理的文件无法靠重新查询恢复。

## Harness 与 MCP

脚本调用加 `--json`。`uutoken assets --json` 提供本地项目白名单索引；`uutoken mcp --project D:/my-video-project` 提供 stdio MCP，不监听网络端口。付费 MCP 工具必须显式 `confirmBillable:true`。

不支持即梦官方 OAuth、官方模型版本名、云画布节点命令或与网页画布实时同步。`--poll 0` 在本站仍读取一轮状态，该轮最多 30 秒；不代表完全不等待。完整参数以 `uutoken --help` 和 `uutoken schema --json` 为准。