mohitagw15856/thumbnail-creator

缩略图创建器技能（通过 Gemini）

在 Claude Code 内作为图像生成代理，为文章和新闻通讯生成缩略图候选项。这个技能让 Claude 完成完整循环：阅读内容、提出构图、编写量身定制的提示、调用 Gemini API、评估输出，并返回带有简要理由的排序结果，而无需在工具之间切换并逐个提示 Gemini 的 Web 界面。

输出是可直接投入生产的缩略图候选项，你可以直接放入你的 CMS、新闻通讯工具或社交媒体调度程序。

---

前提条件

在技能可以生成图像之前，必须具备以下两个条件：

1. Gemini API 密钥

从 Google AI Studio 免费获取密钥。

将其设置为环境变量：

export GEMINI_API_KEY=<your-key>

要在不同会话之间持久化，请将其添加到你的 shell 配置文件（~/.zshrc 或 ~/.bashrc）：

echo 'export GEMINI_API_KEY=<your-key>' >> ~/.zshrc
source ~/.zshrc

验证是否已设置：

echo $GEMINI_API_KEY

2. generate_image.py 脚本

此脚本必须存在于项目根目录下的 ./generate_image.py。下文“脚本模板”部分提供了完整的模板。Claude 会检查该文件，如果缺失，会主动提供创建。

Python 依赖项：

pip install google-generativeai Pillow requests

或者使用 uv：

uv pip install google-generativeai Pillow requests

---

必需的输入

如果未提供，Claude 会询问以下信息：

输入	必需	备注
文章内容或 URL	是	粘贴文章全文，或提供要获取的 URL。用于提取构图所需的主题、吸引点和关键主张。
品牌颜色	推荐	十六进制代码或描述性名称。例如 #1A1A2E（深蓝色）、#E94560（珊瑚色）。如果未提供，Claude 使用干净的中性默认值。
字体/文字样式	推荐	例如“粗体无衬线”、“编辑衬线”、“Neue Haas Grotesk”。用于提示中指导文字处理。
样式参考描述	推荐	例如“扁平插画、极简、像 Stripe 的营销网站”或“照片写实、深色背景、高对比度”。也可以提供样式图像 URL。
输出尺寸	否	默认为 1792x1024（横向，标准文章缩略图）。选项：1024x1024（正方形）、1024x1792（纵向/移动端）。
候选项数量	否	默认为 4。最小 1，最大 8（API 限制和成本）。
文章标题（如果与 H1 不同）	否	用作图像提示中的主要文本元素。
候选项选择	否	在提出构图后，Claude 会询问要生成哪些。用户可以回复“全部”或按编号选择。

---

输出结构

阶段 1 — 构图建议（文本，在任何 API 调用之前）

Claude 会提出 3-4 个构图概念供用户批准。格式如下：

“[文章标题]”的构图概念

1. 大胆声明
   布局：    满版深色背景，大号白色标题居中，
             下方用品牌颜色显示单个重点数据点（例如“3 倍快”）
   风格：    权威感强，新闻通讯风格
   最适合：  LinkedIn、Substack 页眉
   理由：文章的核心主张（“X 比 Y 快 3 倍”）足够具体，
           可以作为视觉锚点——读者会因数据而停留。

2. 概念对象
   布局：    中心对象插画（例如，为关于时间浪费的文章画一个坏掉的时钟），
             标题在上三分之一处，最小纹理背景
   风格：    社论风格、Medium 风格
   最适合：  博客页眉、Medium 封面、邮件预标题
   理由：为艺术总监提供视觉隐喻的灵活性；适用于各种尺寸。

3. 对比分割
   布局：    左半部分品牌颜色，右半部分白色或图像，
             标题在颜色侧，补充副文本在白色侧
   风格：    干净、专业、初创品牌感
   最适合：  新闻通讯、LinkedIn 轮播第一张幻灯片
   理由：分割布局在新闻通讯 A/B 测试中表现稳定；
             文本在小尺寸下可读。

4. 仅排版
   布局：    无插图，超大标题处理，
             作者名以小号大写字母在底部，细线分隔符
   风格：    高端、自信、社论风格
   最适合：  Substack、Ghost、高密度邮件列表
   理由：当品牌拥有强大的字体身份时效果最佳。
             速度最快。

要生成哪些构图？（回复数字，例如“1, 3”或“全部”）

阶段 2 — 生成的图像文件

生成后，Claude 将文件保存到 ./thumbnails/[article-slug]/：

thumbnails/
└── article-slug-from-title/
    ├── candidate_01_bold_claim.png
    ├── candidate_02_conceptual_object.png
    ├── candidate_03_contrast_split.png
    ├── candidate_04_typographic.png
    └── evaluation_report.md

阶段 3 — 评估摘要表

Claude 通过计算机视觉评估每个返回的图像，并生成：

缩略图评估 — “[文章标题]”
生成日期：2026-05-27  |  模型：Gemini Imagen  |  尺寸：1792x1024

| # | 候选项 | 构图 | 品牌适配度 /10 | 文本可读性 /10 | 推荐 |
|---|---|---|---|---|---|
| 1 | candidate_01_bold_claim.png | 大胆声明 | 9 | 8 | ★ 首选 — 强大的数据锚点，品牌颜色正确，200px 宽度下标题可读 |
| 2 | candidate_02_conceptual_object.png | 概念对象 | 7 | 9 | 良好的备选 — 可读性强，干净，但插画风格与品牌略有偏差 |
| 3 | candidate_03_contrast_split.png | 对比分割 | 8 | 7 | 全尺寸下效果良好；发布前请在缩略图尺寸下测试 — 右侧文本空间紧张 |
| 4 | candidate_04_typographic.png | 仅排版 | 9 | 10 | 邮件中最强 — 零品牌偏差风险，完全基于文本 |

推荐用于 Web：          candidate_01_bold_claim.png
推荐用于邮件/移动端： candidate_04_typographic.png
推荐用于社交：         candidate_03_contrast_split.png

文件已保存至：./thumbnails/article-slug-from-title/

---

Claude 应如何执行此技能

步骤 1 — 接收并分析文章

接受文章内容（粘贴的文本或 URL）。

如果提供了 URL，获取页面并提取：

• H1 标题
• 前 3-5 个段落（吸引点、核心主张和关键点）
• 任何值得注意的统计数据或命名框架
• 作者姓名（用于仅排版构图）

如果粘贴了文本，直接阅读。重点关注：

• 吸引点： 开篇的主张或张力是什么？
• 核心论点： 文章论证或教导的一件事是什么？
• 关键细节： 任何可以锚定视觉元素的数字、命名框架或具体示例
• 语调： 这是正式/权威、对话/平易、挑衅/挑战性的？

在提出构图建议之前，内部总结这些发现——建议应针对这篇特定文章，而非通用性的。

步骤 2 — 收集品牌规格

如果未提供，向用户询问品牌规格：

要生成符合品牌的缩略图，我需要一些详细信息：

1. 品牌颜色（十六进制代码或描述）——例如 #1A1A2E, #E94560
2. 字体样式偏好——例如“粗体无衬线”、“编辑衬线”、“几何”
3. 视觉风格——例如“扁平极简”、“照片写实”、“插画”、“仅排版”
4. 任何样式参考——描述一个你想要匹配其美学的品牌或出版物，
   或者分享一个图像 URL

如果你还没有品牌规格，请说“使用干净默认值”，
我将使用专业的深色背景上白色文字的社论风格。

如果用户说“使用干净默认值”，则应用：

• 背景：#FFFFFF 或 #0F0F0F（深色模式默认值）
• 强调色：#2563EB（蓝色）
• 字体样式：粗体几何无衬线
• 风格：极简扁平，无纹理，高对比度

步骤 3 — 提出构图概念

根据文章语调和内容，编写 3-4 个构图概念。每个概念必须：

• 有一个名称（简短、易记的标签）
• 精确描述布局（标题位置、什么视觉元素锚定、背景处理）
• 注明风格及其最适合的用例
• 包含一个理由句，解释为什么这个构图适合这篇特定文章

在提出概念后，询问要生成哪些。在做出任何 API 调用之前等待用户确认。

步骤 4 — 编写 Gemini 图像生成提示

对于每个选定的构图，编写一个详细的图像生成提示。图像生成提示遵循与文本提示不同的语法——它们是描述性的，而非指令性的。

提示结构：

[主题/构图] + [风格] + [调色板] + [风格/光照] +
[文本处理（如果有）] + [要避免的内容]

大胆声明构图示例提示：

文章缩略图图像。大号粗体白色无衬线标题文字显示“比传统方法快 3 倍”，
居中放置在深海军蓝背景上（#1A1A2E）。下方用珊瑚色强调文字（#E94560）显示副标题。
极简扁平设计，无渐变、无库存照片元素、无人像。干净专业的社论风格，
高对比度，新闻通讯页眉格式，16:9 横向方向。构图基于排版——文本是英雄，
无需插画。避免：剪贴画、阴影、低对比度、拥挤布局。

