---
title: MetaDig CLI 完全指南：在终端和 AI 助手里出图出片
section: 命令行
source: https://waytometa.cn/docs/cli/guide
summary: 一行命令安装 metadig，浏览器授权登录，然后就能在终端、脚本或 Cursor / Claude Code 这类 AI 助手里生成图片、视频、配音和音乐，结果自动落到网页画布。
updated: 2026-09-19
---
网页画布适合一张图一张图地磨；但有些活儿更适合命令行——比如给 50 个产品各出一张主图，或者让 Cursor 里的 AI 助手边写文案边配图。`metadig` 就是干这个的：一个单文件的命令行工具，登录一次，之后在终端里敲一行就能提交生成任务，结果直接落到你网页上的画布项目里，随时回去继续编辑。

计费、模型、折扣、会员门禁和网页端完全是一套东西。网页上能用的模型，命令行里就能用；后台下架了某个模型，命令行里也会同步消失，不需要更新工具。

## 安装

### 方式一：交给 AI 助手（推荐）

如果你在用 Cursor、Claude Code、Codex、Kimi、Trae 这类带 Agent 能力的工具，把下面这段话原样发给它：

```text
请帮我安装 MetaDig Skill：克隆 https://github.com/pythonthink/metadig-skills（或下载 https://waytometa.cn/cli-dist/latest/metadig-cli-skill.zip 并解压），
把其中的 metadig/ 目录放进你的 Skills 目录（Cursor 用 .cursor/skills/，Claude Code 用 ~/.claude/skills/，其他工具用 ~/.agents/skills/），
然后按 metadig/SKILL.md 完成 CLI 安装与登录。之后你就可以用 metadig 命令帮我生成图片、视频、配音和音乐了。
```

仓库和 zip 是同一份内容：一个标准的 Agent Skill 目录（`metadig/SKILL.md` + `references/`），助手会照着它装好工具、引导你登录，并且学会怎么查模型、怎么报价、失败了该不该重试。放进 Skills 目录后以后每个新会话都自动可用，装完就可以直接对助手说"帮我出三张 16:9 的秋天海报"，它自己去跑命令。Skill 的详细说明（装到哪个目录、和画布 Skill 广场的区别、常见问题）见 Skills 栏目的《MetaDig Skill 使用指南》（`/docs/skills/agent-skill`）。

### 方式二：手动装

macOS / Linux：

```bash
curl -fsSL https://waytometa.cn/cli/install.sh | bash
```

Windows PowerShell：

```powershell
iwr https://waytometa.cn/cli/install.ps1 -useb | iex
```

工具会装到 `~/.metadig` 并写进 PATH。装完**重新开一个终端**（PATH 要刷新），然后验证：

```bash
metadig --version
```

## 登录

```bash
metadig login
```

它会打印一个授权链接并尝试打开浏览器。你在网页上（已登录的账号）点一下「授权登录」，终端这边两秒内会显示"登录成功"。链接 10 分钟内有效，过了重新执行一次就行。

几件关于登录的事：

- 凭证存在本机 `~/.metadig/credentials.json`，权限只有你自己可读，大约 30 天有效。过期后任何命令都会提示重新 `metadig login`。
- **命令行登录和网页登录互不影响。** 套餐对"同时在线设备数"有限制，但 CLI 的登录不占这个名额，不会把你手机或另一台电脑上的网页登录顶掉。
- 服务器环境没有浏览器？`metadig login --no-open` 只打印链接，你复制到任何一台能登录的设备上打开授权即可。还是不行就用令牌兜底：`metadig login --token <你的令牌>`，或者设环境变量 `METADIG_TOKEN`（它的优先级最高，设了以后本地保存的凭证会被忽略）。
- 只在自己的设备上授权，别人发来的授权链接一律别点——点了就等于把你的账号交给对方的终端。

登录后随时可以用 `metadig whoami` 看当前账号和积分余额，`metadig logout` 退出。

## 先看模型，再生成

模型、价格和参数档位是会变的，所以生成前先查一眼：

