Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(image-search): recommend keyed providers for quality

hugohe395509c24ed00
diff --git a/.env.example b/.env.example
index 770e97f1..a83319f5 100644
--- a/.env.example
+++ b/.env.example
@@ -133,10 +133,10 @@
# Used by scripts/image_search.py — separate from IMAGE_BACKEND above.
# image_search.py 用,与上面的 IMAGE_BACKEND 互不影响。
#
-# Openverse and Wikimedia work with no key. Pexels and Pixabay are
-# OPTIONAL — set their key only if you want to broaden the provider chain.
-# Openverse 和 Wikimedia 无需 Key。Pexels / Pixabay 可选,仅在希望扩展
-# provider 范围时配置。
+# Openverse and Wikimedia work with no key, but image quality can be uneven.
+# For polished stock-style PPT images, configure Pexels and/or Pixabay.
+# Openverse 和 Wikimedia 无需 Key,但图片质量不稳定。
+# 如需更稳定的商业图库风格 PPT 配图,建议配置 Pexels 和/或 Pixabay。
#
# PEXELS_API_KEY=your-pexels-key # signup: https://www.pexels.com/api/
# PIXABAY_API_KEY=your-pixabay-key # signup: https://pixabay.com/api/docs/
diff --git a/README.md b/README.md
index 6934610a..25920e25 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# PPT Master — AI generates natively editable PPTX from any document
-[![Version](https://img.shields.io/badge/version-v2.3.0-blue.svg)](https://github.com/hugohe3/ppt-master/releases)
+[![Version](https://img.shields.io/badge/version-v2.5.0-blue.svg)](https://github.com/hugohe3/ppt-master/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/hugohe3/ppt-master.svg)](https://github.com/hugohe3/ppt-master/stargazers)
[![AtomGit stars](https://atomgit.com/hugohe3/ppt-master/star/badge.svg)](https://atomgit.com/hugohe3/ppt-master)
@@ -219,7 +219,7 @@ Two paths for non-user images, mixable per row in the same deck:
**A) AI generation** — `image_gen.py`. Copy `.env.example` to `.env`, set `IMAGE_BACKEND` plus the provider's `*_API_KEY` (`OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.), and the pipeline calls it automatically. Run `python3 skills/ppt-master/scripts/image_gen.py --list-backends` for the full backend list. `gpt-image-2` is currently the best default.
-**B) Web image search** — `image_search.py`. **Zero-config**, no API key. Searches openly-licensed images across Openverse and Wikimedia Commons; when `PEXELS_API_KEY` / `PIXABAY_API_KEY` (both free) are configured, the default provider chain also appends Pexels / Pixabay. The default is quality-first: CC0, Public Domain, Pexels / Pixabay no-attribution licenses, CC BY, and CC BY-SA are considered together, and Executor adds a small inline credit whenever the selected image requires attribution. Use `--strict-no-attribution` only when a slide cannot tolerate any credit line. Note: web image search is best treated as a fast fallback. Image quality, resolution, composition, and topic fit depend on the open image sources themselves, so results are usually less polished than user-provided high-resolution assets or AI-generated images. For high-impact covers, product shots, portraits, and branded scenes, prefer source images or AI generation.
+**B) Web image search** — `image_search.py`. **Zero-config works**, but configure `PEXELS_API_KEY` / `PIXABAY_API_KEY` (both free) for higher-quality results. Without keys, search uses Openverse / Wikimedia Commons only; this is useful as a fallback, but image quality can be uneven because many results are ordinary user uploads. With keys, the default provider chain also appends Pexels / Pixabay, which materially improves modern stock photography, people, workplace, lifestyle, and illustration coverage. The default is quality-first: CC0, Public Domain, Pexels / Pixabay no-attribution licenses, CC BY, and CC BY-SA are considered together, and Executor adds a small inline credit whenever the selected image requires attribution. Use `--strict-no-attribution` only when a slide cannot tolerate any credit line. For high-impact covers, product shots, portraits, and branded scenes, prefer this order: user-provided high-resolution assets / AI generation > web search with Pexels / Pixabay keys > zero-config web search.
> Full reference: [`image-generator.md`](./skills/ppt-master/references/image-generator.md) (AI) · [`image-searcher.md`](./skills/ppt-master/references/image-searcher.md) (web).
diff --git a/README_CN.md b/README_CN.md
index ce1409b1..57eb5979 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -1,6 +1,6 @@
# PPT Master — AI 生成原生可编辑 PPTX,支持任意文档输入
-[![Version](https://img.shields.io/badge/version-v2.3.0-blue.svg)](https://github.com/hugohe3/ppt-master/releases)
+[![Version](https://img.shields.io/badge/version-v2.5.0-blue.svg)](https://github.com/hugohe3/ppt-master/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/hugohe3/ppt-master.svg)](https://github.com/hugohe3/ppt-master/stargazers)
[![AtomGit stars](https://atomgit.com/hugohe3/ppt-master/star/badge.svg)](https://atomgit.com/hugohe3/ppt-master)
@@ -223,7 +223,7 @@ AI 全程处理——内容分析、视觉设计、SVG 生成、PPTX 导出。
**A) AI 生图** — `image_gen.py`。`cp .env.example .env`,设置 `IMAGE_BACKEND` 和对应 `*_API_KEY`(`OPENAI_API_KEY`、`GEMINI_API_KEY` 等),流程会自动调用。`python3 skills/ppt-master/scripts/image_gen.py --list-backends` 查看完整后端清单。`gpt-image-2` 目前综合质量最佳。
-**B) 网络图片搜索** — `image_search.py`。**零配置**、无需 API Key。在 Openverse 和 Wikimedia Commons 中搜索开放许可可商用图片;如果配置了 `PEXELS_API_KEY` / `PIXABAY_API_KEY`(都免费申请),默认搜索链会继续追加 Pexels / Pixabay。默认以图片质量和匹配度优先,直接把 CC0、公有领域、Pexels / Pixabay 免署名许可、CC BY、CC BY-SA 一起纳入候选;如果选中的图片需要署名,Executor 会在该幻灯片自动添加小字署名。只有明确不能出现署名时,才使用 `--strict-no-attribution` 限制为免署名图片。注意:网络搜索图片适合作为快速兜底,但画质、尺寸、构图和主题匹配度取决于开放图库本身,整体质量通常不如用户自带高清素材或 AI 生图;对视觉要求高的封面、产品图、人物图和品牌场景,建议优先提供原始图片或使用 AI 生图。
+**B) 网络图片搜索** — `image_search.py`。**零配置**可用,但高质量使用建议配置 `PEXELS_API_KEY` / `PIXABAY_API_KEY`(都免费申请)。不配置时只使用 Openverse / Wikimedia Commons,适合作为兜底,但容易出现普通用户上传、构图随意、清晰度不稳定的图片;配置后默认搜索链会追加 Pexels / Pixabay,现代商业摄影、人物、办公、生活方式和插画类图片质量会明显更稳定。默认以图片质量和匹配度优先,直接把 CC0、公有领域、Pexels / Pixabay 免署名许可、CC BY、CC BY-SA 一起纳入候选;如果选中的图片需要署名,Executor 会在该幻灯片自动添加小字署名。只有明确不能出现署名时,才使用 `--strict-no-attribution` 限制为免署名图片。对视觉要求高的封面、产品图、人物图和品牌场景,优先级建议是:用户自带高清素材 / AI 生图 > 配置 Pexels / Pixabay 的网络搜索 > 零配置网络搜索。
> 完整说明:[`image-generator.md`](./skills/ppt-master/references/image-generator.md)(AI)·[`image-searcher.md`](./skills/ppt-master/references/image-searcher.md)(网络)。
diff --git a/docs/faq.md b/docs/faq.md
index a0861d6b..115bc8d2 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -32,9 +32,9 @@ Yes. PPT Master includes a built-in image generation script that supports multip
## Q: I don't have an image-generation API key — can I still get images?
-Yes — pick "Web-sourced" in the Strategist's Image Usage step. PPT Master ships a zero-config `image_search.py` that searches openly-licensed images across Openverse and Wikimedia Commons (no API key needed). It defaults to CC0 / Public Domain so the deck stays visually clean, and only falls back to CC BY / CC BY-SA when no public-domain match exists — in which case the Executor adds a small inline credit on the affected slide.
+Yes — pick "Web-sourced" in the Strategist's Image Usage step. PPT Master ships a zero-config `image_search.py` that searches openly-licensed images across Openverse and Wikimedia Commons (no API key needed). Zero-config search is a fallback: it works immediately, but quality can be uneven because many results are ordinary user uploads.
-You can mix the two paths in one deck (e.g. AI for hero illustrations, web for team photos). For better contemporary stock photography, set `PEXELS_API_KEY` or `PIXABAY_API_KEY` in `.env` (both are free) and the search will include them automatically.
+For better contemporary stock photography, set `PEXELS_API_KEY` and/or `PIXABAY_API_KEY` in `.env` (both are free). The search will include Pexels / Pixabay automatically, which usually improves people, workplace, lifestyle, product, and illustration images. You can mix paths in one deck (e.g. AI for hero illustrations, web for team photos). If a selected image requires attribution, Executor adds a small inline credit on the affected slide.
## Q: Can I edit the generated presentations?
diff --git a/docs/zh/faq.md b/docs/zh/faq.md
index 5777cb25..db15119f 100644
--- a/docs/zh/faq.md
+++ b/docs/zh/faq.md
@@ -32,9 +32,9 @@ PPT Master 可以在任何能读取文件和执行命令的 AI 编程代理中
## Q: 没有生图 API Key,还能配图吗?
-可以——在策略师的"图片方案"步骤选择"网络图片"。PPT Master 内置了零配置的 `image_search.py`,在 Openverse 和 Wikimedia Commons 中搜索可商用的开放许可图片(无需 API Key)。默认只搜 CC0 / 公有领域,避免幻灯片视觉污染;只有公有领域找不到合适图时才回落到 CC BY / CC BY-SA,并由 Executor 在该幻灯片自动添加就地小字署名。
+可以——在策略师的"图片方案"步骤选择"网络图片"。PPT Master 内置了零配置的 `image_search.py`,在 Openverse 和 Wikimedia Commons 中搜索可商用的开放许可图片(无需 API Key)。零配置搜索适合作为兜底:能直接用,但图片质量不稳定,容易出现普通用户上传、构图随意、清晰度一般的素材。
-两种路径可以在同一份 deck 里混用(比如 hero 图用 AI 生成、团队照片用网络搜索)。如果想要更现代的商业风照片,可在 `.env` 里设置 `PEXELS_API_KEY` 或 `PIXABAY_API_KEY`(都是免费申请),搜索会自动把它们纳入。
+如果想要更现代的商业风照片,建议在 `.env` 里设置 `PEXELS_API_KEY` 和/或 `PIXABAY_API_KEY`(都是免费申请)。搜索会自动纳入 Pexels / Pixabay,人物、办公、生活方式、产品和插画类图片质量通常会明显更稳定。两种路径可以在同一份 deck 里混用(比如 hero 图用 AI 生成、团队照片用网络搜索);如果选中的图片需要署名,Executor 会在该幻灯片自动添加就地小字署名。
## Q: 生成的 PPT 可以编辑吗?
diff --git a/skills/ppt-master/references/image-searcher.md b/skills/ppt-master/references/image-searcher.md
index 214cac54..66d67221 100644
--- a/skills/ppt-master/references/image-searcher.md
+++ b/skills/ppt-master/references/image-searcher.md
@@ -47,10 +47,10 @@ Strict: provider chain, license filter = cc0,pdm,pexels,pixabay
| Provider | Config | Strength |
|---|---|---|
-| Openverse | zero-config | aggregator: Wikimedia + Flickr + museums + rawpixel |
+| Openverse | zero-config | fallback aggregator: Wikimedia + Flickr + museums + rawpixel |
| Wikimedia Commons | zero-config | educational, scientific, geographic, historical |
-| Pexels | `PEXELS_API_KEY` (free, [signup](https://www.pexels.com/api/)) | modern stock photography, people, scenes |
-| Pixabay | `PIXABAY_API_KEY` (free, [signup](https://pixabay.com/api/docs/)) | broad type coverage including illustrations |
+| Pexels | recommended: `PEXELS_API_KEY` (free, [signup](https://www.pexels.com/api/)) | modern stock photography, people, workplace, lifestyle |
+| Pixabay | recommended: `PIXABAY_API_KEY` (free, [signup](https://pixabay.com/api/docs/)) | broad type coverage including photos and illustrations |
Default chain (when `--provider` is unset):
@@ -60,6 +60,8 @@ openverse → wikimedia → pexels (if PEXELS_API_KEY set) → pixabay (if PIXAB
Keyed providers without an API key are silently skipped — not an error.
+**Validation**: For polished visual decks, configure at least one keyed provider before using `Acquire Via: web`.
+
---
## 4. Intent → Query Translation
diff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.md
index 105e9932..1150b6d1 100644
--- a/skills/ppt-master/scripts/docs/image.md
+++ b/skills/ppt-master/scripts/docs/image.md
@@ -94,16 +94,16 @@ python3 scripts/image_search.py "offshore wind farm" \
--orientation landscape -o projects/demo/images
```
-Providers (Openverse and Wikimedia work with no key; Pexels and Pixabay are optional):
+Providers (Openverse and Wikimedia work with no key; configure Pexels / Pixabay for better stock-photo quality):
| Provider | Config | Strength |
|---|---|---|
-| `openverse` | zero-config | aggregator: Wikimedia + Flickr + museums + rawpixel |
+| `openverse` | zero-config | fallback aggregator: Wikimedia + Flickr + museums + rawpixel |
| `wikimedia` | zero-config | educational, scientific, geographic, historical |
-| `pexels` | needs `PEXELS_API_KEY` | modern stock photography |
-| `pixabay` | needs `PIXABAY_API_KEY` | broad type coverage including illustrations |
+| `pexels` | recommended: `PEXELS_API_KEY` | modern stock photography, people, workplace, lifestyle |
+| `pixabay` | recommended: `PIXABAY_API_KEY` | broad type coverage including photos and illustrations |
-Default search chain (when `--provider` is unset): zero-config providers first, then keyed providers whose API key is set in the environment. Keyed providers without a key are silently skipped.
+Default search chain (when `--provider` is unset): zero-config providers first, then keyed providers whose API key is set in the environment. Keyed providers without a key are silently skipped. For polished visual decks, configure at least one keyed provider.
Query guidance: