back
loading skill details...
基于百度ERNIE-Image-Turbo模型，将儿童故事核心画面文本转为指定分辨率的高质量绘本图像并保存为PNG文件。
# 儿童绘本生成器
## 一、概述
儿童绘本生成器是一个基于百度文心大模型图像生成模型能力的 OpenClaw Skill，封装了 Baidu AI Studio 的 `ERNIE-Image-Turbo` API，通过提炼儿童故事核心画面，通过文本生成图像（Text-to-Image）核心能力生成儿童绘本。Skill 通过 Python 脚本调用 OpenAI 兼容接口，实现与百度文心图像生成服务的无缝对接。
### 1.1 设计目标
| 目标 | 说明 |
|------|------|
| **易用性** | 单条命令即可完成图像生成，无需手动处理 API 调用细节 |
| **灵活性** | 支持多种分辨率、支持命令行传参和环境变量配置 API Key |
| **分辨率** | 1024x1024/1376x768/1264x848/ 1200x896/896x1200/848x1264/768x1376 |
| **跨平台** | 基于 Python 3.7+ 和 `openai` 库，兼容 Windows/macOS/Linux |
### 1.2 核心能力矩阵
| 能力 | 支持状态 | 备注 |
|------|---------|------|
| 文本生成图像 | ✅ | 核心功能，支持详细 prompt |
| 多分辨率输出 | ✅ | 7 种预设分辨率 |
| 中文文字渲染 | ✅ | 可在 prompt 中指定中文文字内容 |
| 批量生成 | ❌ | 当前版本单图生成 |
| 风格迁移 | ⚠️ | 依赖 prompt 描述，无独立风格参数 |
---
## 二、架构设计
### 2.1 组件关系图
```
输入儿童故事，或者儿童故事主题
↓
通过大模型生成故事关键画面prompt
↓
调用ERNIE-Image 生成绘本图
```
### 2.2 数据流
```
用户输入故事内容，或者故事主题
│
▼
生成故事多个关键画面Prompt
│
▼
[generate_image.py]
│
├── 1. 解析命令行参数 (argparse)
│ ├── --prompt: 图像描述文本
│ ├── --filename: 输出文件路径
│ ├── --resolution: 输出分辨率
│ └── --api-key: API 密钥（可选）
│
├── 2. 解析 API Key（优先级递减）
│ ├── ① --api-key 参数
│ ├── ② ERNIE-Image_API_KEY 环境变量
│ ├── ③ ERNIE_Image_API_KEY 环境变量
│
├── 3. 初始化 OpenAI 客户端
│ ├── api_key = 解析结果
│ ├── base_url = "https://aistudio.baidu.com/llm/lmapi/v3"
│ └── 模型 = "ERNIE-Image-Turbo"
│
├── 4. 调用 API
│ ├── POST /images/generations
│ ├── payload: {model, prompt, size, response_format: "b64_json"}
│ └── 接收 base64 编码图像数据
│
└── 5. 保存文件
├── 创建输出目录（如果不存在）
├── base64 解码 → PNG 字节流
└── 写入磁盘
```
---
## 三、核心模块详解
### 3.1 参数解析模块
**文件:** `scripts/generate_image.py`
使用 Python 标准库 `argparse` 实现命令行参数解析，设计为**全显式传参**，无交互式输入：
| 参数 | 简写 | 必填 | 类型 | 默认值 | 说明 |
|------|------|------|------|--------|------|
| `--prompt` | `-p` | ✅ | string | - | 图像描述文本 |
| `--filename` | `-f` | ✅ | string | - | 输出文件路径（支持绝对/相对路径） |
| `--resolution` | `-r` | ❌ | choice | `1024x1024` | 输出分辨率 |
| `--api-key` | `-k` | ❌ | string | `None` | API 密钥（覆盖环境变量） |
**设计决策：**
- `--filename` 为必填项而非自动生成：赋予用户完全的文件命名控制权
- `--resolution` 使用 `choices` 限制：避免传入 API 不支持的分辨率导致报错
- 无 `--output-dir` 参数：通过 `--filename` 中的路径信息直接推导
### 3.2 API Key 解析模块
```python
def get_api_key(provided_key: str | None) -> str | None:
"""Get API key from argument first, then environment."""
if provided_key:
return provided_key
for key in ["ERNIE-Image_API_KEY", "ERNIE_Image_API_KEY", "BAIDU_API_KEY"]:
value = os.environ.get(key)
if value:
return value
return None
```
**多环境变量兼容设计：**
| 环境变量名 | 优先级 | 设计原因 |
|-----------|--------|---------|
| `ERNIE-Image_API_KEY` | 1（最高） | 官方推荐命名，与 Skill 名称一致 |
| `ERNIE_Image_API_KEY` | 2 | 兼容下划线命名（部分系统不支持连字符） |
**安全考量：**
- 命令行传参 `--api-key` 会暴露在进程列表中（`ps` 可见），建议仅在临时场景使用
- 生产环境推荐设置环境变量，避免密钥泄露
### 3.3 OpenAI 客户端封装
```python
client = OpenAI(
api_key=api_key,
base_url="https://aistudio.baidu.com/llm/lmapi/v3"
)
```
**关键设计：**
- 使用 `openai` Python SDK（非百度原生 SDK），利用其 **OpenAI 兼容接口** 能力
- `base_url` 指向百度 AI Studio 的 OpenAI 兼容端点
- 模型名称硬编码为 `"ERNIE-Image-Turbo"`，这是当前百度文心图像生成的默认模型
### 3.4 API 调用与响应处理
```python
img = client.images.generate(
model="ERNIE-Image-Turbo",
prompt=contents,
size=output_resolution,
response_format="b64_json",
)
# 解码并保存
image_bytes = base64.b64decode(img.data[0].b64_json)
with open(output_path, "wb") as f:
f.write(image_bytes)
```
**响应格式：**
- `response_format="b64_json"`：返回 base64 编码的 PNG 图像数据
- 不返回 URL（避免临时链接失效问题）
- 直接内存解码写入磁盘，无中间临时文件
---
## 四、分辨率系统设计
### 4.1 支持的分辨率列表
| 分辨率 | 宽高比 | 适用场景 | 备注 |
|--------|--------|---------|------|
| `1024x1024` | 1:1 | 头像、方形插画 | 默认分辨率 |
| `1376x768` | 16:9 | 横屏壁纸、视频封面 | 宽屏 |
| `1264x848` | ~3:2 | 照片比例 | 接近单反相机比例 |
| `1200x896` | ~4:3 | 传统屏幕比例 | 兼容旧设备 |
| `896x1200` | ~3:4 | 竖屏照片 | 类似手机竖拍 |
| `848x1264` | ~2:3 | 竖屏壁纸 | 接近手机屏幕 |
| `768x1376` | ~9:16 | 手机竖屏壁纸 | 全面屏手机适配 |
## 五、Prompt 工程指南
### 5.1 Prompt 传递策略
Skill 采用**透传优先**策略：
- 默认将用户描述原样传递给 API
- 仅在用户描述明显不足时进行补充优化
### 5.2 高命中率 Prompt 模板
```
Create an image of: <主体描述>
Style: <艺术风格>
Composition: <构图/镜头>
Lighting: <光影效果>
Background: <背景描述>
Color palette: <色彩方案>
Avoid: <需要避免的内容>
```
### 5.3 中文文字渲染技巧
ERNIE-Image 支持在图像中渲染中文文字，关键要点：
1. **明确指定文字内容**：在 prompt 中直接写出要显示的中文
2. **指定字体风格**：如「行书」「楷书」「宋体」等
3. **指定位置和样式**：如「顶部居中」「白色字体带金色光晕」
4. **控制大小**：避免文字过大遮挡主体或过小无法辨认
**示例：**
```
In the upper portion of the image, elegant vertical Chinese calligraphy
text arranged in two lines: first line '山再高，往上攀，总能登顶；'
and second line '路再长，走下去，定能到达。' — the text is rendered
in a refined semi-cursive Chinese calligraphy style (行书), white color
with subtle golden glow effect, positioned in the upper third area.
```
---
## 六、错误处理与故障排查
### 6.1 预检清单（Preflight）
在调用脚本前，Agent 应检查：
```bash
# API Key 是否可用
test -n "$ERNIE-Image_API_KEY" || echo "API Key 未设置"
```
### 6.2 常见错误与解决方案
| 错误信息 | 原因 | 解决方案 |
|---------|------|---------|
| `Error: No API key provided.` | API Key 未提供 | 设置环境变量或传 `--api-key` |
| 401/403 权限错误 | Key 无效或过期 | 更换有效 Key |
| 配额超限错误 | 调用次数达到上限 | 等待配额重置或升级账户 |
| 图像生成失败 | Prompt 包含敏感内容 | 修改 prompt 避免违规描述 |
### 6.3 调试模式
当前脚本无独立 `--verbose` 参数，调试时可：
1. 检查命令行参数是否正确传递
2. 验证环境变量是否加载到当前进程
3. 手动测试 API 连通性：`curl https://aistudio.baidu.com/llm/lmapi/v3`
---
## 七、安全设计
### 7.1 密钥管理
| 场景 | 风险等级 | 建议做法 |
|------|---------|---------|
| 命令行传参 `--api-key` | ⚠️ 中 | 临时使用，避免在共享环境使用 |
| 用户级环境变量 | ✅ 低 | 推荐方案，仅当前用户可见 |
| 系统级环境变量 | ⚠️ 中 | 多用户共享，注意权限控制 |
| 硬编码在脚本中 | ❌ 高 | 严禁，会泄露到版本控制 |
### 7.2 输入安全
- Prompt 内容直接传递给百度 API，**无本地过滤**
- 依赖百度服务端的内容安全策略
- 敏感/违规内容会被 API 拒绝并返回错误
### 7.3 输出安全
- 生成的图像保存到用户指定路径
- 脚本自动创建父目录（`mkdir(parents=True)`）
- 无文件覆盖确认，同名文件直接覆盖
---
## 八、扩展性设计
### 8.1 当前限制
| 限制项 | 说明 | 未来改进方向 |
|--------|------|------------|
| 单图生成 | 每次调用仅生成一张 | 支持 `--batch` 批量生成 |
| 无回调机制 | 生成完成后仅打印路径 | 支持 webhook/消息通知 |
| 无进度反馈 | 长时间生成无中间状态 | 添加进度条或流式输出 |
| 固定模型 | 仅支持 ERNIE-Image-Turbo | 支持模型选择参数 |
| 无元数据 | 输出 PNG 无 EXIF 信息 | 嵌入生成参数到图像元数据 |
### 8.2 与其他 Skill 的协作
| 协作场景 | 方式 | 示例 |
|---------|------|------|
| 图像 → 文档 | 插入 docx/pptx | 使用 `docx`/`pptx` Skill 将生成图像插入文档 |
| 图像 → 云存储 | 上传备份 | 使用 `cloud-upload-backup` Skill 上传生成图像 |
| 图像 → 展示 | 浏览器查看 | 使用 `xbrowser` Skill 打开生成图像预览 |
| 批量 → 自动化 | 定时任务 | 使用 `qclaw-cron-skill` 定时生成图像 |
---
## 九、使用示例
### 9.1 基础生成
```bash
python scripts/generate_image.py \
--prompt "A serene Japanese garden with cherry blossoms" \
--filename "japanese-garden.png" \
--resolution 1024x1024
```
### 9.2 手机壁纸（竖屏）
```bash
python scripts/generate_image.py \
--prompt "A mystical dark fantasy meadow with a glowing-eyed kitten..." \
--filename "wallpaper.png" \
--resolution 768x1376 \
--api-key "your-api-key-here"
```
---
## 十、版本历史
| 版本 | 日期 | 变更内容 |
|------|------|---------|
| 1.0.1 | 2026-04-25 | 初始版本，支持文生图、图生图、7种分辨率 |
---
## 十一、参考资源
- **百度 AI Studio:** https://aistudio.baidu.com
- **OpenAI Python SDK:** https://github.com/openai/openai-python
- [https://aistudio.baidu.com/blog/detail/794723628346373](https://aistudio.baidu.com/blog/detail/794723628346373)
- [https://aistudio.baidu.com/ernieimage](https://aistudio.baidu.com/ernieimage)
- [https://aistudio.baidu.com/modelsdetail/46030/intro](https://aistudio.baidu.com/modelsdetail/46030/intro)
---
don't have the plugin yet? install it then click "run inline in claude" again.