儿童绘本生成器

一、概述

儿童绘本生成器是一个基于百度文心大模型图像生成模型能力的 OpenClaw Skill，封装了 Baidu AI Studio 的 ERNIE-Image-Turbo API，通过提炼儿童故事核心画面，通过文本生成图像（Text-to-Image）核心能力生成儿童绘本。Skill 通过 Python 脚本调用 OpenAI 兼容接口，实现与百度文心图像生成服务的无缝对接。

1.1 设计目标

1.2 核心能力矩阵

二、架构设计

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 实现命令行参数解析，设计为全显式传参，无交互式输入：

设计决策：

• --filename 为必填项而非自动生成：赋予用户完全的文件命名控制权
• --resolution 使用 choices 限制：避免传入 API 不支持的分辨率导致报错
• 无 --output-dir 参数：通过 --filename 中的路径信息直接推导

3.2 API Key 解析模块

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

多环境变量兼容设计：

安全考量：

• 命令行传参 --api-key 会暴露在进程列表中（ps 可见），建议仅在临时场景使用
• 生产环境推荐设置环境变量，避免密钥泄露

3.3 OpenAI 客户端封装

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 调用与响应处理

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 支持的分辨率列表

五、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 应检查：

#  API Key 是否可用
test -n "$ERNIE-Image_API_KEY" || echo "API Key 未设置"

6.2 常见错误与解决方案

6.3 调试模式

当前脚本无独立 --verbose 参数，调试时可：

1. 检查命令行参数是否正确传递
2. 验证环境变量是否加载到当前进程
3. 手动测试 API 连通性：curl https://aistudio.baidu.com/llm/lmapi/v3

七、安全设计

7.1 密钥管理

7.2 输入安全

• Prompt 内容直接传递给百度 API，无本地过滤
• 依赖百度服务端的内容安全策略
• 敏感/违规内容会被 API 拒绝并返回错误

7.3 输出安全

• 生成的图像保存到用户指定路径
• 脚本自动创建父目录（mkdir(parents=True)）
• 无文件覆盖确认，同名文件直接覆盖

八、扩展性设计

8.1 当前限制

8.2 与其他 Skill 的协作

九、使用示例

9.1 基础生成

python scripts/generate_image.py \
  --prompt "A serene Japanese garden with cherry blossoms" \
  --filename "japanese-garden.png" \
  --resolution 1024x1024

9.2 手机壁纸（竖屏）

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"

十、版本历史

十一、参考资源

• 百度 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/ernieimage
• https://aistudio.baidu.com/modelsdetail/46030/intro