@dlazy/cli

English · 中文

@dlazy/cli 提供 dlazy 终端命令，方便在 Shell 管道中运行 dLazy 的 AI 工具。

每条命令输出统一的 ToolResult 信封，一个工具的输出可直接管道喂给下一个。

访问 https://dlazy.com/docs 获取更多信息。

安装

# 全局安装（把 `dlazy` 加入 PATH）
npm install -g @dlazy/cli

# 项目内（通过 `npx dlazy ...` 调用）
npm install @dlazy/cli
# 或：pnpm add @dlazy/cli   |   yarn add @dlazy/cli

登录认证

dlazy login                 # 设备码流程，浏览器扫码授权后保存到 ~/.dlazy/config.json
dlazy login --local         # 使用 http://localhost:3000，便于本地服务端联调
dlazy auth set sk-xxxx      # 直接写入 Token
dlazy auth get              # 查看当前 Token（已脱敏）
dlazy auth get --show       # 显示完整 Token
dlazy logout                # 从配置中清除 Token

运行时的 API Key 解析顺序：--api-key 参数 → DLAZY_API_KEY 环境变量 → ~/.dlazy/config.json → 交互式登录（仅在 TTY 下触发）。

CLI 快速上手

# 单图生成
dlazy gpt-image-2 --prompt "雨夜赛博朋克猫"

# 两个工具串成管道（自动解析上游产物）
dlazy gpt-image-2 --prompt "侦探侧脸" \
  | dlazy veo-3.1 --image - --prompt "雨夜镜头推进"

# 列出 / 详查工具
dlazy tools list
dlazy tools describe gpt-image-2

# 异步任务：先提交，后查询
dlazy veo-3.1 --image hero.png --prompt "..." --no-wait
dlazy status gen_abc123 --wait

全局参数

| 参数 | 作用 | | --------------------- | -------------------------------------------------------------- | | --api-key <key> | 覆盖本次运行的 API Key | | --base-url <url> | 覆盖服务端地址（默认 DLAZY_BASE_URL 或 https://dlazy.com） | | --verbose | 在 stderr 输出调试日志 | | --format <mode> | 控制 stdout 形态：json（默认） / url / text | | -l, --lang <locale> | 帮助 / 输出语言：en-US 或 zh-CN |

语言也会按 DLAZY_LANG → LC_ALL → LANG 顺序回退识别。

单次运行参数（每个工具命令通用）

| 参数 | 作用 | | ---------------------- | ------------------------------------------------------------------------------------------- | | --dry-run | 解析所有引用并回显 payload，不做鉴权 / 上传 / 联网 | | --no-wait | 异步工具：立刻返回 { generateId, status } | | --timeout <seconds> | 异步任务的轮询超时（默认 1800 秒） | | --input <jsonOrFile> | 内联 JSON 对象，或 @path/to/file.json；与 flag 合并，flag 值优先 | | --save <path> | 将结果素材下载到该本地路径（自动 mkdir + 重试） | | --batch <n> | 同 input 并行执行 N 次，outputs 合并（仅对 image / video / audio / text / auto 类工具有效） |

输出模式 --format

stderr 始终是给人看的进度提示；stdout 由 --format 决定。

| 模式 | stdout 内容 | | -------------- | ----------------------------------------------------------- | | json（默认） | 完整信封 { ok, result } 或 { ok: false, code, message } | | url | 每行一个 URL（仅媒体类 output） | | text | 每行一段文本（仅 text 类 output） |

要保存生成的素材，用 --save（自动下载、建目录、重试）：

dlazy gpt-image-2 --prompt "logo" --save logo.png

# script 输出结构化分镜 JSON；用 jq 提取 markdown 渲染
dlazy script --prompt "6 个流浪猫的电影分镜" \
  | jq -r '.result.outputs[0].value.texts[0]' > script.md

