ai-image-cli
# AI Image — AI 图像生成技能
`ai-image-cli` 是 AI 图像生成工具，支持文生图和图生图两大核心能力。
| 能力 | 提供商 | 模型 | 说明 |
|------|--------|------|------|
| 文生图 | AIGW | doubao-seedream-4-5 | 根据文本描述生成图片 |
| 图生图 | AIGW | doubao-seededit-3-0-i2i | 基于源图片和文本生成新图片 |
## 命令选择
根据用户意图，直接选择对应子命令：
- **用户想根据描述生成新图片** → `ai-image text2img "<描述>"`
- **用户提供了图片 URL，想要修改或编辑** → `ai-image img2img "<修改描述>" <URL>`
- **查看工具能力** → `ai-image capabilities`
## 命令速查
| 命令 | 用途 | 关键选项 |
|------|------|----------|
| `ai-image text2img "<描述>"` | 文生图 | `-s` 尺寸, `--seed` 种子, `-g` 引导系数, `--watermark` |
| `ai-image img2img "<描述>" <URL>` | 图生图 | `--seed` 种子, `-g` 引导系数, `--watermark` |
| `ai-image capabilities` | 查看工具能力(JSON) | 无参数，无需认证 |
所有命令输出 JSON 格式，`success` 字段标识成功或失败。
## Quick Start
直接执行命令即可，无需预检。如果命令不存在或返回错误，再执行环境诊断：
```bash
# 诊断环境
bash {baseDir}/scripts/preflight.sh
# 如果 cli_installed: false，执行安装
bash {baseDir}/scripts/install.sh
```
## 常用工作流
### 文生图 (text2img)
```bash
# 基本用法
ai-image text2img "一个中国女孩,高清"
# 指定尺寸
ai-image text2img "夕阳下的海滩" --size 1920x1920
# 使用随机种子(可复现)
ai-image text2img "雪山风景" --seed 12345
# 完整参数
ai-image text2img "城市夜景" --size 1920x1920 --seed 999 --guidance-scale 3.0 --watermark
```
**常用参数：**
- `--size, -s`: 图片尺寸，如 `1920x1920`(默认: `1920x1920`，最低尺寸：`1920x1920`)
- `--seed`: 随机种子，用于复现相同结果
- `--guidance-scale, -g`: 引导系数，控制生成质量(默认: `2.5`)
- `--watermark / --no-watermark`: 是否添加水印(默认: 不添加)
### 图生图 (img2img)
**注意**: 图生图不支持指定尺寸参数，输出图片尺寸由源图片决定。
```bash
# 基本用法
ai-image img2img "改成爱心形状的泡泡" https://example.com/image.jpg
# 使用随机种子
ai-image img2img "改变颜色为红色" https://example.com/car.jpg --seed 777
# 调整引导系数
ai-image img2img "转为水彩画风格" https://example.com/pic.png --guidance-scale 6.0
# 完整参数
ai-image img2img "添加蓝天白云" https://example.com/photo.png \
--seed 888 --guidance-scale 6.0 --watermark
```
**常用参数：**
- `--seed`: 随机种子，用于复现相同结果
- `--guidance-scale, -g`: 引导系数，控制编辑强度(默认: `5.5`)
- `--watermark / --no-watermark`: 是否添加水印(默认: 不添加)
## 输出格式
### 成功响应
```json
{
"success": true,
"command": "text2img",
"provider": "ark",
"data": {
"model": "doubao-seedream-4-5",
"created": 1754384045,
"data": [
{
"url": "https://ark-content-generation-v2-cn-beijing.tos-cn-beijing.volces.com/..."
}
],
"usage": {
"generated_images": 1,
"output_tokens": 4096,
"total_tokens": 4096
}
}
}
```
### 错误响应
```json
{
"success": false,
"command": "text2img",
"error": "未找到 AIGW API Key",
"hint": "请设置 LANGBASE_TOKEN 或 ARK_API_KEY 环境变量"
}
```
## 故障恢复
命令执行失败时，按以下步骤排查：
1. **命令不存在** (`command not found`): 执行 `bash {baseDir}/scripts/install.sh`
2. **认证失败** (`AUTH_FAILED` 或 `未找到 AIGW API Key`): 执行 `bash {baseDir}/scripts/preflight.sh` 查看诊断。若 `auth_configured: false`，说明 `LANGBASE_TOKEN` 环境变量未注入当前进程，需确认 `~/.openclaw/user.env` 中包含 `LANGBASE_TOKEN`。
3. **网络/API 错误**: 重试一次。若持续失败，执行 preflight 检查连通性。
## 未全局安装时的备选方式
```bash
python3 -m ai_image text2img "查询词"
python3 -m ai_image img2img "修改描述" "https://example.com/image.jpg"
```
## 参考文档
- 完整 CLI 参考（参数、返回结构、错误码）：读取 `references/cli-reference.md`
- 更多高级示例（批量生成、参数调优）：读取 `references/examples.md`
标签
skill
ai
