Skill: jinchanzis/ai-media-generator-ai-media-cli (version 1.0.0)

--- name: ai-media-cli description: Use when someone wants to install, configure, onboard, script, or troubleshoot the ricebowl.ai-first ai-media CLI. version: 1.0.0 metadata: openclaw: requires: env: - AI_MEDIA_BASE_URL - AI_MEDIA_API_KEY bins: - ai-media primaryEnv: AI_MEDIA_API_KEY skillKey: ai-media-cli emoji: "🧰" homepage: https://github.com/214140846/ai-media-generator install: - kind: node package: ai-media-generator bins: [ai-media] --- # ai-media CLI 用这个 skill 处理这些请求： - 安装 `ai-media-generator` - 配置 `ai-media` CLI - 对接 <a href="https://ricebowl.ai">ricebowl.ai</a> - 讲命令参数、常用法、脚本化调用 - onboarding 新用户，包括充值、生成 key、写入配置 如果用户明显是在搜某类生成能力，优先切到更窄的 skill： - `ai-image-generation` - `ai-video-generation` - `sora2-video-generator`（legacy） ## Quick Start 默认平台就是 `ricebowl.ai`，按这个顺序带用户走： ```text install -> recharge credits -> create API key -> set key -> config show -> models list --json -> run first image/video task ``` ## What To Explain By Default 默认要讲清楚这 4 件事： 1. 安装包名是 `ai-media-generator` 2. 实际命令名是 `ai-media` 3. 核心配置只有 `api_key` 4. 环境变量 `AI_MEDIA_API_KEY` 会覆盖本地配置 5. `--param KEY=VALUE` 是模型专属参数的通用透传入口，JSON 值会自动按原类型解析 ## Core Commands 常用命令： ```bash ai-media config set-key <KEY> ai-media config show ai-media models list ai-media models list --json ai-media models show --model <MODEL> ai-media image generate --model <MODEL> --prompt <PROMPT> ai-media image get --task-id <TASK_ID> ai-media video generate --model <MODEL> --prompt <PROMPT> ai-media video get --task-id <TASK_ID> ai-media task get --kind <image|video> --task-id <TASK_ID> ai-media image generate --model <MODEL> --prompt <PROMPT> --param KEY=VALUE ai-media video generate --model <MODEL> --prompt <PROMPT> --param KEY=VALUE ``` ## When To Load References - 参数全表、默认值、输出行为、模型参数模板：读 `references/cli-commands.md` - 充值、生成 key、平台 onboarding：读 `references/platform-onboarding.md` ## Response Pattern 如果用户是第一次接触这个 CLI，优先给： 1. 最短安装命令 2. 平台充值路径 3. 生成 key 的位置 4. 一组可直接复制的配置命令 5. 一条图片命令或视频命令 如果用户要自动化或脚本集成，补充： - `models list --json` - `models show --model <MODEL>` - `image/video/task get` - `--wait` - `--poll-interval` - `--param KEY=VALUE` - 环境变量覆盖方式 ## Friendly Onboarding Snippet ```bash ai-media config set-key gm_xxx ai-media config show ai-media models list --json ```

path: references/cli-commands.md
content: # ai-media CLI Commands

## Install Matrix

```bash
# Rust
cargo install ai-media-generator

# npm / pnpm / bun
npm install -g ai-media-generator
pnpm add -g ai-media-generator
bun add -g ai-media-generator

# Python
pipx install ai-media-generator
uv tool install ai-media-generator
```

实际可执行命令：

```bash
ai-media
```

## Config

### `ai-media config set-key <KEY>`

- 用途：保存受管 API key
- 例子：`ai-media config set-key gm_xxx`

### `ai-media config show`

- 用途：打印当前配置
- 输出：pretty JSON

## Default Platform

当前默认平台固定为 `ricebowl.ai`，用户不需要手动设置 `base_url`。

历史兼容说明：

- 旧版文档可能会出现 `ai-media config set-base-url ...`
- 旧版环境变量可能会出现 `AI_MEDIA_BASE_URL`
- 这两种写法现在都不作为默认用户路径推荐

## Models

### `ai-media models list`

- 用途：查看当前 API 暴露的模型
- 输出：按 `Videos` 和 `Images` 分组的人类可读文本

### `ai-media models list --json`

- 用途：给 agent、脚本、流水线消费
- 输出：JSON，包含每个模型的 `parameters` manifest