# 默认 JSON 模式 + jq，直接取信封字段
dlazy gpt-image-2 --prompt "..." | jq -r '.result.outputs[0].url'
dlazy veo-3.1 --image hero.png --prompt "..." \
  | jq 'if .ok then .result else .message end'

管道引用语法

CLI flag 值可使用引用语法，从上游 stdin 信封里取数据。所有引用在网络请求前替换完成。

| 语法 | 含义 | | --------------- | ------------------------------------------------------------------- | | - | 自动选取 —— 标量字段取首个 output 的 url/text/value，数组字段取全部 | | @<n> | 第 n 个 output 的 primary value（@0 为第一个） | | @<n>.<path> | 进入 output 内部字段（如 @0.url、@1.meta.fps、@0.text） | | @* | 所有 outputs 的 primary value 数组 | | @stdin | 整个 stdin 信封 | | @stdin:<path> | 对整个信封做 jsonpath（如 @stdin:result.usage.creditsCost） |

示例：

# 1) 单图自动接到视频
dlazy gpt-image-2 --prompt "..." \
  | dlazy veo-3.1 --image - --prompt "雨夜推进"

# 2) 取 4 张图里第 2 张
dlazy gpt-image-2 --batch 4 --prompt "..." \
  | dlazy veo-3.1 --image @1.url --prompt "缓推"

# 3) 数组字段：上游全部 url 自动展开
dlazy gpt-image-2 --batch 4 --prompt "..." \
  | dlazy merge --videos -

# 4) script 输出的分镜文本驱动下一个 prompt
dlazy script --prompt "6 个流浪猫的电影分镜" \
  | dlazy gpt-image-2 --prompt @stdin:result.outputs[0].value.storyboards[0].firstFramePrompt

引用对所有 flag 都生效（prompt、url、id 都可以）。--dry-run 可以查看引用替换后的 input，不真正调用 API。

本地文件与 Data URL

媒体字段（--image、--video、--audio 等）支持三种值：

• https://... —— 原样传入
• data:image/png;base64,... —— 自动上传到对象存储后替换为公开 URL
• ./path/to/file.png —— 自动上传到对象存储后替换为公开 URL

dlazy gpt-image-2 --image ./hero.png --prompt "油画风格"

文件大于 100 MB 会有警告日志；大于 500 MB 会被直接拒绝。

批量生成

所有生成类工具（image / video / audio / text / auto）都支持 --batch <n>，CLI 会用同一份输入并行执行 N 次，并把每次的 outputs 合并到同一个信封：

# 一次出 4 张图（并行），合并到 outputs[0..3]
dlazy gpt-image-2 --prompt "雨夜赛博朋克猫" --batch 4

# 配合管道引用：4 张图直接喂给下一个工具
dlazy gpt-image-2 --prompt "..." --batch 4 \
  | dlazy veo-3.1 --image @0.url --prompt "镜头推进"

usage.creditsCost / tokenIn / tokenOut 会跨子任务求和；durationMs 取并行墙钟（最大值）。配合 --no-wait 时，每个子任务的 task 会以 json 类型 output 的形式落到 outputs 数组里，方便下游管道继续读取所有 generateId。

异步任务

视频类工具大多是异步任务，CLI 默认会轮询直到完成。手动控制：

dlazy veo-3.1 --image hero.png --no-wait                  # 立即返回 generateId
dlazy status gen_abc123 --wait --tool veo-3.1             # 阻塞直到完成（按工具的 outputSchema 解析）
dlazy status gen_abc123                                    # 单次查询

--timeout <seconds> 控制轮询超时（默认 30 分钟）。status 命令传 --tool <cli_name> 可按对应工具的 outputSchema 解析结果；不传则按原始 JSON 输出。

工具发现

dlazy <tool> --help            # 该工具所有参数 / 默认值 / 依赖关系
dlazy tools list               # 注册表概览
dlazy tools describe <tool>    # 完整 input / output JSON Schema

CLI 会把 manifest 缓存到 ~/.dlazy/manifest-<locale>.json，TTL 24 小时，并在后台静默刷新。这样 --help 在弱网 / 离线下依然秒开。

ToolResult —— 统一输出契约

CLI 在 stdout 把结果包成 { ok: true, result }：

type ToolResult = {
  tool: string // cli_name，如 "seedream-4.5"
  modelId: string // 服务端模型 id
  outputs: Output[] // 始终是数组，永远不是标量
  usage?: {
    creditsCost?: number
    durationMs?: number
    tokenIn?: number
    tokenOut?: number
  }
  task?: {
    // wait=false 或异步任务时存在
    generateId: string
    status: 'pending' | 'running'
  }
}

CLI 默认 --format json 的成功信封：

{
  "ok": true,
  "result": {
    "tool": "gpt-image-2",
    "modelId": "gpt-image-2",
    "outputs": [
      {
        "type": "image",
        "id": "o_8a1f3b7d",
        "url": "https://cdn.dlazy.com/...png",
        "mimeType": "image/png"
      }
    ]
  }
}

失败信封：

{ "ok": false, "code": "insufficient_balance", "message": "...", "details": {} }

退出码：成功 0；运行时 / 网络错误 1；输入 / 配置错误 2（缺字段、JSON 解析失败、未知工具、引用错误等）。

支持的工具

下表为快照，请用 dlazy tools list 查看实时注册表，用 dlazy tools describe <name> 查看完整 schema。

| 命令 | 类型 | 说明 | | -------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------- | | seedream-4.5 | 图片 | 豆包 Seedream 4.5 高质量文生图 / 参考图生图 | | seedream-5.0-lite | 图片 | 豆包 Seedream 5.0 轻量高速生成 | | banana2 / banana-pro | 图片 | Gemini Banana 通用 / Pro 文生图 | | gpt-image-2 | 图片 | GPT Image 2（文 + 参考图编辑） | | grok-4.2 | 图片 | 极简文生图 | | recraft-v3 / recraft-v3-svg / recraft-v4* | 图片 | 风格化 / 矢量 / Pro 系列 | | kling-image-o1 | 图片 | 可灵图像（多图占位约束） | | mj-imagine | 图片 | Midjourney 风格 | | viduq2-t2i / jimeng-t2i | 图片 | Vidu / 即梦文生图 | | imageseg / superres | 工具 | 抠图 / 超分辨率 | | veo-3.1 / veo-3.1-fast | 视频 | Veo 高质量 / 极速版文生视频 | | seedance-2.0 / seedance-2.0-fast / seedance-1.5-pro | 视频 | 字节 Seedance 视频 | | kling-v3 / kling-v3-omni | 视频 | 可灵 V3 / 全控版 | | wan2.6-r2v / wan2.6-r2v-flash / wan2.7 | 视频 | 通义万相视频 | | pixverse-c1 | 视频 | PixVerse C1（动作 / 特效） | | viduq2-i2v | 视频 | Vidu 图生视频 | | jimeng-i2v-first / jimeng-i2v-first-tail / jimeng-dream-actor / jimeng-omnihuman-1.5 | 视频 | 即梦视频系列 | | video-replicate / image-replicate | 视频 / 图片 | Replicate 桥接模型 | | video-scenes / merge | 视频 | 分镜切割 / 多片段合并 | | gemini-2.5-tts | 音频 | Gemini 2.5 Pro TTS | | keling-tts / doubao-tts | 音频 | 可灵 / 豆包语音合成 | | keling-sfx | 音频 | 音效 / 拟音 | | suno-music | 音频 | Suno 音乐生成 | | vidu-audio-clone / kling-audio-clone | 音频 | 声音克隆 | | plan / execute | 文本 | 工作流规划 / 执行 | | script | 文本 | 分镜脚本生成：从自由文本简介（可选参考图）产出结构化的 subjects 主体 + storyboards 分镜 |

运行环境

• Node.js ≥ 18（构建目标 node18，依赖 fetch 和异步迭代器）。
• CLI 打包为单个 CJS bundle。