```bash
metadig models                 # 全部类型：图片 / 视频 / 语音 / 音乐，带积分价格
metadig models --type video    # 只看视频模型
metadig models seedance-2      # 某个模型的详情：支持的比例、分辨率、时长、渠道、参考素材上限
metadig models --json          # 给程序或 AI 助手解析用
```

列表里的标签能看出模型状态：`会员` 表示免费档用不了，`停用` 表示维护中，`新` 是新上架，`8折` 这种是正在进行的价格活动（表里显示的已经是折后价）。

## 生成

四类任务，四个子命令。所有子命令都支持 `-m` 指定模型（不指定用该类目录里第一个可用的）、`-p` 指定项目、`-o 目录` 完成后自动下载、`--no-wait` 提交后立刻返回、`--json` 机器可读输出。

### 图片

```bash
# 文生图
metadig gen image "一只橘猫在窗台晒太阳，午后暖光，写实" --ratio 16:9

# 图生图：带 -r 参考图就自动走图生图；本地文件会先上传，多张就多写几个 -r
metadig gen image "改成水彩风格" -r ./photo.png -m nano-banana-pro

# 一次出 4 张 2K
metadig gen image "极简风格的产品海报" -n 4 --resolution 2K
```

可用参数：`--ratio` 比例（1:1 / 16:9 / 9:16 等）、`--resolution` 分辨率（1K / 2K / 4K）、`-n` 张数、`--channel` 渠道、`--quality` 质量档、`--format` 输出格式。不传的参数按模型目录取默认，图片默认 1:1、1K。

### 视频

生成方式由你给的素材决定，不用单独指定：

```bash
# 什么素材都不给 → 文生视频
metadig gen video "清晨海边，低机位沿沙滩平稳前移，电影感" -m seedance-2 --resolution 720p -d 5

# --first 首帧图 → 首帧生视频
metadig gen video "镜头缓慢推进，人物微笑" --first ./cover.png -d 5 -o ./exports

# --first + --last → 首尾帧生视频
metadig gen video "从白天过渡到夜晚" --first a.png --last b.png

# -r / --ref-video / --ref-audio → 参考生视频
metadig gen video "保持人物外观一致" -r role.png --ref-video demo.mp4
```

其它参数：`-d` 时长（秒）、`--ratio`、`--resolution`（480p / 720p / 1080p）、`--audio` 让支持的模型带环境音或对白。视频默认 16:9、720p、5 秒。

两个规则：`--last` 必须和 `--first` 一起用；`--first` 和 `--ref` 系列不能混用——首帧模式只认首尾帧图，参考模式用 `-r / --ref-video / --ref-audio`。

> [!WARNING] 视频比图片贵不少
> 一条视频通常几十积分起，高分辨率、长时长、带参考视频都会加价。批量跑之前先用 `metadig models <模型ID>` 看一眼分档价，`--no-wait` 提交一条试试效果再放开跑。

### 语音和音乐

```bash
metadig gen speech "欢迎来到元界深掘" --voice male-qn-qingse
metadig gen music "轻快的夏日流行" --lyrics "夏天的风……" -d 40
metadig gen music "适合 vlog 的轻电子" --instrumental
```

`--voice` 是音色 ID，默认 `male-qn-qingse`，完整音色列表在网页画布的语音节点里试听后照抄 ID 即可。音乐按 5 秒计价的模型默认 40 秒，`-d` 可以改，超出模型范围会自动钳进去；按首计价的模型不支持自定义时长，传了会被忽略并提示。

### 参数不在档位内会怎样

命令行只做提示，不做拦截：你传了一个模型不支持的比例，终端会打一行警告，任务照常提交，最终以服务端校验为准。所以拿不准的时候看 `metadig models <模型ID>` 的详情最稳。

## 结果去了哪

**默认落到网页画布。** 提交成功那一刻，对应画布项目里就会出现一个"生成中"的节点；任务完成后节点自动变成成品。如果你此时正开着那个画布，它是实时出现的；没开的话下次打开就在。这样命令行出的东西和你手动做的在同一张画布上，可以接着连线、改图、进时间线剪辑。