### `ai-media models show --model <MODEL>`

- 用途：查看单个模型的参数要求
- 例子：`ai-media models show --model veo3-1`
- JSON：`ai-media models show --model nano-banana --json`

### `ai-media models show`

- 用途：查看单个模型的参数元数据
- 输出：人类可读文本，或 `--json`

```bash
ai-media models show --model veo3.1
ai-media models show --model veo3.1 --json
```

优先用它来判断某个模型应该传哪些 `--param KEY=VALUE`。

## Image

### `ai-media image generate`

用法：

```bash
ai-media image generate [OPTIONS] --model <MODEL> --prompt <PROMPT>
```

参数：

- `--model <MODEL>` 必填
- `--prompt <PROMPT>` 必填
- `--aspect-ratio <ASPECT_RATIO>` 选填
- `--response-format <RESPONSE_FORMAT>` 选填
- `--image <IMAGE_URL>` 选填，可重复
- `--metadata-json <JSON>` 选填
- `--param <KEY=VALUE>` 选填，可重复
- `--wait` 选填
- `--poll-interval <POLL_INTERVAL>` 选填，默认 `5`

常用例子：

```bash
ai-media image generate \
  --model nano-banana \
  --prompt "a cinematic ramen bowl on a wooden table" \
  --aspect-ratio 1:1
```

```bash
ai-media image generate \
  --model nano-banana \
  --prompt "studio portrait lighting, close-up ramen bowl" \
  --aspect-ratio 1:1 \
  --image https://example.com/reference.png \
  --param vendor_options='{"style":"cinematic"}' \
  --wait \
  --poll-interval 3
```

行为：

- 不带 `--wait`：打印初始创建任务响应
- 带 `--wait`：轮询直到任务变成 `completed` 或 `failed`
- `--param` 值会合并进请求 body，像 `true`、`8`、`["url"]` 这样的值会优先按 JSON 解析

### `ai-media image get`

用法：

```bash
ai-media image get [OPTIONS] --task-id <TASK_ID>
```

参数：

- `--task-id <TASK_ID>` 必填
- `--wait` 选填
- `--poll-interval <POLL_INTERVAL>` 选填，默认 `5`

## Video

### `ai-media video generate`

用法：

```bash
ai-media video generate [OPTIONS] --model <MODEL> --prompt <PROMPT>
```

参数：

- `--model <MODEL>` 必填
- `--prompt <PROMPT>` 必填
- `--aspect-ratio <ASPECT_RATIO>` 选填
- `--duration <DURATION>` 选填
- `--image <IMAGE_URL>` 选填，可重复
- `--param <KEY=VALUE>` 选填，可重复
- `--wait` 选填
- `--poll-interval <POLL_INTERVAL>` 选填，默认 `8`

常用例子：

```bash
ai-media video generate \
  --model seedance-pro-fast \
  --prompt "steam rising from a rice bowl, cinematic close-up" \
  --aspect-ratio 16:9 \
  --duration 5 \
  --param resolution=720p \
  --param seed=42
```

```bash
ai-media video generate \
  --model veo3-1 \
  --prompt "slow dolly shot over a steaming rice bowl" \
  --aspect-ratio 16:9 \
  --duration 4 \
  --image https://example.com/start-frame.png \
  --param audio=true \
  --wait
```

行为：

- 不带 `--wait`：打印初始创建任务响应
- 带 `--wait`：轮询直到任务变成 `SUCCESS` 或 `FAILURE`
- `--param` 值会合并进请求 body，像 `true`、`8`、`["url"]` 这样的值会优先按 JSON 解析

### `ai-media video get`

用法：

```bash
ai-media video get [OPTIONS] --task-id <TASK_ID>
```

参数：

- `--task-id <TASK_ID>` 必填
- `--wait` 选填
- `--poll-interval <POLL_INTERVAL>` 选填，默认 `5`

## Task

### `ai-media task get`

用法：

```bash
ai-media task get [OPTIONS] --kind <KIND> --task-id <TASK_ID>
```

参数：

- `--kind <KIND>` 必填，可选值：`image`、`video`
- `--task-id <TASK_ID>` 必填
- `--wait` 选填
- `--poll-interval <POLL_INTERVAL>` 选填，默认 `5`

## Config Precedence

```text
AI_MEDIA_API_KEY
  -> local config file
  -> built-in ricebowl.ai default
```

本地配置文件路径：

