docs(baoyu-imagine): clarify Codex image2 fallback

2026-08-06 00:43:03 +08:00 · 2026-05-22 16:45:30 +08:00
parent adbfa3036b
commit daf0fb7bec
6 changed files with 176 additions and 0 deletions
@@ -0,0 +1,35 @@
+---
+name: codex-image2-fallback
+description: Fallback behavior when baoyu-imagine lacks OpenAI API credentials but Codex/native image generation is available
+---
+
+# Codex Image2 Fallback
+
+When using `baoyu-imagine` with `--provider openai --model gpt-image-2`, the CLI can fail with:
+
+```text
+OPENAI_API_KEY is required. Codex/ChatGPT desktop login does not automatically grant OpenAI Images API access to this script.
+```
+
+This is expected. The `openai` provider uses the public OpenAI Images API and needs `OPENAI_API_KEY`. Codex / ChatGPT image2 entitlement is a separate runtime-native path.
+
+## Practical fallback pattern
+
+1. Try `baoyu-imagine` when provider credentials are available.
+2. If it fails only because `OPENAI_API_KEY` is missing, do not leave the user waiting.
+3. Prefer a Codex/native raster backend in this order:
+   - Codex runtime native `imagegen` skill/tool, if available.
+   - Repo-level `scripts/codex-imagegen.sh`, if `codex` CLI is installed/logged in and the calling skill supports the wrapper.
+   - Hermes native `image_generate`, if available.
+4. Be transparent about reference-image behavior:
+   - If the fallback backend accepts references, pass the reference images.
+   - If it does not, derive a concise identity-preserving prompt from the references and state that it is a text-description fallback, not strict reference-image editing.
+5. Return the generated media path or structured backend error promptly.
+
+## User-facing wording
+
+Use concise wording such as:
+
+> The OpenAI API path needs `OPENAI_API_KEY`; Codex login is a separate image2 backend. I used the available Codex/native image backend instead. Reference images were [passed directly / reconstructed from visual traits].
+
+Avoid implying that `baoyu-imagine --provider openai` can use Codex OAuth without a dedicated provider implementation.
@@ -0,0 +1,18 @@
+# Codex OAuth vs OpenAI API key for baoyu-imagine
+
+`baoyu-imagine --provider openai` uses the standard OpenAI Images API and requires `OPENAI_API_KEY`. It calls OpenAI-compatible image endpoints such as `/images/generations` and `/images/edits`.
+
+Codex / ChatGPT login is different. Codex image generation is driven by Codex OAuth and the Codex runtime's `image_gen` capability, not by the public OpenAI Images API key path. A Codex OAuth token is not a drop-in replacement for `OPENAI_API_KEY`, and setting `OPENAI_BASE_URL` to a Codex backend will not make baoyu-imagine's existing `openai` provider work because the auth, route, and payload shape differ.
+
+## What to use instead
+
+- If running inside Codex and the native `imagegen` skill/tool is available, use it directly.
+- If running outside Codex but the `codex` CLI is installed and logged in, use the repo-level `scripts/codex-imagegen.sh` wrapper when the calling skill supports it. The wrapper invokes `codex exec` and the Codex `image_gen` tool; no `OPENAI_API_KEY` is required.
+- If running inside Hermes and a native `image_generate` tool is available, use that as a runtime-native fallback. Be explicit about whether reference images are passed directly or only reconstructed from extracted traits.
+- If the user wants `baoyu-imagine` itself to support Codex OAuth, add a distinct provider such as `openai-codex` rather than modifying the existing `openai` provider.
+
+## Reference-image prompting note
+
+When using actual reference images for identity preservation, avoid long generic descriptions of the subject. Long descriptions can cause the model to synthesize a new similar-looking person/object. Prefer direct wording:
+
+> Use the person/object in the reference image(s) as the same identity. Do not redesign it or create a similar-looking new subject. Only change scene, clothing, pose, lighting, rendering style, and composition.