不想弄乱画布？加 `--no-canvas`，产物只进项目的「历史文件」，需要时再从那里拖回来。

**项目归属。** 每个任务都归属某个画布项目。第一次生成时工具会自动建一个叫「CLI 项目」的项目并记为默认，之后都往里放，一般不用管。想分开管理时：

```bash
metadig project list                  # 我的项目
metadig project create "产品广告A"    # 建一个新项目
metadig project use <项目ID>          # 绑定到当前目录
metadig project current               # 看当前生效的是哪个
```

`project use` 会在当前目录写一个 `.metadig/project.json`，这个目录和它的子目录里跑的所有生成都归到该项目。一个片子一个文件夹，各归各的，很顺手。单次任务也可以用 `-p <项目ID>` 临时指定。

**下载到本地。** 生成命令加 `-o ./exports` 会在完成后自动把产物存进去；已经完成的任务用 `metadig download <任务ID> -o ./exports`。

## 任务管理

```bash
metadig status <任务ID>                     # 查状态和产物链接
metadig status <任务ID> --wait -o ./exports  # 等它完成，完成后顺手下载
metadig history                             # 近 7 天的任务记录（最多 50 条）
```

`history` 只列记录不带链接，拿链接用 `status`。等待有上限：一条任务最多等 2 小时，超过会自动放弃等待（任务本身不受影响）。

## 遇到问题

- **提交请求超时。** 这不等于失败。网络抖一下，任务可能已经被受理并预扣了积分。终端会给出 `metadig status <任务ID>` 的提示，先查再决定要不要重提，别看到超时就重复提交。
- **任务失败。** 失败和取消都不扣积分，可以改参数重试。原样重提大概率还是失败，先看 `status` 里的说明。
- **积分不足。** 去网页充值或订阅，命令行里没法充。
- **提示模型维护中、会员专属。** 换 `metadig models` 里其它可用的模型；会员专属的模型需要订阅。
- **401 或"尚未登录"。** 凭证过期了，`metadig login` 一次。
- **想连测试环境。** 全局参数 `--api-base http://localhost:6603`，或者环境变量 `METADIG_API_BASE`。

## 让 AI 助手替你跑

这是 CLI 最省心的用法。装好 Skill 之后（见上面"方式一"，或直接在对话里输入 `/metadig` 调用），助手已经知道这些规矩：生成前先 `metadig models` 查最新目录，不凭记忆写模型 ID；批量或高价任务先向你报方案和预计积分；用 `--json` 解析结果；失败不原样重提。你只需要像跟同事说话一样：

> 用 metadig 给 ./photos 里的 6 张产品图各出一张 16:9 的电商主图，白底，参考原图，2K，先告诉我大概要多少积分。

它会先跑 `models` 查价、报数给你，你点头后逐张 `gen image -r ... --ratio 16:9 --resolution 2K`，最后把链接和落画布的节点 ID 整理给你。

写脚本也一样简单，`--json` 的输出只在标准输出里，进度提示都在标准错误里，管道很干净：

```bash
TASK=$(metadig gen video "海浪拍岸" --no-wait --json | jq -r .taskId)
metadig status "$TASK" --wait -o ./exports --json
```

## 一个完整的例子

从零开始做一条带配音的短片素材：

```bash
mkdir autumn && cd autumn
metadig project create "秋日短片"
metadig project use <上一步输出的项目ID>

# 出一张封面
metadig gen image "秋天的银杏大道，午后逆光，电影感，16:9" --ratio 16:9 --resolution 2K -o ./exports

# 用封面做首帧，出 5 秒视频
metadig gen video "镜头缓慢向前推进，落叶飘下" --first ./exports/<刚下载的图片> -d 5 -o ./exports

# 配一段旁白
metadig gen speech "秋天来了，银杏叶把整条街染成了金色。" -o ./exports
```

跑完打开网页，「秋日短片」这个画布上已经躺着一张图、一条视频、一段音频，接下来拖进时间线剪一剪就是成片。