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.exampleindex 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.mdindex 6934610a..25920e25 100644--- a/README.md+++ b/README.md@@ -1,6 +1,6 @@# PPT Master — AI generates natively editable PPTX from any document-[](https://github.com/hugohe3/ppt-master/releases)+[](https://github.com/hugohe3/ppt-master/releases)[](https://opensource.org/licenses/MIT)[](https://github.com/hugohe3/ppt-master/stargazers)[](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.mdindex ce1409b1..57eb5979 100644--- a/README_CN.md+++ b/README_CN.md@@ -1,6 +1,6 @@# PPT Master — AI 生成原生可编辑 PPTX,支持任意文档输入-[](https://github.com/hugohe3/ppt-master/releases)+[](https://github.com/hugohe3/ppt-master/releases)[](https://opensource.org/licenses/MIT)[](https://github.com/hugohe3/ppt-master/stargazers)[](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.mdindex 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.mdindex 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.mdindex 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 PIXABKeyed 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 Translationdiff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.mdindex 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: