mirror of
https://github.com/ningzimu/codex-ppt-skill.git
synced 2026-09-14 20:06:52 +08:00
feat: support GPT Image 2.5 models and output options (#101)
* feat: support GPT Image 2.5 models and output options * docs: link GPT Image 2.5 changes to PR 101
This commit is contained in:
ningzimu
@@ -4,6 +4,11 @@ Release notes are generated from this file. Keep changelog entries in English.
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Improvements
|
||||
|
||||
- Default image requests to GPT Image 2.5 Flare, support Sunburst, xhigh/max quality and transparent PNG/WebP, and retain legacy model validation. (#101)
|
||||
- Refresh image backend guidance across all languages without claiming a fixed model for built-in tools. (#101)
|
||||
|
||||
### Documentation
|
||||
|
||||
- Add Codia NoteSlide sponsor cards and links across Chinese, English, and Korean READMEs and documentation homepages. (#100)
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
[](https://ningzimu.github.io/codex-ppt-skill/#/) [](https://t.me/CodexPPT) [](https://clawhub.ai/ningzimu/codex-ppt) [](https://app.clawmama.run/skills/5lak48/hermes?utm_source=github&utm_medium=issue&utm_campaign=skill_outreach_ningzimu_codex_ppt_skill) [](https://github.com/ningzimu/codex-ppt-skill/stargazers) [](https://github.com/ningzimu/codex-ppt-skill/forks)
|
||||
|
||||
一个面向 Codex 的 PPT 生成 skill，也可在 Claude Code、OpenClaw、Hermes Agent 等支持 `SKILL.md` 的 agent 中使用；在这些非 Codex 环境中通常需要配置 `gpt-image-2`、第三方生图 API 或 OpenAI 兼容格式的生图接口。它把文章、报告、论文、课程笔记等内容转换成“整页图片式”的演示文稿：先规划大纲和视觉风格，再生成每页幻灯片图片，最后用本地脚本组装为 `.pptx`。
|
||||
一个面向 Codex 的 PPT 生成 skill，也可在 Claude Code、OpenClaw、Hermes Agent 等支持 `SKILL.md` 的 agent 中使用；在这些非 Codex 环境中通常需要配置 `gpt-image-2.5-flare`、第三方生图 API 或 OpenAI 兼容格式的生图接口。它把文章、报告、论文、课程笔记等内容转换成“整页图片式”的演示文稿：先规划大纲和视觉风格，再生成每页幻灯片图片，最后用本地脚本组装为 `.pptx`。
|
||||
|
||||
## 赞助
|
||||
|
||||
@@ -42,7 +42,7 @@
|
||||
## 特点
|
||||
|
||||
- 多 agent 可用：支持 Codex、Claude Code、OpenClaw、Hermes Agent 等支持 `SKILL.md` 的环境；最推荐在 Codex 中使用，优先走内置生图和编辑图能力。
|
||||
- 第三方生图供应商接入：支持 OpenAI 兼容接口、AtlasCloud、`base URL` 和自定义模型名配置，方便通过 API/CLI fallback 使用 `gpt-image-2` 或兼容模型。
|
||||
- 第三方生图供应商接入：支持 OpenAI 兼容接口、AtlasCloud、`base URL` 和自定义模型名配置，方便通过 API/CLI fallback 使用 `gpt-image-2.5-flare` 或兼容模型。
|
||||
- 稳定的阶段化流程：先确认大纲、页数、视觉风格、生图后端和样张，再进入整套生成，降低一次生成完整 PPT 时的返工和偏航。
|
||||
- 不是无脑生成：会先引导你确认 `outline.md`、每页要点、风格方向和样张效果，再按确认后的方案继续。
|
||||
- 低门槛输入：文章、报告、论文、课程笔记、Markdown、大纲、PDF、Word 等材料都可以作为起点。
|
||||
@@ -219,7 +219,8 @@ skill 会按以下流程执行：
|
||||
|
||||
## 使用技巧
|
||||
|
||||
- Codex 会员默认会优先使用内置生图工具，其生成的图片分辨率比较低，且目前不能手动指定分辨率。如果需要更高分辨率的图像，需要改用 `gpt-image-2` API 的方式生成（即 API/CLI fallback，提供 API key、base URL 和模型名）。API/CLI fallback 场景下，脚本默认分辨率是 2K 16:9 横屏；如果生成的幻灯片图片仍然比较模糊，尤其是文字较多的页面，可以让 AI 改用 4K 分辨率生成。
|
||||
- 优先使用当前环境可调用的内置生图工具；实际模型、分辨率和可调参数取决于环境，不能仅凭会员身份或成功出图确认。若需精确指定尺寸或质量，而内置工具未暴露这些参数，可选择支持相应参数的 API/CLI fallback。API/CLI fallback 默认输出为 2K 16:9；文字较多或仍模糊时可尝试 4K；GPT Image 2.5 超过 `2560x1440` 像素的输出属于实验性能力，需检查实际结果。
|
||||
- API/CLI fallback 默认使用 `gpt-image-2.5-flare`，可用 `--model gpt-image-2.5-sunburst` 切换。两者支持 `xhigh` / `max` 质量及透明 PNG/WebP；默认仍为 2K 16:9、`medium`。旧模型保留原参数限制，第三方服务需确认其支持的模型和参数。
|
||||
- 如果只是不满意某一页的内容、排版、配色或文字表达，可以直接让当前 agent 针对这一页做细致修改，不需要整套 PPT 重新生成。
|
||||
|
||||
|
||||
@@ -230,7 +231,7 @@ skill 会按以下流程执行：
|
||||
## 我的其他项目
|
||||
|
||||
- [image-to-editable-ppt-skill](https://github.com/ningzimu/image-to-editable-ppt-skill)：把幻灯片截图、PDF 页面或图片版 PPTX 重建为可编辑 PowerPoint，适合在 `codex-ppt` 生成整页图片后继续做可编辑化。
|
||||
- [codex-gpt-image](https://github.com/ningzimu/codex-gpt-image)：通过 Codex OAuth / 会员登录调用 `gpt-image-2` 的生图 skill。
|
||||
- [codex-gpt-image](https://github.com/ningzimu/codex-gpt-image)：通过 Codex OAuth / 会员登录生成图片，支持 GPT Image 2.5 请求参数；实际后端模型取决于服务端。
|
||||
- [handdrawn-tech-illustrations](https://github.com/ningzimu/handdrawn-tech-illustrations)：面向中文技术内容的手绘配图 skill，可以把技术文章、产品笔记、截图、大纲或粗略想法生成正文配图、概念解释图、微信公众号封面和小红书封面；风格强调亲和、轻卡通、中文可读和适中的信息密度。
|
||||
- [awesome-ai-ppt](https://github.com/ningzimu/awesome-ai-ppt)：精选的 AI PPT 相关开源项目，按 HTML-first、图片生成式、PPTX-native、转换与自动化基础设施等工作流分类，关注能帮助 agent 或开发者创建、编辑、转换、检查 PPT 的 GitHub 仓库。
|
||||
- [awesome-skills](https://github.com/ningzimu/awesome-skills)：精选实用的 AI Agent Skills 与配套工具；安装一个入口后，Agent 会根据任务从持续更新的清单中选择、安装并使用合适的 skill。
|
||||
|
||||
+5
-4
@@ -4,7 +4,7 @@
|
||||
|
||||
[](https://ningzimu.github.io/codex-ppt-skill/#/en/) [](https://t.me/CodexPPT) [](https://clawhub.ai/ningzimu/codex-ppt) [](https://app.clawmama.run/skills/5lak48/hermes?utm_source=github&utm_medium=issue&utm_campaign=skill_outreach_ningzimu_codex_ppt_skill) [](https://github.com/ningzimu/codex-ppt-skill/stargazers) [](https://github.com/ningzimu/codex-ppt-skill/forks)
|
||||
|
||||
A Codex skill for generating PowerPoint decks. It can also be used in Claude Code, OpenClaw, Hermes Agent, and other agents that support `SKILL.md`; these non-Codex environments usually require configuring `gpt-image-2`, a third-party image API, or an OpenAI-compatible image generation endpoint. It turns articles, reports, papers, course notes, and other source materials into image-based presentations: first plan the outline and visual style, then generate each full-slide image, and finally assemble the images into a `.pptx` file with a local script.
|
||||
A Codex skill for generating PowerPoint decks. It can also be used in Claude Code, OpenClaw, Hermes Agent, and other agents that support `SKILL.md`; these non-Codex environments usually require configuring `gpt-image-2.5-flare`, a third-party image API, or an OpenAI-compatible image generation endpoint. It turns articles, reports, papers, course notes, and other source materials into image-based presentations: first plan the outline and visual style, then generate each full-slide image, and finally assemble the images into a `.pptx` file with a local script.
|
||||
|
||||
## Sponsor
|
||||
|
||||
@@ -42,7 +42,7 @@ For a basic introduction to skill design and usage, see [good-skill-design.pptx]
|
||||
## Features
|
||||
|
||||
- Works across multiple agents: supports Codex, Claude Code, OpenClaw, Hermes Agent, and other `SKILL.md`-based environments; Codex is the recommended environment because it can use the built-in image generation and image editing tools first.
|
||||
- Supports third-party image providers: works with OpenAI-compatible endpoints, AtlasCloud, `base URL`, and custom model names, so API/CLI fallback can use `gpt-image-2` or compatible image models.
|
||||
- Supports third-party image providers: works with OpenAI-compatible endpoints, AtlasCloud, `base URL`, and custom model names, so API/CLI fallback can use `gpt-image-2.5-flare` or compatible image models.
|
||||
- Stable staged workflow: confirms the outline, slide count, visual style, image backend, and sample slide before full-deck generation, reducing drift and rework when generating a complete PPT.
|
||||
- Guided instead of one-shot: the skill asks you to confirm `outline.md`, per-slide key points, style direction, and sample-slide quality before continuing.
|
||||
- Low setup effort: articles, reports, papers, course notes, Markdown files, outlines, PDFs, and Word documents can all be used as starting material.
|
||||
@@ -219,7 +219,8 @@ The skill follows this workflow:
|
||||
|
||||
## Usage Tips
|
||||
|
||||
- Codex subscribers use the built-in image generation tool by default; its output resolution is relatively low, and it does not currently expose a manual resolution setting. If you need higher-resolution images, switch to generating via the `gpt-image-2` API (the API/CLI fallback path, configured with an API key, base URL, and model name). In the API/CLI fallback path, the default script resolution is 2K 16:9 landscape; if slide images still look blurry, especially on text-heavy pages, ask the AI to switch to 4K.
|
||||
- Prefer the built-in image tool available in the current environment. Its actual model, resolution, and controls depend on that environment; a subscription or successful image response does not verify them. If precise size or quality settings are required and the built-in tool does not expose them, use an API/CLI fallback that supports those parameters. API/CLI fallback output defaults to 2K 16:9; try 4K for text-heavy or blurry slides. GPT Image 2.5 output above `2560x1440` pixels is experimental; inspect the actual result.
|
||||
- API/CLI fallback defaults to `gpt-image-2.5-flare`; select `--model gpt-image-2.5-sunburst` to switch. Both support `xhigh` / `max` quality and transparent PNG/WebP. Defaults remain 2K 16:9 and `medium`. Older models retain their parameter limits; check which models and parameters your provider supports.
|
||||
- If you are unhappy with one specific slide's content, layout, colors, or wording, ask the current agent to refine that slide in detail instead of regenerating the whole deck.
|
||||
|
||||
|
||||
@@ -230,7 +231,7 @@ The skill follows this workflow:
|
||||
## More Projects
|
||||
|
||||
- [image-to-editable-ppt-skill](https://github.com/ningzimu/image-to-editable-ppt-skill): Rebuild slide screenshots, PDF pages, or image-based PPTX files into editable PowerPoint decks, useful after `codex-ppt` generates image-based slides.
|
||||
- [codex-gpt-image](https://github.com/ningzimu/codex-gpt-image): A `gpt-image-2` image generation skill powered by Codex OAuth / member login.
|
||||
- [codex-gpt-image](https://github.com/ningzimu/codex-gpt-image): Image generation through Codex OAuth / member login, with GPT Image 2.5 request parameters; the actual backend model depends on the service.
|
||||
- [handdrawn-tech-illustrations](https://github.com/ningzimu/handdrawn-tech-illustrations): A hand-drawn illustration skill for Chinese technical content. It turns technical articles, product notes, screenshots, outlines, or rough ideas into article illustrations, concept explainer graphics, WeChat cover images, and Rednote covers, with a friendly, light-cartoon, Chinese-readable style and moderate information density.
|
||||
- [awesome-ai-ppt](https://github.com/ningzimu/awesome-ai-ppt): A curated list of open-source AI PPT projects, organized by workflows such as HTML-first, image-first, PPTX-native, conversion, and automation infrastructure, focused on GitHub projects that help agents or developers create, edit, convert, or inspect PPT decks.
|
||||
- [awesome-skills](https://github.com/ningzimu/awesome-skills): A curated list of practical AI Agent Skills and related tools. Install one entry point, and your agent can consult the continuously updated list to select, install, and use the right skill for each task.
|
||||
|
||||
+5
-4
@@ -4,7 +4,7 @@
|
||||
|
||||
[](https://ningzimu.github.io/codex-ppt-skill/#/ko/) [](https://t.me/CodexPPT) [](https://clawhub.ai/ningzimu/codex-ppt) [](https://app.clawmama.run/skills/5lak48/hermes?utm_source=github&utm_medium=issue&utm_campaign=skill_outreach_ningzimu_codex_ppt_skill) [](https://github.com/ningzimu/codex-ppt-skill/stargazers) [](https://github.com/ningzimu/codex-ppt-skill/forks)
|
||||
|
||||
PowerPoint 덱을 생성하는 Codex용 skill입니다. Codex 외에도 Claude Code, OpenClaw, Hermes Agent 등 `SKILL.md`를 지원하는 다른 에이전트에서도 사용할 수 있으며, 이런 비(非)Codex 환경에서는 보통 `gpt-image-2`, 서드파티 이미지 API, 또는 OpenAI 호환 이미지 생성 엔드포인트 설정이 필요합니다. 이 skill은 글, 리포트, 논문, 강의 노트 등의 원본 자료를 "한 페이지 통이미지" 형식의 프레젠테이션으로 변환합니다. 먼저 개요와 시각 스타일을 기획하고, 각 슬라이드를 전면 이미지로 생성한 뒤, 마지막에 로컬 스크립트로 이미지들을 `.pptx` 파일로 조립합니다.
|
||||
PowerPoint 덱을 생성하는 Codex용 skill입니다. Codex 외에도 Claude Code, OpenClaw, Hermes Agent 등 `SKILL.md`를 지원하는 다른 에이전트에서도 사용할 수 있으며, 이런 비(非)Codex 환경에서는 보통 `gpt-image-2.5-flare`, 서드파티 이미지 API, 또는 OpenAI 호환 이미지 생성 엔드포인트 설정이 필요합니다. 이 skill은 글, 리포트, 논문, 강의 노트 등의 원본 자료를 "한 페이지 통이미지" 형식의 프레젠테이션으로 변환합니다. 먼저 개요와 시각 스타일을 기획하고, 각 슬라이드를 전면 이미지로 생성한 뒤, 마지막에 로컬 스크립트로 이미지들을 `.pptx` 파일로 조립합니다.
|
||||
|
||||
## 스폰서
|
||||
|
||||
@@ -42,7 +42,7 @@ skill 설계와 사용에 대한 기본 소개는 [good-skill-design.pptx](asset
|
||||
## 특징
|
||||
|
||||
- 여러 에이전트에서 동작: Codex, Claude Code, OpenClaw, Hermes Agent 등 `SKILL.md` 기반 환경을 지원합니다. 내장 이미지 생성·편집 도구를 우선 사용할 수 있는 Codex가 가장 권장되는 환경입니다.
|
||||
- 서드파티 이미지 공급자 연동: OpenAI 호환 엔드포인트, AtlasCloud, `base URL`, 커스텀 모델명 설정을 지원하므로, API/CLI fallback에서 `gpt-image-2`나 호환 이미지 모델을 사용할 수 있습니다.
|
||||
- 서드파티 이미지 공급자 연동: OpenAI 호환 엔드포인트, AtlasCloud, `base URL`, 커스텀 모델명 설정을 지원하므로, API/CLI fallback에서 `gpt-image-2.5-flare`나 호환 이미지 모델을 사용할 수 있습니다.
|
||||
- 안정적인 단계형 워크플로: 전체 덱 생성 전에 개요, 슬라이드 수, 시각 스타일, 이미지 백엔드, 샘플 슬라이드를 확인하여 완성 PPT 생성 시의 이탈과 재작업을 줄입니다.
|
||||
- 원샷이 아닌 가이드형: 계속 진행하기 전에 `outline.md`, 슬라이드별 핵심 포인트, 스타일 방향, 샘플 슬라이드 품질을 확인하도록 요청합니다.
|
||||
- 낮은 준비 부담: 글, 리포트, 논문, 강의 노트, Markdown 파일, 개요, PDF, Word 문서 등을 모두 시작 자료로 사용할 수 있습니다.
|
||||
@@ -219,7 +219,8 @@ skill은 다음 워크플로를 따릅니다:
|
||||
|
||||
## 사용 팁
|
||||
|
||||
- Codex 구독자는 기본적으로 내장 이미지 생성 도구를 사용합니다. 이 도구의 출력 해상도는 비교적 낮고, 현재 수동 해상도 설정을 제공하지 않습니다. 더 높은 해상도의 이미지가 필요하면 `gpt-image-2` API를 통한 생성(API key, base URL, 모델명으로 설정하는 API/CLI fallback 경로)으로 전환하세요. API/CLI fallback 경로에서 스크립트 기본 해상도는 2K 16:9 가로이며, 특히 텍스트가 많은 페이지에서 슬라이드 이미지가 여전히 흐릿하면 AI에게 4K로 전환해 달라고 요청하세요.
|
||||
- 현재 환경에서 호출 가능한 내장 이미지 도구를 우선 사용합니다. 실제 모델, 해상도, 조절 가능한 매개변수는 환경에 따라 다르며, 구독 여부나 이미지 생성 성공만으로 확인할 수 없습니다. 정확한 크기나 품질 지정이 필요하지만 내장 도구가 해당 매개변수를 제공하지 않으면 이를 지원하는 API/CLI fallback을 선택하세요. API/CLI fallback의 기본 출력은 2K 16:9이며, 텍스트가 많거나 흐릿한 슬라이드는 4K를 시도할 수 있습니다. GPT Image 2.5에서 `2560x1440` 픽셀을 초과하는 출력은 실험적 기능이므로 실제 결과를 확인하세요.
|
||||
- API/CLI fallback의 기본 모델은 `gpt-image-2.5-flare`이며, `--model gpt-image-2.5-sunburst`로 전환할 수 있습니다. 두 모델은 `xhigh` / `max` 품질과 투명 PNG/WebP를 지원합니다. 기본값은 2K 16:9와 `medium`을 유지합니다. 이전 모델의 매개변수 제한은 유지되며, 서드파티 서비스가 지원하는 모델과 매개변수를 확인해야 합니다.
|
||||
- 특정 슬라이드의 내용, 레이아웃, 색상, 문구가 마음에 들지 않으면, 전체 덱을 다시 생성하는 대신 현재 에이전트에게 그 슬라이드를 상세히 다듬어 달라고 요청하세요.
|
||||
|
||||
|
||||
@@ -230,7 +231,7 @@ skill은 다음 워크플로를 따릅니다:
|
||||
## 관련 프로젝트
|
||||
|
||||
- [image-to-editable-ppt-skill](https://github.com/ningzimu/image-to-editable-ppt-skill): 슬라이드 스크린샷, PDF 페이지, 이미지 기반 PPTX 파일을 편집 가능한 PowerPoint 덱으로 재구성합니다. `codex-ppt`가 이미지 기반 슬라이드를 생성한 뒤에 유용합니다.
|
||||
- [codex-gpt-image](https://github.com/ningzimu/codex-gpt-image): Codex OAuth / 멤버 로그인 기반의 `gpt-image-2` 이미지 생성 skill입니다.
|
||||
- [codex-gpt-image](https://github.com/ningzimu/codex-gpt-image): Codex OAuth / 멤버 로그인으로 이미지를 생성하며 GPT Image 2.5 요청 매개변수를 지원합니다. 실제 백엔드 모델은 서비스에 따라 달라집니다.
|
||||
- [handdrawn-tech-illustrations](https://github.com/ningzimu/handdrawn-tech-illustrations): 중국어 기술 콘텐츠를 위한 손그림 일러스트 skill입니다. 기술 아티클, 제품 노트, 스크린샷, 개요, 대략적인 아이디어를 아티클 삽화, 개념 설명 그래픽, WeChat 커버 이미지, Rednote 커버로 변환하며, 친근하고 가벼운 카툰풍에 중국어 가독성이 좋고 적당한 정보 밀도를 갖습니다.
|
||||
- [awesome-ai-ppt](https://github.com/ningzimu/awesome-ai-ppt): 오픈소스 AI PPT 프로젝트를 HTML-first, image-first, PPTX-native, 변환, 자동화 인프라 등의 워크플로별로 정리한 큐레이션 목록입니다. 에이전트나 개발자가 PPT 덱을 만들고, 편집하고, 변환하고, 검사하는 데 도움이 되는 GitHub 프로젝트에 초점을 둡니다.
|
||||
- [awesome-skills](https://github.com/ningzimu/awesome-skills): 실용적인 AI Agent Skills와 관련 도구를 엄선한 목록입니다. 하나의 진입점을 설치하면 에이전트가 지속적으로 업데이트되는 목록을 참고해 작업에 맞는 skill을 선택하고 설치해 사용할 수 있습니다.
|
||||
|
||||
+2
-2
@@ -45,7 +45,7 @@ Codex PPT 是一个面向 Codex 的 PPT 生成 skill，也可在 Claude Code、O
|
||||
- 支持指定素材入页：可以把论文原图、实验结果图、架构图或截图指定到具体页面中使用。
|
||||
- 支持多 agent 环境：除 Codex 外，也可在 Claude Code、OpenClaw、Hermes Agent 等支持 `SKILL.md` 的 agent 中使用。
|
||||
- 自动组装 PowerPoint：生成 `outline.md`、每页图片、`speech.md`，并最终组装为 `.pptx` 文件。
|
||||
- 支持通过第三方 API 使用文本模型和 `gpt-image-2` 生图模型。
|
||||
- 支持通过第三方 API 使用文本模型和 `gpt-image-2.5-flare` 生图模型。
|
||||
- 支持配套生成 PPT 演讲稿，默认会自动插入 PPT 备注页。
|
||||
- 支持生成后针对特定不满意的页面做定向修改，参见[常见问题](faq.md)。
|
||||
|
||||
@@ -64,7 +64,7 @@ Codex PPT 生成的是图片式 PPT：视觉一致性强，但页面里的文字
|
||||
|
||||
如果你需要进一步转换成可编辑 PPT，可以在生成后再使用 [image-to-editable-ppt-skill](https://github.com/ningzimu/image-to-editable-ppt-skill)。
|
||||
|
||||
如果你没有 `gpt-image-2` 生图模型的使用权限，则无法使用该 skill，参见[安装与配置](installation.md)。
|
||||
需要当前环境可用的内置生图工具或兼容图片 API，参见[安装与配置](installation.md)。
|
||||
|
||||
## 相关链接
|
||||
|
||||
|
||||
+2
-2
@@ -45,7 +45,7 @@ If you are already using the skill and have encountered a problem, see the [FAQ]
|
||||
- Place specified source materials on designated slides: You can assign original paper figures, experiment results, architecture diagrams, or screenshots to specific slides.
|
||||
- Multiple agent environments: In addition to Codex, the skill works with agents that support `SKILL.md`, including Claude Code, OpenClaw, and Hermes Agent.
|
||||
- Automatic PowerPoint assembly: The skill generates `outline.md`, individual slide images, and `speech.md`, then assembles everything into a `.pptx` file.
|
||||
- Third-party API support for text models and the `gpt-image-2` image-generation model.
|
||||
- Third-party API support for text models and the `gpt-image-2.5-flare` image-generation model.
|
||||
- Companion speaker notes: Speaker notes are generated and inserted into the PowerPoint notes pages by default.
|
||||
- Targeted post-generation edits for specific slides that need improvement. See the [FAQ](/en/faq.md).
|
||||
|
||||
@@ -64,7 +64,7 @@ Codex PPT generates image-based presentations. They offer strong visual consiste
|
||||
|
||||
If you need to convert the result into an editable presentation, you can use [image-to-editable-ppt-skill](https://github.com/ningzimu/image-to-editable-ppt-skill) after generation.
|
||||
|
||||
You cannot use this skill without access to the `gpt-image-2` image-generation model. See [Installation and Configuration](/en/installation.md).
|
||||
This skill requires an available built-in image tool or compatible image API. See [Installation and Configuration](/en/installation.md).
|
||||
|
||||
## Related Links
|
||||
|
||||
|
||||
+4
-4
@@ -16,7 +16,7 @@ Yes. Codex PPT is a `SKILL.md`-based skill. In addition to Codex, it works with
|
||||
|
||||
This skill is developed and tested primarily with Codex, so Codex offers the best compatibility and is recommended.
|
||||
|
||||
Different agents have different image-generation capabilities and tool interfaces. Outside Codex, you will usually need to configure `gpt-image-2` or a third-party OpenAI-compatible image-generation API. See [Installation and Configuration](/en/installation.md), and let the AI guide you through setup based on your current environment.
|
||||
Different agents have different image-generation capabilities and tool interfaces. Outside Codex, you will usually need to configure `gpt-image-2.5-flare` or a third-party OpenAI-compatible image-generation API. See [Installation and Configuration](/en/installation.md), and let the AI guide you through setup based on your current environment.
|
||||
|
||||
## Q: How Do I Update the Skill to the Latest Version?
|
||||
|
||||
@@ -32,15 +32,15 @@ Do not regenerate the entire deck. First select one or two slides with obvious d
|
||||
|
||||
## Q: What Should I Do If the Generated Presentation Looks Bad?
|
||||
|
||||
First confirm that your `gpt-image-2` model can generate images correctly. If the model is unavailable, returns abnormal quality, or a third-party API or relay service does not correctly support `gpt-image-2`, the output quality will be significantly worse.
|
||||
First confirm that your selected image backend can generate images correctly. If it is unavailable, returns abnormal quality, or the provider does not support the selected model and parameters, the output quality will be significantly worse.
|
||||
|
||||
After confirming that the model works, ask the AI to address specific issues such as inconsistent styling, text that is too small, overcrowded layouts, unattractive colors, or illustrations that do not match the topic. It is best to regenerate one sample slide first and continue with the full deck only after you are satisfied.
|
||||
|
||||
## Q: What Should I Do If the Generated Slide Images Are Blurry?
|
||||
|
||||
Codex subscribers use the built-in image-generation tool by default. Its generated images have a relatively low resolution, which currently cannot be specified manually. For higher-resolution images, use the `gpt-image-2` API instead—the API/CLI fallback—and configure the API key, base URL, and model name. See [Installation and Configuration](/en/installation.md).
|
||||
Prefer the built-in image tool available in the current environment. Its actual model, resolution, and controls depend on that environment; a subscription or successful image response does not verify them. If precise size or quality settings are required and the built-in tool does not expose them, use an API/CLI fallback that supports those parameters. API/CLI fallback output defaults to 2K 16:9; try 4K for text-heavy or blurry slides. GPT Image 2.5 output above `2560x1440` pixels is experimental; inspect the actual result.
|
||||
|
||||
With the API/CLI fallback, the script defaults to 2K resolution in a 16:9 landscape format. If the image is still blurry, especially on slides with substantial text, ask the AI to generate it at 4K resolution.
|
||||
API/CLI fallback defaults to `gpt-image-2.5-flare`; select `--model gpt-image-2.5-sunburst` to switch. Both support `xhigh` / `max` quality and transparent PNG/WebP. Defaults remain 2K 16:9 and `medium`. Older models retain their parameter limits; check which models and parameters your provider supports.
|
||||
|
||||
## Q: Why Confirm the Outline First?
|
||||
|
||||
|
||||
@@ -74,25 +74,21 @@ Updates are safe: runtime configuration such as API keys is stored in `~/.codex-
|
||||
|
||||
## Image-Generation Model Configuration
|
||||
|
||||
You cannot use this skill without access to the `gpt-image-2` model. The skill depends heavily on the `gpt-image-2` image-generation model.
|
||||
You need an image backend available in the current environment: a built-in tool or a compatible image API. No single model is required.
|
||||
|
||||
## How Do I Know Whether I Have Access to `gpt-image-2`?
|
||||
API/CLI fallback defaults to `gpt-image-2.5-flare`; select `--model gpt-image-2.5-sunburst` to switch. Both support `xhigh` / `max` quality and transparent PNG/WebP. Defaults remain 2K 16:9 and `medium`. Older models retain their parameter limits; check which models and parameters your provider supports.
|
||||
|
||||
- If you subscribe to ChatGPT Plus or Pro, you have access to the `gpt-image-2` model by default. Codex includes a built-in image-generation tool.
|
||||
- If you access Codex through a third-party relay API, ask it to generate an image containing complex Chinese text, such as a poem written in running script. Check whether the image is generated successfully and whether the Chinese characters contain errors. If everything works, no further configuration is required.
|
||||
- If neither option works, you will need to purchase access to a relay API that provides the `gpt-image-2` model.
|
||||
|
||||
You usually do not need to configure the image-generation model manually. While you use Codex PPT, the AI automatically detects the image-generation backend. If none is available, it will ask you to configure an image-generation backend API and guide you through the setup.
|
||||
The AI checks whether the built-in tool is callable, then generates a sample to validate text and visual quality. Its actual model and parameters depend on the environment; a ChatGPT subscription or successful image response does not prove that 2.5 was used. Once API/CLI fallback is selected, configure the API key, base URL, and a provider-supported model as needed based on errors.
|
||||
|
||||
## Notes on Third-Party APIs
|
||||
|
||||
This skill includes a script compatible with OpenAI's official image-generation interface. If you use a third-party `gpt-image-2` relay API, try providing:
|
||||
This skill includes a script compatible with OpenAI's official image-generation interface. If you use a third-party `gpt-image-2.5-flare` relay API, try providing:
|
||||
|
||||
- The relay service's base URL
|
||||
- If the relay service gives an endpoint such as `https://xxx/v1/images/generations`, set the base URL to `https://xxx/v1`.
|
||||
- If the relay service already gives `https://xxx/v1`, do not append another layer, which would produce `.../v1/v1`.
|
||||
- For official OpenAI, `OPENAI_BASE_URL` can be omitted; the default is the official `https://api.openai.com/v1`.
|
||||
- The relay service's API key
|
||||
- The exact `gpt-image-2` model name used by the relay service
|
||||
- The exact `gpt-image-2.5-flare` model name used by the relay service
|
||||
|
||||
After providing this information to the AI, ask it to generate an image. If it still does not work, the relay service may use a custom image-generation scheme that is not fully compatible with the OpenAI image API. Send the relay service's official image-generation documentation to the AI so it can learn the interface and adapt the image-generation script.
|
||||
|
||||
+4
-4
@@ -16,7 +16,7 @@
|
||||
|
||||
本 skill 在 Codex 场景下开发和测试，对 Codex 的适配度最好，推荐优先使用。
|
||||
|
||||
需要注意的是，不同 agent 的图片生成能力和工具接口不一样。如果不是在 Codex 中使用，通常需要配置 `gpt-image-2` 或第三方 OpenAI 兼容格式的生图 API。具体配置方式可以参考[安装与配置](installation.md)，并在使用过程中让 AI 根据当前环境引导完成。
|
||||
需要注意的是，不同 agent 的图片生成能力和工具接口不一样。如果不是在 Codex 中使用，通常需要配置 `gpt-image-2.5-flare` 或第三方 OpenAI 兼容格式的生图 API。具体配置方式可以参考[安装与配置](installation.md)，并在使用过程中让 AI 根据当前环境引导完成。
|
||||
|
||||
## Q：如何更新 skill 到最新版本？
|
||||
|
||||
@@ -32,15 +32,15 @@
|
||||
|
||||
## Q：生成的 PPT 很丑怎么办？
|
||||
|
||||
请先检查自己的 `gpt-image-2` 模型是否可以正常生图。如果模型本身不可用、返回质量异常，或者第三方 API / 中转站没有正确支持 `gpt-image-2`，生成效果会明显变差。
|
||||
请先检查所选生图后端是否可以正常生图。如果后端不可用、返回质量异常，或者第三方 API / 中转站未正确支持所选模型和参数，生成效果会明显变差。
|
||||
|
||||
确认模型可用后，再让 AI 针对具体问题修改，例如风格不统一、文字太小、页面太挤、配色不好看、插图不贴合主题等。建议先重新生成 1 页样张，满意后再继续整套生成。
|
||||
|
||||
## Q：生成的幻灯片图片比较模糊怎么办？
|
||||
|
||||
Codex 会员默认使用内置生图工具，其生成的图片分辨率比较低，且目前不能手动指定分辨率。如果需要更高分辨率的图像，需要改用 `gpt-image-2` API 的方式生成（即 API/CLI fallback，配置 API key、base URL 和模型名，参见[安装与配置](installation.md)）。
|
||||
优先使用当前环境可调用的内置生图工具；实际模型、分辨率和可调参数取决于环境，不能仅凭会员身份或成功出图确认。若需精确指定尺寸或质量，而内置工具未暴露这些参数，可选择支持相应参数的 API/CLI fallback。API/CLI fallback 默认输出为 2K 16:9；文字较多或仍模糊时可尝试 4K；GPT Image 2.5 超过 `2560x1440` 像素的输出属于实验性能力，需检查实际结果。
|
||||
|
||||
API/CLI fallback 场景下，脚本默认分辨率是 2K 16:9 横屏。如果图片仍然模糊，尤其是文字较多的页面，可以让 AI 改用 4K 分辨率生成。
|
||||
API/CLI fallback 默认使用 `gpt-image-2.5-flare`，可用 `--model gpt-image-2.5-sunburst` 切换。两者支持 `xhigh` / `max` 质量及透明 PNG/WebP；默认仍为 2K 16:9、`medium`。旧模型保留原参数限制，第三方服务需确认其支持的模型和参数。
|
||||
|
||||
## Q：为什么要先确认大纲？
|
||||
|
||||
|
||||
@@ -74,25 +74,21 @@ npx -y skills@latest add ningzimu/codex-ppt-skill \
|
||||
|
||||
## 生图模型配置
|
||||
|
||||
如果你没有 `gpt-image-2` 模型的使用权限，就无法使用该 skill。该 skill 强依赖 `gpt-image-2` 生图模型。
|
||||
需要一个当前环境可用的生图后端：内置工具或兼容的图片 API。无需固定依赖某个模型。
|
||||
|
||||
## 如何判断是否具备 `gpt-image-2` 使用权限？
|
||||
API/CLI fallback 默认使用 `gpt-image-2.5-flare`，可用 `--model gpt-image-2.5-sunburst` 切换。两者支持 `xhigh` / `max` 质量及透明 PNG/WebP；默认仍为 2K 16:9、`medium`。旧模型保留原参数限制，第三方服务需确认其支持的模型和参数。
|
||||
|
||||
- 如果你购买了 ChatGPT Plus、Pro 会员，默认就可以使用 `gpt-image-2` 模型；Codex 有一个内置工具用于生图。
|
||||
- 如果你使用第三方中转 API 接入 Codex，可以让它生成一张包含复杂中文文本的图片，例如要求用行楷写一首诗。观察是否能正常生图，以及生成的图里是否有中文字体错误。如果一切正常，也无需配置。
|
||||
- 如果上面两个都不行，就需要自行购买具备 `gpt-image-2` 模型使用权限的中转 API。
|
||||
|
||||
通常不需要手动配置生图模型。你在使用 Codex PPT 的过程中，AI 会自动检测生图后端；如果不可用，会提示你配置生图后端 API，并引导你完成配置。
|
||||
AI 会先检查内置工具是否可调用，再生成样张验证文字和视觉质量。内置工具的实际模型与参数由环境决定，不能仅凭 ChatGPT 会员身份或成功出图确认已使用 2.5。只有选择 API/CLI fallback 后，才按报错配置 API key、base URL 和服务商支持的模型名。
|
||||
|
||||
## 第三方 API 注意事项
|
||||
|
||||
本 skill 内置了一个适配 OpenAI 官方生图方式的脚本。如果你用的是第三方 `gpt-image-2` 中转 API，可以尝试提供：
|
||||
本 skill 内置了一个适配 OpenAI 官方生图方式的脚本。如果你用的是第三方 `gpt-image-2.5-flare` 中转 API，可以尝试提供：
|
||||
|
||||
- 中转站的 base URL
|
||||
- 中转站示例如果是 `https://xxx/v1/images/generations`，base URL 填 `https://xxx/v1`。
|
||||
- 如果中转站已经给的是 `https://xxx/v1`，不要再加一层，避免 `.../v1/v1`。
|
||||
- 如果是官方 OpenAI，`OPENAI_BASE_URL` 可以不填，默认就是官方 `https://api.openai.com/v1`。
|
||||
- 中转站的 API key
|
||||
- 中转站的 `gpt-image-2` 具体模型名
|
||||
- 中转站的 `gpt-image-2.5-flare` 具体模型名
|
||||
|
||||
将上述信息提供给 AI 之后，尝试让其生图。如果跑不通，则可能你使用的中转站有自定义的生图使用方案，不完全兼容 OpenAI 生图接口。请将中转站官方的生图使用文档发给 AI，让它学习并适配生图脚本。
|
||||
|
||||
+2
-2
@@ -45,7 +45,7 @@ Codex PPT는 Codex용 PPT 생성 skill이며, Claude Code, OpenClaw, Hermes Agen
|
||||
- 지정 이미지 삽입: 논문 원본 이미지, 실험 결과 그래프, 아키텍처 다이어그램 또는 스크린샷을 특정 슬라이드에 사용하도록 지정할 수 있습니다.
|
||||
- 여러 agent 환경 지원: Codex 외에도 Claude Code, OpenClaw, Hermes Agent 등 `SKILL.md`를 지원하는 agent에서 사용할 수 있습니다.
|
||||
- PowerPoint 자동 조립: `outline.md`, 각 슬라이드 이미지, `speech.md`를 생성하고 최종적으로 `.pptx` 파일로 조립합니다.
|
||||
- 서드파티 API를 통한 텍스트 모델 및 `gpt-image-2` 이미지 생성 모델 사용 지원.
|
||||
- 서드파티 API를 통한 텍스트 모델 및 `gpt-image-2.5-flare` 이미지 생성 모델 사용 지원.
|
||||
- PPT 발표 대본 생성을 지원하며, 기본적으로 PPT 메모 영역에 자동 삽입합니다.
|
||||
- 생성 후 만족스럽지 않은 특정 슬라이드만 선택적으로 수정할 수 있습니다. 자세한 내용은 [자주 묻는 질문](/ko/faq.md)을 참고하세요.
|
||||
|
||||
@@ -64,7 +64,7 @@ Codex PPT는 이미지형 PPT를 생성합니다. 시각적 일관성은 높지
|
||||
|
||||
편집 가능한 PPT로 추가 변환해야 한다면 생성 후 [image-to-editable-ppt-skill](https://github.com/ningzimu/image-to-editable-ppt-skill)을 사용할 수 있습니다.
|
||||
|
||||
`gpt-image-2` 이미지 생성 모델을 사용할 권한이 없다면 이 skill을 사용할 수 없습니다. 자세한 내용은 [설치 및 설정](/ko/installation.md)을 참고하세요.
|
||||
이 skill에는 사용 가능한 내장 이미지 도구 또는 호환 이미지 API가 필요합니다. 자세한 내용은 [설치 및 설정](/ko/installation.md)을 참고하세요.
|
||||
|
||||
## 관련 링크
|
||||
|
||||
|
||||
+4
-4
@@ -16,7 +16,7 @@
|
||||
|
||||
이 skill은 Codex 환경에서 개발 및 테스트되어 Codex와의 호환성이 가장 좋으므로 우선 사용을 권장합니다.
|
||||
|
||||
각 agent의 이미지 생성 기능과 도구 인터페이스가 서로 다르다는 점에 유의해야 합니다. Codex에서 사용하지 않는 경우 일반적으로 `gpt-image-2` 또는 서드파티 OpenAI 호환 형식의 이미지 생성 API를 설정해야 합니다. 구체적인 설정 방법은 [설치 및 설정](/ko/installation.md)을 참고하고, 사용 중 AI가 현재 환경에 맞게 설정을 안내하도록 하세요.
|
||||
각 agent의 이미지 생성 기능과 도구 인터페이스가 서로 다르다는 점에 유의해야 합니다. Codex에서 사용하지 않는 경우 일반적으로 `gpt-image-2.5-flare` 또는 서드파티 OpenAI 호환 형식의 이미지 생성 API를 설정해야 합니다. 구체적인 설정 방법은 [설치 및 설정](/ko/installation.md)을 참고하고, 사용 중 AI가 현재 환경에 맞게 설정을 안내하도록 하세요.
|
||||
|
||||
## Q: skill을 최신 버전으로 업데이트하려면 어떻게 하나요?
|
||||
|
||||
@@ -32,15 +32,15 @@
|
||||
|
||||
## Q: 생성된 PPT가 보기 좋지 않으면 어떻게 하나요?
|
||||
|
||||
먼저 `gpt-image-2` 모델로 이미지가 정상적으로 생성되는지 확인하세요. 모델 자체를 사용할 수 없거나 비정상적인 품질의 결과를 반환하거나, 서드파티 API / 프록시 서비스가 `gpt-image-2`를 제대로 지원하지 않으면 생성 품질이 크게 떨어집니다.
|
||||
먼저 선택한 이미지 백엔드가 정상적으로 이미지를 생성하는지 확인하세요. 백엔드를 사용할 수 없거나 결과 품질이 비정상적이거나 서비스가 선택한 모델과 매개변수를 지원하지 않으면 생성 품질이 크게 떨어집니다.
|
||||
|
||||
모델을 사용할 수 있는지 확인한 뒤 스타일 불일치, 너무 작은 텍스트, 지나치게 빽빽한 페이지, 조화롭지 않은 색상, 주제와 맞지 않는 일러스트 등 구체적인 문제를 AI에게 수정하도록 하세요. 샘플 슬라이드 1장을 먼저 다시 생성하고 만족한 뒤 전체 생성을 계속하는 것을 권장합니다.
|
||||
|
||||
## Q: 생성된 슬라이드 이미지가 흐리면 어떻게 하나요?
|
||||
|
||||
Codex 회원은 기본적으로 내장 이미지 생성 도구를 사용합니다. 이 도구로 생성한 이미지의 해상도는 비교적 낮으며 현재 수동으로 지정할 수 없습니다. 더 높은 해상도가 필요하다면 `gpt-image-2` API 방식으로 생성해야 합니다. 즉, API key, base URL과 모델명을 설정하는 API/CLI fallback을 사용합니다. 자세한 내용은 [설치 및 설정](/ko/installation.md)을 참고하세요.
|
||||
현재 환경에서 호출 가능한 내장 이미지 도구를 우선 사용합니다. 실제 모델, 해상도, 조절 가능한 매개변수는 환경에 따라 다르며, 구독 여부나 이미지 생성 성공만으로 확인할 수 없습니다. 정확한 크기나 품질 지정이 필요하지만 내장 도구가 해당 매개변수를 제공하지 않으면 이를 지원하는 API/CLI fallback을 선택하세요. API/CLI fallback의 기본 출력은 2K 16:9이며, 텍스트가 많거나 흐릿한 슬라이드는 4K를 시도할 수 있습니다. GPT Image 2.5에서 `2560x1440` 픽셀을 초과하는 출력은 실험적 기능이므로 실제 결과를 확인하세요.
|
||||
|
||||
API/CLI fallback에서는 스크립트의 기본 해상도가 2K 16:9 가로 화면입니다. 이미지가 여전히 흐리다면, 특히 텍스트가 많은 페이지에서는 AI에게 4K 해상도로 생성하도록 요청할 수 있습니다.
|
||||
API/CLI fallback의 기본 모델은 `gpt-image-2.5-flare`이며, `--model gpt-image-2.5-sunburst`로 전환할 수 있습니다. 두 모델은 `xhigh` / `max` 품질과 투명 PNG/WebP를 지원합니다. 기본값은 2K 16:9와 `medium`을 유지합니다. 이전 모델의 매개변수 제한은 유지되며, 서드파티 서비스가 지원하는 모델과 매개변수를 확인해야 합니다.
|
||||
|
||||
## Q: 개요를 먼저 확인해야 하는 이유는 무엇인가요?
|
||||
|
||||
|
||||
@@ -74,25 +74,21 @@ codex-ppt skill을 최신 버전으로 업데이트해 주세요. 저장소: htt
|
||||
|
||||
## 이미지 생성 모델 설정
|
||||
|
||||
`gpt-image-2` 모델 사용 권한이 없다면 이 skill을 사용할 수 없습니다. 이 skill은 `gpt-image-2` 이미지 생성 모델에 크게 의존합니다.
|
||||
현재 환경에서 사용할 수 있는 내장 도구 또는 호환 이미지 API가 필요합니다. 특정 모델에 의존하지 않습니다.
|
||||
|
||||
## `gpt-image-2` 사용 권한 확인 방법
|
||||
API/CLI fallback의 기본 모델은 `gpt-image-2.5-flare`이며, `--model gpt-image-2.5-sunburst`로 전환할 수 있습니다. 두 모델은 `xhigh` / `max` 품질과 투명 PNG/WebP를 지원합니다. 기본값은 2K 16:9와 `medium`을 유지합니다. 이전 모델의 매개변수 제한은 유지되며, 서드파티 서비스가 지원하는 모델과 매개변수를 확인해야 합니다.
|
||||
|
||||
- ChatGPT Plus 또는 Pro 멤버십을 구독 중이라면 기본적으로 `gpt-image-2` 모델을 사용할 수 있습니다. Codex에는 이미지 생성을 위한 내장 도구가 있습니다.
|
||||
- 서드파티 프록시 API로 Codex를 사용하는 경우, 행서체로 시 한 편을 써 달라는 요청처럼 복잡한 중국어 텍스트가 포함된 이미지를 생성하게 해 보세요. 이미지가 정상적으로 생성되는지, 생성된 이미지의 중국어 글꼴에 오류가 없는지 확인하세요. 모두 정상이라면 별도 설정이 필요 없습니다.
|
||||
- 위 두 방법 모두 사용할 수 없다면 `gpt-image-2` 모델 사용 권한을 제공하는 프록시 API를 직접 구매해야 합니다.
|
||||
|
||||
보통 이미지 생성 모델을 수동으로 설정할 필요는 없습니다. Codex PPT를 사용하는 동안 AI가 이미지 생성 백엔드를 자동으로 감지합니다. 사용할 수 없는 경우 이미지 생성 백엔드 API 설정이 필요하다는 안내와 함께 설정 과정을 도와줍니다.
|
||||
AI는 내장 도구를 호출할 수 있는지 먼저 확인한 뒤 샘플을 생성하여 텍스트와 시각 품질을 검증합니다. 실제 모델과 매개변수는 환경에 따라 다르며, ChatGPT 구독이나 이미지 생성 성공만으로 2.5 사용을 입증할 수 없습니다. API/CLI fallback을 선택한 후 오류에 따라 API key, base URL, 서비스가 지원하는 모델명을 설정합니다.
|
||||
|
||||
## 서드파티 API 유의 사항
|
||||
|
||||
이 skill에는 OpenAI 공식 이미지 생성 방식을 지원하는 스크립트가 포함되어 있습니다. 서드파티 `gpt-image-2` 프록시 API를 사용하는 경우 다음 정보를 제공해 보세요.
|
||||
이 skill에는 OpenAI 공식 이미지 생성 방식을 지원하는 스크립트가 포함되어 있습니다. 서드파티 `gpt-image-2.5-flare` 프록시 API를 사용하는 경우 다음 정보를 제공해 보세요.
|
||||
|
||||
- 프록시 서비스의 base URL
|
||||
- 프록시 서비스에서 제공한 예시가 `https://xxx/v1/images/generations`라면 base URL에는 `https://xxx/v1`을 입력합니다.
|
||||
- 프록시 서비스에서 이미 `https://xxx/v1`을 제공했다면 한 단계를 더 추가하지 마세요. 그렇지 않으면 `.../v1/v1`이 됩니다.
|
||||
- OpenAI 공식 서비스를 사용하는 경우 `OPENAI_BASE_URL`을 입력하지 않아도 됩니다. 기본값은 공식 주소인 `https://api.openai.com/v1`입니다.
|
||||
- 프록시 서비스의 API key
|
||||
- 프록시 서비스의 구체적인 `gpt-image-2` 모델명
|
||||
- 프록시 서비스의 구체적인 `gpt-image-2.5-flare` 모델명
|
||||
|
||||
위 정보를 AI에 제공한 뒤 이미지 생성을 시도하세요. 실행되지 않는다면 사용하는 프록시 서비스에 OpenAI 이미지 생성 인터페이스와 완전히 호환되지 않는 자체 이미지 생성 방식이 있을 수 있습니다. 프록시 서비스의 공식 이미지 생성 문서를 AI에 전달해 스크립트를 학습하고 조정하도록 하세요.
|
||||
|
||||
@@ -16,7 +16,7 @@ metadata:
|
||||
description: API base URL.
|
||||
- name: CODEX_PPT_IMAGE_MODEL
|
||||
required: false
|
||||
description: Image model, defaults to gpt-image-2.
|
||||
description: Image model, defaults to gpt-image-2.5-flare.
|
||||
- name: CODEX_PPT_HOME
|
||||
required: false
|
||||
description: Runtime home override.
|
||||
|
||||
@@ -10,8 +10,8 @@ This skill supports two image backends:
|
||||
## Decision Rules
|
||||
|
||||
- Before recommending CLI/API fallback, actively check whether the built-in image generation tool is callable in the current environment. Do not infer availability only from the agent name or subscription context.
|
||||
- Prefer the built-in image tool when available. In Codex, this usually means the built-in `image_gen` tool. In OpenClaw, this may be `image_generate`. Resolution, quality, aspect ratio, slide-edit requests, or the user saying "use `gpt-image-2`" do not require CLI/API fallback.
|
||||
- In Codex, treat the built-in image tool as the preferred `gpt-image-2` path when it is available. If the user has a GPT subscription / Codex environment and asks for `gpt-image-2`, do not switch to `scripts/image_gen.py` only to satisfy the model name.
|
||||
- Prefer the built-in image tool when available. In Codex, this usually means the built-in `image_gen` tool. In OpenClaw, this may be `image_generate`. Resolution, quality, aspect ratio, or slide-edit requests alone do not require CLI/API fallback. Check which parameters the current tool actually exposes.
|
||||
- Do not identify the built-in tool as a specific GPT Image model unless the environment provides evidence. If exact model, size, or quality selection is required but the tool does not expose it, explain the limitation and select a compatible API/CLI fallback with the user. Successful image generation alone does not verify the actual model or requested parameters.
|
||||
- Use CLI/API fallback only when the built-in tool is unavailable, the built-in tool failed for a required capability, the user explicitly asks for API/CLI or a third-party image API/provider adapter, or the requested capability is unavailable in the built-in tool.
|
||||
- Do not recommend CLI/API fallback merely because it provides direct `--out` file paths, easier local file management, local config reuse, batch generation convenience, or simpler automation.
|
||||
- Before generating the first image, tell the user which tool availability you checked, which backend you plan to use, why fallback is or is not needed, and ask for confirmation. Do not treat being in a specific agent environment as proof that the built-in image tool is available.
|
||||
|
||||
@@ -22,14 +22,14 @@ Basic generation command:
|
||||
|
||||
```bash
|
||||
~/.codex-ppt-skill/.venv/bin/python {skill_root}/scripts/image_gen.py generate \
|
||||
--model gpt-image-2 \
|
||||
--model gpt-image-2.5-flare \
|
||||
--prompt-file {prompt_file} \
|
||||
--size 2560x1440 \
|
||||
--quality medium \
|
||||
--out {base_dir}/{deck_name}/origin_image/slide_01.png
|
||||
```
|
||||
|
||||
The fallback CLI accepts model names containing `gpt-image-`, such as `gpt-image-2` or `openai/gpt-image-2`.
|
||||
The fallback CLI defaults to `gpt-image-2.5-flare`. Select `--model gpt-image-2.5-sunburst` for Sunburst. It also accepts provider-prefixed names and older GPT Image models; verify provider support before using a model.
|
||||
|
||||
When generating from saved `prompts/slide_XX.json` files, use the job's `prompt` field only when the job does not require input images:
|
||||
|
||||
@@ -51,7 +51,7 @@ The fallback CLI supports:
|
||||
- `generate`: create one or more images from a prompt.
|
||||
- `edit`: edit one or more existing images, optionally with a mask.
|
||||
|
||||
The fallback CLI defaults to 2K 16:9 landscape output, `2560x1440`, because it keeps slide text clearer while staying below the `gpt-image-2` pixel limit. For 4K landscape slides, use `--size 3840x2160 --quality high` only when the user asks for 4K, text-heavy slides need sharper output, or the default result is blurry. For portrait assets, use `--size 2160x3840` only if the user requests portrait output.
|
||||
The fallback CLI defaults to 2K 16:9 landscape output, `2560x1440`, with `medium` quality. GPT Image 2.5 also supports `xhigh` and `max`; older models retain their existing quality limits. For 4K landscape slides, use `--size 3840x2160 --quality high` only when the user asks for 4K, text-heavy slides need sharper output, or the default result is blurry. For portrait assets, use `--size 2160x3840` only if the user requests portrait output. For GPT Image 2.5, output above `2560x1440` pixels is experimental; inspect the actual size and visual quality.
|
||||
|
||||
## Editing Slides
|
||||
|
||||
@@ -70,9 +70,9 @@ Replace the final slide only after validating the edited output.
|
||||
|
||||
Transparent-background requests:
|
||||
|
||||
- Built-in mode should use a flat chroma-key background and local removal when appropriate.
|
||||
- CLI/API fallback should also prefer chroma-key generation plus `scripts/remove_chroma_key.py` for simple opaque subjects.
|
||||
- `gpt-image-2` does not support `--background transparent`. If the user needs true model-native transparency, ask before switching to `--model gpt-image-1.5 --background transparent --output-format png`.
|
||||
- GPT Image 2.5 Flare and Sunburst support `--background transparent --output-format png` (or `webp`) through compatible APIs. JPEG cannot preserve transparency. The current AtlasCloud adapter does not forward `background` and accepts only PNG/JPEG; do not promise native transparency through that adapter.
|
||||
- `gpt-image-2` does not support native transparent backgrounds; GPT Image 1 / 1.5 do. Preserve the selected model unless a switch has been agreed.
|
||||
- In built-in mode, use native transparency if the tool supports it; otherwise use a flat chroma-key background and `scripts/remove_chroma_key.py` when appropriate.
|
||||
|
||||
## Assembly And Doctor
|
||||
|
||||
|
||||
@@ -19,13 +19,13 @@ Typical cases:
|
||||
- Codex is using a third-party API or OpenAI-compatible proxy for image generation.
|
||||
- The skill is being used from Claude Code, OpenClaw, Hermes Agent, or another agent without Codex's built-in image tool.
|
||||
|
||||
If Codex is being used through a GPT subscription and the built-in image tool is available, do not ask the user to configure `gpt-image-2`.
|
||||
If Codex is being used through a GPT subscription and the built-in image tool is available, do not ask the user to configure `gpt-image-2.5-flare`.
|
||||
|
||||
## Required And Optional Values
|
||||
|
||||
- `OPENAI_API_KEY` is required for real API/CLI fallback calls.
|
||||
- `OPENAI_BASE_URL` is optional. When it is unset, the CLI uses the official OpenAI API. When it is set, the CLI uses the configured third-party provider base URL.
|
||||
- `CODEX_PPT_IMAGE_MODEL` is optional. The default is `gpt-image-2`. Use a custom value only when the provider requires one.
|
||||
- `CODEX_PPT_IMAGE_MODEL` is optional. The default is `gpt-image-2.5-flare`. Use `gpt-image-2.5-sunburst` to select Sunburst, or a model name supported by the provider.
|
||||
|
||||
Configure provided API settings with `scripts/codex_ppt_runtime.py config --api-key`. The config command writes `~/.codex-ppt-skill/.env`.
|
||||
|
||||
@@ -34,7 +34,7 @@ Configure provided API settings with `scripts/codex_ppt_runtime.py config --api-
|
||||
```bash
|
||||
python3 {skill_root}/scripts/codex_ppt_runtime.py config \
|
||||
--api-key "your-api-key" \
|
||||
--model gpt-image-2
|
||||
--model gpt-image-2.5-flare
|
||||
```
|
||||
|
||||
## OpenAI-Compatible Provider Example
|
||||
@@ -45,7 +45,7 @@ Use this shape for providers that implement the OpenAI Images API paths used by
|
||||
python3 {skill_root}/scripts/codex_ppt_runtime.py config \
|
||||
--api-key "your-provider-api-key" \
|
||||
--base-url "https://xxxx.example.com/v1" \
|
||||
--model gpt-image-2
|
||||
--model gpt-image-2.5-flare
|
||||
```
|
||||
|
||||
This produces the same effective runtime config as:
|
||||
@@ -53,16 +53,16 @@ This produces the same effective runtime config as:
|
||||
```env
|
||||
OPENAI_API_KEY=your-provider-api-key
|
||||
OPENAI_BASE_URL=https://xxxx.example.com/v1
|
||||
CODEX_PPT_IMAGE_MODEL=gpt-image-2
|
||||
CODEX_PPT_IMAGE_MODEL=gpt-image-2.5-flare
|
||||
```
|
||||
|
||||
For OpenAI-compatible providers, `OPENAI_BASE_URL` should normally end at the provider's `/v1` root. Do not set it to `/images/generations`, `/images/edits`, or another terminal endpoint. The fallback CLI appends the image-generation or image-edit path through the OpenAI SDK.
|
||||
|
||||
Use the provider's model name only when the provider documents a custom name. Otherwise prefer `gpt-image-2`.
|
||||
Use the provider's model name only when the provider documents a custom name. Otherwise prefer `gpt-image-2.5-flare`.
|
||||
|
||||
## AtlasCloud Example
|
||||
|
||||
For AtlasCloud, set `--model` to the base model name. The CLI chooses the matching generation or editing model route internally.
|
||||
For AtlasCloud, set `--model` to the base model name. The CLI chooses the matching generation or editing model route internally. This example retains the known `gpt-image-2` route; check provider documentation before selecting a 2.5 model.
|
||||
|
||||
```bash
|
||||
python3 {skill_root}/scripts/codex_ppt_runtime.py config \
|
||||
|
||||
@@ -23,7 +23,7 @@ import venv
|
||||
|
||||
|
||||
DEFAULT_RUNTIME_HOME = "~/.codex-ppt-skill"
|
||||
DEFAULT_MODEL = "gpt-image-2"
|
||||
DEFAULT_MODEL = "gpt-image-2.5-flare"
|
||||
ENV_FIELDS = ("OPENAI_API_KEY", "OPENAI_BASE_URL", "CODEX_PPT_IMAGE_MODEL")
|
||||
|
||||
|
||||
|
||||
@@ -2,10 +2,9 @@
|
||||
"""Fallback CLI for codex-ppt image generation or editing with GPT Image models.
|
||||
|
||||
Used when Codex's built-in image tool is unavailable, when the user explicitly
|
||||
opts into API mode, or when explicit transparent output requires the
|
||||
`gpt-image-1.5` fallback path.
|
||||
opts into API mode, or needs output controls exposed by the API.
|
||||
|
||||
Defaults to gpt-image-2 and a structured prompt augmentation workflow.
|
||||
Defaults to gpt-image-2.5-flare and a structured prompt augmentation workflow.
|
||||
Reads OPENAI_API_KEY, and optionally OPENAI_BASE_URL for provider adapters or
|
||||
OpenAI-compatible proxy providers.
|
||||
"""
|
||||
@@ -28,7 +27,7 @@ from urllib.parse import urlparse
|
||||
from image_providers import create_image_provider
|
||||
from image_providers.atlascloud import atlascloud_model_for_operation
|
||||
|
||||
DEFAULT_MODEL = "gpt-image-2"
|
||||
DEFAULT_MODEL = "gpt-image-2.5-flare"
|
||||
DEFAULT_SIZE = "2560x1440"
|
||||
DEFAULT_QUALITY = "medium"
|
||||
DEFAULT_OUTPUT_FORMAT = "png"
|
||||
@@ -38,11 +37,10 @@ DEFAULT_OUTPUT_PATH = "output/imagegen/output.png"
|
||||
GPT_IMAGE_MODEL_PREFIX = "gpt-image-"
|
||||
|
||||
ALLOWED_LEGACY_SIZES = {"1024x1024", "1536x1024", "1024x1536", "auto"}
|
||||
ALLOWED_QUALITIES = {"low", "medium", "high", "auto"}
|
||||
ALLOWED_QUALITIES = {"low", "medium", "high", "xhigh", "max", "auto"}
|
||||
ALLOWED_BACKGROUNDS = {"transparent", "opaque", "auto", None}
|
||||
ALLOWED_INPUT_FIDELITIES = {"low", "high", None}
|
||||
|
||||
GPT_IMAGE_2_MODEL = "gpt-image-2"
|
||||
GPT_IMAGE_2_MIN_PIXELS = 655_360
|
||||
GPT_IMAGE_2_MAX_PIXELS = 8_294_400
|
||||
GPT_IMAGE_2_MAX_EDGE = 3840
|
||||
@@ -237,19 +235,19 @@ def _validate_gpt_image_2_size(size: str) -> None:
|
||||
total_pixels = width * height
|
||||
|
||||
if max_edge > GPT_IMAGE_2_MAX_EDGE:
|
||||
_die("gpt-image-2 size maximum edge length must be less than or equal to 3840px.")
|
||||
_die("GPT Image 2 / 2.5 size maximum edge length must be less than or equal to 3840px.")
|
||||
if width % 16 != 0 or height % 16 != 0:
|
||||
_die("gpt-image-2 size width and height must be multiples of 16px.")
|
||||
_die("GPT Image 2 / 2.5 size width and height must be multiples of 16px.")
|
||||
if max_edge / min_edge > GPT_IMAGE_2_MAX_RATIO:
|
||||
_die("gpt-image-2 size long edge to short edge ratio must not exceed 3:1.")
|
||||
_die("GPT Image 2 / 2.5 size long edge to short edge ratio must not exceed 3:1.")
|
||||
if total_pixels < GPT_IMAGE_2_MIN_PIXELS or total_pixels > GPT_IMAGE_2_MAX_PIXELS:
|
||||
_die(
|
||||
"gpt-image-2 size total pixels must be at least 655,360 and no more than 8,294,400."
|
||||
"GPT Image 2 / 2.5 size total pixels must be at least 655,360 and no more than 8,294,400."
|
||||
)
|
||||
|
||||
|
||||
def _validate_size(size: str, model: str) -> None:
|
||||
if _is_gpt_image_2_model(model):
|
||||
if _is_gpt_image_2_model(model) or _is_gpt_image_2_5_model(model):
|
||||
_validate_gpt_image_2_size(size)
|
||||
return
|
||||
|
||||
@@ -259,9 +257,11 @@ def _validate_size(size: str, model: str) -> None:
|
||||
)
|
||||
|
||||
|
||||
def _validate_quality(quality: str) -> None:
|
||||
def _validate_quality(quality: str, model: str) -> None:
|
||||
if quality not in ALLOWED_QUALITIES:
|
||||
_die("quality must be one of low, medium, high, or auto.")
|
||||
_die("quality must be one of low, medium, high, xhigh, max, or auto.")
|
||||
if quality in {"xhigh", "max"} and not _is_gpt_image_2_5_model(model):
|
||||
_die("xhigh and max quality require gpt-image-2.5-flare or gpt-image-2.5-sunburst.")
|
||||
|
||||
|
||||
def _validate_background(background: Optional[str]) -> None:
|
||||
@@ -278,13 +278,20 @@ def _validate_model(model: str) -> None:
|
||||
if GPT_IMAGE_MODEL_PREFIX not in model:
|
||||
_die(
|
||||
"model must be a GPT Image model name containing 'gpt-image-' "
|
||||
"(for example gpt-image-2, openai/gpt-image-2, gpt-image-1.5, "
|
||||
"(for example gpt-image-2.5-flare, gpt-image-2.5-sunburst, gpt-image-2, "
|
||||
"gpt-image-1, or gpt-image-1-mini)."
|
||||
)
|
||||
|
||||
|
||||
def _is_gpt_image_2_model(model: str) -> bool:
|
||||
return GPT_IMAGE_2_MODEL in model
|
||||
return bool(re.search(r"(?:^|/)gpt-image-2(?:-\d{4}-\d{2}-\d{2})?(?:/|$)", model))
|
||||
|
||||
|
||||
def _is_gpt_image_2_5_model(model: str) -> bool:
|
||||
return bool(re.search(
|
||||
r"(?:^|/)gpt-image-2\.5-(?:flare|sunburst)(?:-\d{4}-\d{2}-\d{2})?(?:/|$)",
|
||||
model,
|
||||
))
|
||||
|
||||
|
||||
def _validate_transparency(background: Optional[str], output_format: str) -> None:
|
||||
@@ -302,8 +309,8 @@ def _validate_model_specific_options(
|
||||
return
|
||||
if background == "transparent":
|
||||
_die(
|
||||
"transparent backgrounds are not supported in gpt-image-2, the latest model. "
|
||||
"Use --model gpt-image-1.5 --background transparent --output-format png instead."
|
||||
"transparent backgrounds are not supported in gpt-image-2. "
|
||||
"Use --model gpt-image-2.5-flare --background transparent --output-format png instead."
|
||||
)
|
||||
if input_fidelity is not None:
|
||||
_die(
|
||||
@@ -321,7 +328,7 @@ def _validate_generate_payload(payload: Dict[str, Any]) -> None:
|
||||
quality = str(payload.get("quality", DEFAULT_QUALITY))
|
||||
background = payload.get("background")
|
||||
_validate_size(size, model)
|
||||
_validate_quality(quality)
|
||||
_validate_quality(quality, model)
|
||||
_validate_background(background)
|
||||
_validate_model_specific_options(model=model, background=background)
|
||||
oc = payload.get("output_compression")
|
||||
@@ -948,7 +955,7 @@ def main() -> int:
|
||||
|
||||
_validate_model(args.model)
|
||||
_validate_size(args.size, args.model)
|
||||
_validate_quality(args.quality)
|
||||
_validate_quality(args.quality, args.model)
|
||||
_validate_background(args.background)
|
||||
_validate_model_specific_options(
|
||||
model=args.model,
|
||||
|
||||
@@ -0,0 +1,119 @@
|
||||
"""Offline regression checks for GPT Image model requests."""
|
||||
|
||||
import contextlib
|
||||
import io
|
||||
import json
|
||||
from pathlib import Path
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from unittest.mock import patch
|
||||
|
||||
sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "skills/codex-ppt/scripts"))
|
||||
import image_gen
|
||||
import codex_ppt_runtime
|
||||
|
||||
|
||||
class ImageModelTests(unittest.TestCase):
|
||||
def test_new_models_accept_quality_and_custom_size(self):
|
||||
for model in (
|
||||
"gpt-image-2.5-flare",
|
||||
"gpt-image-2.5-sunburst",
|
||||
"openai/gpt-image-2.5-flare-2026-09-08",
|
||||
"openai/gpt-image-2.5-sunburst/edit",
|
||||
):
|
||||
for quality in ("xhigh", "max"):
|
||||
with self.subTest(model=model, quality=quality):
|
||||
image_gen._validate_generate_payload({
|
||||
"model": model, "quality": quality,
|
||||
"size": "2560x1440", "background": "transparent",
|
||||
})
|
||||
|
||||
def test_legacy_models_reject_new_quality(self):
|
||||
for model in ("gpt-image-2", "openai/gpt-image-2/edit", "gpt-image-1.5"):
|
||||
for quality in ("xhigh", "max"):
|
||||
with self.subTest(model=model, quality=quality), self.assertRaises(SystemExit):
|
||||
image_gen._validate_quality(quality, model)
|
||||
|
||||
def test_unknown_model_does_not_inherit_new_quality(self):
|
||||
for model in ("gpt-image-2.5", "gpt-image-2.5-flare-invalid", "gpt-image-20"):
|
||||
with self.subTest(model=model), self.assertRaises(SystemExit):
|
||||
image_gen._validate_quality("max", model)
|
||||
|
||||
def test_legacy_transparency_and_fidelity_rules(self):
|
||||
for model in ("gpt-image-2", "openai/gpt-image-2-2026-04-21/edit"):
|
||||
with self.subTest(model=model), self.assertRaises(SystemExit):
|
||||
image_gen._validate_model_specific_options(model=model, background="transparent")
|
||||
with self.subTest(model=model), self.assertRaises(SystemExit):
|
||||
image_gen._validate_model_specific_options(model=model, background=None, input_fidelity="high")
|
||||
image_gen._validate_model_specific_options(model="gpt-image-1.5", background="transparent")
|
||||
|
||||
def test_size_constraints_remain_enforced(self):
|
||||
for model in ("gpt-image-2.5-flare", "gpt-image-2.5-sunburst", "gpt-image-2"):
|
||||
image_gen._validate_size("3840x2160", model)
|
||||
for size in ("4096x2160", "1025x1024", "3840x3840", "3840x1024", "256x256"):
|
||||
with self.subTest(model=model, size=size), self.assertRaises(SystemExit):
|
||||
image_gen._validate_size(size, model)
|
||||
|
||||
def run_cli(self, *args):
|
||||
output = io.StringIO()
|
||||
with (
|
||||
patch.object(sys, "argv", ["image_gen.py", *args]),
|
||||
patch.object(image_gen, "_load_runtime_env"),
|
||||
patch.dict("os.environ", {"OPENAI_BASE_URL": "https://api.openai.com/v1"}, clear=True),
|
||||
contextlib.redirect_stdout(output),
|
||||
):
|
||||
self.assertEqual(image_gen.main(), 0)
|
||||
return json.loads(output.getvalue())
|
||||
|
||||
def test_cli_defaults_preserve_size_and_quality(self):
|
||||
result = self.run_cli("generate", "--prompt", "slide", "--dry-run")
|
||||
self.assertEqual(result["model"], "gpt-image-2.5-flare")
|
||||
self.assertEqual(result["model"], codex_ppt_runtime.DEFAULT_MODEL)
|
||||
self.assertEqual(result["size"], "2560x1440")
|
||||
self.assertEqual(result["quality"], "medium")
|
||||
|
||||
def test_generate_and_edit_transparent_requests(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
image = Path(temp) / "reference.png"
|
||||
image.write_bytes(b"reference")
|
||||
for command in (("generate",), ("edit", "--image", str(image))):
|
||||
for fmt in ("png", "webp"):
|
||||
with self.subTest(command=command[0], fmt=fmt):
|
||||
result = self.run_cli(
|
||||
*command, "--prompt", "slide",
|
||||
"--model", "gpt-image-2.5-sunburst",
|
||||
"--quality", "max", "--background", "transparent",
|
||||
"--output-format", fmt,
|
||||
"--out", str(Path(temp) / f"out.{fmt}"), "--dry-run",
|
||||
)
|
||||
self.assertEqual(result["model"], "gpt-image-2.5-sunburst")
|
||||
self.assertEqual(result["quality"], "max")
|
||||
self.assertEqual(result["background"], "transparent")
|
||||
self.assertEqual(result["output_format"], fmt)
|
||||
|
||||
def test_transparent_jpeg_is_rejected(self):
|
||||
with self.assertRaises(SystemExit):
|
||||
self.run_cli("generate", "--prompt", "slide", "--background", "transparent", "--output-format", "jpeg", "--dry-run")
|
||||
|
||||
def test_batch_overrides_validate_effective_model(self):
|
||||
with tempfile.TemporaryDirectory() as temp:
|
||||
jobs = Path(temp) / "jobs.jsonl"
|
||||
job = {
|
||||
"prompt": "slide", "model": "gpt-image-2.5-sunburst",
|
||||
"quality": "xhigh", "background": "transparent", "output_format": "webp",
|
||||
}
|
||||
jobs.write_text(json.dumps(job) + "\n")
|
||||
args = ("generate-batch", "--input", str(jobs), "--out-dir", temp, "--dry-run")
|
||||
result = self.run_cli(*args)
|
||||
self.assertEqual(result["model"], job["model"])
|
||||
self.assertEqual(result["quality"], "xhigh")
|
||||
self.assertEqual(result["output_format"], "webp")
|
||||
job["model"] = "gpt-image-2"
|
||||
jobs.write_text(json.dumps(job) + "\n")
|
||||
with self.assertRaises(SystemExit):
|
||||
self.run_cli(*args)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user