提示规则：

• 提供品牌颜色时，包含确切的十六进制颜色
• 指定要在图像中出现的确切标题文字
• 明确命名样式（“扁平设计”、“社论”、“照片写实”）——Gemini 对样式类别名称反应良好
• 在末尾添加否定提示（“避免：...”）以减少与品牌风格的偏差
• 保持提示在 300 字以内——较长的提示并不总能可靠地产生更好的输出

步骤 5 — 检查前提条件并运行生成脚本

在调用 API 之前，验证：

# 检查 API 密钥是否已设置
echo $GEMINI_API_KEY

# 检查脚本是否存在
ls -la ./generate_image.py

# 检查依赖项
python3 -c "import google.generativeai, PIL, requests; print('Dependencies OK')"

如果脚本缺失，请主动提出使用下文“脚本模板”部分中的模板创建它。

为每个提示运行生成脚本：

python3 generate_image.py \
  --prompt "your full prompt here" \
  --output "./thumbnails/article-slug/candidate_01_bold_claim.png" \
  --width 1792 \
  --height 1024

或者通过批处理配置文件传递所有提示：

python3 generate_image.py --config ./thumbnails/article-slug/prompts.json

步骤 6 — 评估生成的图像

在每张图像保存后，使用计算机视觉进行检查。在两个维度上评估：

品牌适配度（分数/10）：

• 品牌颜色是否正确？（1-2 分每项）
• 样式是否与请求的美学匹配？（2 分）
• 布局是否与构图简报一致？（2 分）
• 是否存在任何 AI 伪影、扭曲文本或意外元素？（-1 分每个问题）

文本可读性（分数/10）：

• 标题文字在全分辨率下是否可读？（3 分）
• 图像缩小到 300px 宽（缩略图尺寸）时，标题文字是否可读？（3 分）
• 文本和背景之间是否有足够的对比度？（2 分）
• 文本是否放置在安全区域内（不会在边缘被裁剪）？（2 分）

注意：Gemini Imagen 有时会渲染带有拼写错误或扭曲字母形式的文本。如果发生这种情况，请在评估中注明，并建议用户在 Canva 或 Figma 中手动添加文本叠加。

步骤 7 — 生成评估报告

编写评估摘要表（格式见输出结构部分）并将其保存为输出文件夹中的 evaluation_report.md。

包括：

• 每个分数的单行理由
• 按用例（Web、邮件/移动端、社交）的首选推荐
• 任何生产注意事项（例如“candidate_02 上的文本渲染不完美——请手动叠加文本”）
• 使用的完整提示，以便用户如果需要可以直接在 AI Studio 中进行迭代

步骤 8 — 提供迭代

在交付候选项后，提供一次迭代轮次：

要我迭代其中任何一个吗？

选项：
- 调整特定候选项的颜色或样式
- 尝试不同的构图概念
- 更改标题文字
- 使用不同的 Gemini 参数（不同的温度/种子）重新运行
- 生成首选方案的更多变体

只需告诉我需要更改什么。

---

脚本模板

如果 generate_image.py 不存在，Claude 应主动提供编写此文件。这是要使用的规范模板。

#!/usr/bin/env python3
"""
generate_image.py — 用于缩略图创建器技能的 Gemini Imagen 封装。

用法：
    python3 generate_image.py --prompt "..." --output "./out.png" [--width 1792] [--height 1024]
    python3 generate_image.py --config ./prompts.json

配置文件 JSON 格式：
    [
      {
        "prompt": "...",
        "output": "./thumbnails/slug/candidate_01.png",
        "width": 1792,
        "height": 1024
      }
    ]

要求：
    pip install google-generativeai Pillow
"""

import os
import sys
import json
import argparse
import base64
from pathlib import Path

try:
    import google.generativeai as genai
    from google.generativeai import types as genai_types
except ImportError:
    print("ERROR: 未安装 google-generativeai。运行：pip install google-generativeai")
    sys.exit(1)

try:
    from PIL import Image
    import io
except ImportError:
    print("ERROR: 未安装 Pillow。运行：pip install Pillow")
    sys.exit(1)


def get_api_key() -> str:
    key = os.environ.get("GEMINI_API_KEY", "")
    if not key:
        print("ERROR: 未设置 GEMINI_API_KEY 环境变量。")
        print("在以下位置获取密钥：https://aistudio.google.com/app/apikey")
        print("然后运行：export GEMINI_API_KEY=<your-key>")
        sys.exit(1)
    return key