```text
<system config dir>/ai-media/config.json
```

## Script-Friendly Usage

适合自动化的命令：

- `ai-media config show`
- `ai-media models list --json`
- `ai-media models show --model`
- `ai-media image generate`
- `ai-media image get`
- `ai-media video generate`
- `ai-media video get`
- `ai-media task get`

例子：

```bash
ai-media models list --json
ai-media image get --task-id img_task_xxx | jq .
```

## Model Family Templates

这些模板对应 upstream API 里最常见的模型专属字段。遇到更细的模型参数，先跑 `models show --model <MODEL>`，再决定哪些字段走内建 flag，哪些字段走 `--param`。
先跑 `ai-media models show --model <MODEL>`，再决定要塞哪些 `--param KEY=VALUE`。

### Veo

文本转视频常见参数：

- `--aspect-ratio 16:9`
- `--param enhance_prompt=true`
- `--param enable_upsample=true`

```bash
ai-media video generate \
  --model veo3.1 \
  --prompt "cinematic bowl of ramen under soft light" \
  --aspect-ratio 16:9 \
  --param enhance_prompt=true \
  --param enable_upsample=true
```

图生视频常见参数：

- `--aspect-ratio 16:9`
- `--param images='["https://example.com/reference.png"]'`

```bash
ai-media video generate \
  --model veo3.1 \
  --prompt "steam drifting upward, gentle camera push-in" \
  --param images='["https://example.com/reference.png"]' \
  --aspect-ratio 16:9
```

### Seedance / 参考图视频

- `--aspect-ratio 16:9`
- `--param images='["https://example.com/reference.png"]'`

```bash
ai-media video generate \
  --model doubao-seedance-1-5-pro-251215 \
  --prompt "slow push-in over the food" \
  --param images='["https://example.com/reference.png"]' \
  --duration 4
```

### Flux / Recraft / 其他图片模型

- `size=1024x1024`

```bash
ai-media image generate \
  --model bfl/flux-2-max \
  --prompt "minimal product photo of a ceramic bowl" \
  --param size=1024x1024
```

## Historical Notes

如果你在旧脚本里看到 `set-base-url` 或 `AI_MEDIA_BASE_URL`，那是历史兼容写法。当前默认路径里，只有 `AI_MEDIA_API_KEY` 还保留为推荐的可覆盖配置。


path: references/platform-onboarding.md
content: # Platform Onboarding

## Supported Hosted Platforms

- <a href="https://ricebowl.ai">ricebowl.ai</a>

## First-Time Onboarding

```text
sign in
  -> buy credits or subscription
  -> open account / profile
  -> create API key
  -> copy plaintext key now
  -> ai-media config set-key ...
  -> ai-media models list --json
```

## ricebowl.ai

### 1. Recharge

- 打开 <a href="https://ricebowl.ai/pricing">ricebowl.ai/pricing</a>
- 选择适合的套餐或积分档位
- 完成支付后，credits 会进入当前账户

### 2. Generate API Key

基于站点源码，账号中心支持 `Profile -> API Keys`，并且 API Keys tab 的路由是：

```text
/profile?tab=api-keys
```

实际操作：

1. 登录 ricebowl.ai
2. 进入个人中心 `Profile`
3. 切到 `API Keys`
4. 点击 `Create API Key`
5. 立即复制明文 key

注意：

- 明文 key 只会完整显示一次
- key 前缀形如 `gm_xxx`
- 最好每个集成单独建一个 key，后续撤销更安全

### 3. Configure CLI

```bash
ai-media config set-key gm_xxx
ai-media config show
ai-media models list --json
```

## Environment Variable Setup

如果不想把 key 落到本地配置文件，可以直接用环境变量：

```bash
export AI_MEDIA_API_KEY=gm_xxx
```

历史兼容说明：

- 旧版脚本里可能还会出现 `AI_MEDIA_BASE_URL`
- 当前默认用户路径不再需要它
- 如果旧脚本依赖它，可以先保留，但新文档不再推荐

## First Working Commands

图片：

```bash
ai-media image generate \
  --model nano-banana \
  --prompt "a cinematic ramen bowl on a wooden table" \
  --aspect-ratio 1:1 \
  --wait
```

视频：

```bash
ai-media video generate \
  --model seedance-pro-fast \
  --prompt "steam rising from a rice bowl, cinematic close-up" \
  --aspect-ratio 16:9 \
  --duration 2 \
  --wait
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)