def generate_image(
    prompt: str,
    output_path: str,
    width: int = 1792,
    height: int = 1024,
) -> bool:
    """
    调用 Gemini Imagen 生成单个图像并保存到 output_path。
    返回 True 表示成功，False 表示失败。
    """
    try:
        genai.configure(api_key=get_api_key())
        model = genai.GenerativeModel('imagen-3.0-generate-002')
        response = model.generate_content(
            f"Generate a {width}x{height} image: {prompt}",
            generation_config=genai.types.GenerationConfig(
                temperature=1.0,
            ),
        )
        if not response.candidates:
            print(f"WARNING: No candidates returned for prompt:\n  {prompt[:80]}...")
            return False
    
        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
        
        for i, candidate in enumerate(response.candidates):
            img_data = None
            if candidate.content.parts:
                for part in candidate.content.parts:
                    if part.inline_data and part.inline_data.mime_type.startswith('image/'):
                        img_data = part.inline_data.data
                        break
            if img_data:
                img = Image.open(io.BytesIO(img_data))
                img.save(output_path)
                print(f"Saved: {output_path}")
                return True
            else:
                print(f"WARNING: Candidate {i+1} returned no image data.")
        return False
    except Exception as e:
        print(f"ERROR during generation: {e}")
        return False


def generate_batch_from_config(config_path: str) -> None:
    """
    从 JSON 配置文件读取一系列生成任务并依次执行。
    """
    with open(config_path, "r") as f:
        tasks = json.load(f)
    
    success_count = 0
    for i, task in enumerate(tasks):
        prompt = task.get("prompt", "")
        output = task.get("output", f"./out_{i}.png")
        width = task.get("width", 1792)
        height = task.get("height", 1024)
        if generate_image(prompt, output, width, height):
            success_count += 1
        else:
            print(f"Task {i+1} failed for: {output}")
    
    print(f"Batch complete: {success_count}/{len(tasks)} images generated successfully.")


def main():
    parser = argparse.ArgumentParser(description="Thumbnail Creator via Gemini Imagen")
    parser.add_argument("--prompt", type=str, help="Image generation prompt")
    parser.add_argument("--output", type=str, help="Output file path")
    parser.add_argument("--width", type=int, default=1792, help="Image width")
    parser.add_argument("--height", type=int, default=1024, help="Image height")
    parser.add_argument("--config", type=str, help="JSON config file for batch generation")
    args = parser.parse_args()
    
    if args.config:
        generate_batch_from_config(args.config)
        return
    
    if not args.prompt or not args.output:
        print("Usage: python3 generate_image.py --prompt \"...\" --output \"./out.png\"")
        print("       python3 generate_image.py --config ./prompts.json")
        sys.exit(1)
    
    generate_image(args.prompt, args.output, args.width, args.height)


if __name__ == "__main__":
    main()

---

常见问题

Gemini Imagen 会渲染可用的文本吗？

有时会，但并不可靠。Imagen 3 可以在图像中渲染短文本（标题、徽标），但长句子或小字经常包含伪影。在生产中，许多团队使用 Imagen 生成不含文本的底板，然后在照片编辑软件中添加标题叠加。评估报告会指出何时需要手动叠加文本。

我需要提供文章吗？

是的——维护此技能的首轮提示会要求提供文章内容。粘贴全文（大约 1000 字）会产生比仅仅标题更聚焦的输出。如果无法获取整篇文章，至少提供前几个段落和中心论点。

可以用我自己的 API 密钥吗？

是的。所有调用都使用你自己的 GEMINI_API_KEY。该技能不共享或记录你的密钥。密钥设置和 Python 依赖项列在前提条件中。

我需要 Python 吗？

是的——精简的生成包装器（generate_image.py）是必备脚本。Claude 可以在桌面上创建它，但你的系统需要 Python 3.9+ 和 pip install google-generativeai。

图像存储在本地还是云端？

仅本地。所有文件都保存到项目目录中的 ./thumbnails/。不会将内容或图像上传到外部服务（除了直接向 Gemini API 发送生成提示）。

这适用于 Cursor 吗？

此技能是为 Claude Code 编写的（使用 Claude 的计算机视觉和会话工作流）。虽然在 Cursor 或 Codex 中可能有部分功能，但计算机视觉评估和迭代对话体验是 Claude Code 独有的。