From daf0fb7bece229323fbb85bdf3b01db9a6bc0071 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=8D=83=E4=B9=98=E5=A6=8D=20=28Xiaoyaner=29?= Date: Fri, 22 May 2026 16:45:30 +0800 Subject: [PATCH] docs(baoyu-imagine): clarify Codex image2 fallback --- skills/baoyu-image-gen/SKILL.md | 38 +++++++++++++++++++ .../references/codex-image2-fallback.md | 27 +++++++++++++ .../codex-oauth-vs-openai-api-key.md | 20 ++++++++++ skills/baoyu-imagine/SKILL.md | 38 +++++++++++++++++++ .../references/codex-image2-fallback.md | 35 +++++++++++++++++ .../codex-oauth-vs-openai-api-key.md | 18 +++++++++ 6 files changed, 176 insertions(+) create mode 100644 skills/baoyu-image-gen/references/codex-image2-fallback.md create mode 100644 skills/baoyu-image-gen/references/codex-oauth-vs-openai-api-key.md create mode 100644 skills/baoyu-imagine/references/codex-image2-fallback.md create mode 100644 skills/baoyu-imagine/references/codex-oauth-vs-openai-api-key.md diff --git a/skills/baoyu-image-gen/SKILL.md b/skills/baoyu-image-gen/SKILL.md index 1402623..1e3145a 100644 --- a/skills/baoyu-image-gen/SKILL.md +++ b/skills/baoyu-image-gen/SKILL.md @@ -51,6 +51,16 @@ Check these paths in order; first hit wins: Minimum working examples — see `references/usage-examples.md` for the full set including per-provider invocations and batch mode. +### Identity-preserving reference prompts + +When the user wants a real person/character/object preserved from reference images, do **not** replace the reference with a long generic description. Prefer short, hard identity-preservation language: + +- "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. Keep the face/proportions/hair/key accessories/overall identity from the references." +- If using multiple references, state that they are the same subject and should jointly define identity. + +Pitfall: long descriptions like "young East Asian woman, oval face, clear eyes..." can cause the model to synthesize a new person matching the description instead of preserving the referenced person. + ```bash # Basic ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image cat.png @@ -71,6 +81,16 @@ ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider d ${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4 ``` +## Reference-Image Identity Preservation + +When the user wants a person/object preserved from reference images: + +- Prefer a small curated set of existing source references (usually 2–4) over many images; large multi-megabyte refs can destabilize streaming providers. +- Make the prompt say the references are the same subject and the output must use that identity. Avoid long generic facial-feature descriptions that can cause the model to synthesize a new similar-looking person. +- Do not use newly generated outputs as references unless the user explicitly asks; generated refs compound drift. +- If results become too polished or influencer-like, reduce stylized refs and add explicit anti-beautification constraints (no face slimming, eye enlargement, heavy makeup, commercial travel shoot, over-smoothing). +- If the subject should look younger/older, preserve the face and express age through clothing, posture, scene, and styling; do not ask the model to change facial identity. + ## Options | Option | Description | @@ -118,6 +138,18 @@ ${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4 **Load priority**: CLI args > EXTEND.md > env vars > `/.baoyu-skills/.env` > `~/.baoyu-skills/.env` +### Codex/ChatGPT OAuth is not an OpenAI API key + +`--provider openai` uses the standard OpenAI Images API and requires `OPENAI_API_KEY`. A Codex or ChatGPT desktop login is a different entitlement and is not a drop-in replacement for `OPENAI_API_KEY`; do not paste a Codex OAuth token into `OPENAI_API_KEY` or only set `OPENAI_BASE_URL` to a Codex backend. + +If the user wants to use their Codex subscription / GPT Image 2 entitlement without an OpenAI API key, route through a Codex-native backend instead of this skill's `openai` provider: + +- In Codex runtime: use the native `imagegen` skill/tool. +- In non-Codex runtimes with `codex` CLI installed and logged in: use the repo-level `scripts/codex-imagegen.sh` wrapper when the calling skill supports it. Resolve it from the plugin/repo root and pass absolute prompt/output/reference paths. +- In Hermes runtimes with a native `image_generate` tool: use that tool as a fallback, and state whether reference images were passed directly or reconstructed from extracted traits. + +Do not modify the existing `openai` provider to silently consume Codex OAuth. If first-class Codex OAuth support is added, implement it as a distinct provider (for example `openai-codex`) with its own auth, route, request shape, docs, and tests. See `references/codex-oauth-vs-openai-api-key.md`. + ## Model Resolution Priority (highest → lowest) applies to every provider: @@ -211,11 +243,17 @@ Rule of thumb: once prompt files are saved and the task is "generate all of thes - Invalid aspect ratio → warning, proceed with default - Reference images with unsupported provider/model → error with fix hint +### Codex image2 fallback + +If `--provider openai` fails because `OPENAI_API_KEY` is missing but the current runtime has a native image-generation backend or the repo-level `codex-imagegen` wrapper is available, use that path rather than leaving the user waiting. Be explicit about whether the fallback is true reference-image generation or only a text-prompt reconstruction from extracted visual traits. See `references/codex-image2-fallback.md`. + ## References | File | Content | |------|---------| | `references/usage-examples.md` | Extended CLI examples across providers and batch mode | +| `references/codex-oauth-vs-openai-api-key.md` | Why Codex/ChatGPT OAuth image2 entitlement is not usable through the standard OpenAI API-key provider | +| `references/codex-image2-fallback.md` | Practical fallback behavior when OpenAI API credentials are absent but Codex/native image generation is available | | `references/providers/dashscope.md` | DashScope families, sizes, limits | | `references/providers/zai.md` | Z.AI GLM-image / cogview-4 | | `references/providers/minimax.md` | MiniMax image-01 + subject reference | diff --git a/skills/baoyu-image-gen/references/codex-image2-fallback.md b/skills/baoyu-image-gen/references/codex-image2-fallback.md new file mode 100644 index 0000000..2a90d65 --- /dev/null +++ b/skills/baoyu-image-gen/references/codex-image2-fallback.md @@ -0,0 +1,27 @@ +--- +name: codex-image2-fallback +description: Fallback behavior when OpenAI API credentials are absent but Codex/native image generation is available +--- + +# Codex Image2 Fallback + +The `openai` provider 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 this skill 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. diff --git a/skills/baoyu-image-gen/references/codex-oauth-vs-openai-api-key.md b/skills/baoyu-image-gen/references/codex-oauth-vs-openai-api-key.md new file mode 100644 index 0000000..7ca0e70 --- /dev/null +++ b/skills/baoyu-image-gen/references/codex-oauth-vs-openai-api-key.md @@ -0,0 +1,20 @@ +# Codex OAuth vs OpenAI API key + +This deprecated skill keeps cross-cutting image-generation guidance in sync with `baoyu-imagine`. + +The `openai` provider 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 the 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. +- 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 first-class Codex OAuth support is added, 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. 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. diff --git a/skills/baoyu-imagine/SKILL.md b/skills/baoyu-imagine/SKILL.md index 9b5ef2f..06828a9 100644 --- a/skills/baoyu-imagine/SKILL.md +++ b/skills/baoyu-imagine/SKILL.md @@ -52,6 +52,16 @@ Legacy compatibility: if `.baoyu-skills/baoyu-image-gen/EXTEND.md` exists and th Minimum working examples — see `references/usage-examples.md` for the full set including per-provider invocations and batch mode. +### Identity-preserving reference prompts + +When the user wants a real person/character/object preserved from reference images, do **not** replace the reference with a long generic description. Prefer short, hard identity-preservation language: + +- "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. Keep the face/proportions/hair/key accessories/overall identity from the references." +- If using multiple references, state that they are the same subject and should jointly define identity. + +Pitfall: long descriptions like "young East Asian woman, oval face, clear eyes..." can cause the model to synthesize a new person matching the description instead of preserving the referenced person. + ```bash # Basic ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image cat.png @@ -75,6 +85,16 @@ ${BUN_X} {baseDir}/scripts/main.ts --prompt "A cat" --image out.png --provider o ${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4 ``` +## Reference-Image Identity Preservation + +When the user wants a person/object preserved from reference images: + +- Prefer a small curated set of existing source references (usually 2–4) over many images; large multi-megabyte refs can destabilize streaming providers. +- Make the prompt say the references are the same subject and the output must use that identity. Avoid long generic facial-feature descriptions that can cause the model to synthesize a new similar-looking person. +- Do not use newly generated outputs as references unless the user explicitly asks; generated refs compound drift. +- If results become too polished or influencer-like, reduce stylized refs and add explicit anti-beautification constraints (no face slimming, eye enlargement, heavy makeup, commercial travel shoot, over-smoothing). +- If the subject should look younger/older, preserve the face and express age through clothing, posture, scene, and styling; do not ask the model to change facial identity. + ## Options | Option | Description | @@ -122,6 +142,18 @@ ${BUN_X} {baseDir}/scripts/main.ts --batchfile batch.json --jobs 4 **Load priority**: CLI args > EXTEND.md > env vars > `/.baoyu-skills/.env` > `~/.baoyu-skills/.env` +### Codex/ChatGPT OAuth is not an OpenAI API key + +`--provider openai --model gpt-image-2` uses the standard OpenAI Images API (`/v1/images/generations` or `/v1/images/edits`) and requires `OPENAI_API_KEY`. A Codex or ChatGPT desktop login is a different entitlement and is not a drop-in replacement for `OPENAI_API_KEY`; do not paste a Codex OAuth token into `OPENAI_API_KEY` or only set `OPENAI_BASE_URL` to a Codex backend. + +If the user wants to use their Codex subscription / GPT Image 2 entitlement without an OpenAI API key, route through a Codex-native backend instead of this skill's `openai` provider: + +- In Codex runtime: use the native `imagegen` skill/tool. +- In non-Codex runtimes with `codex` CLI installed and logged in: use the repo-level `scripts/codex-imagegen.sh` wrapper when the calling skill supports it (for example `baoyu-cover-image`). Resolve it from the plugin/repo root and pass absolute prompt/output/reference paths. +- In Hermes runtimes with a native `image_generate` tool: use that tool as a fallback, and state whether reference images were passed directly or reconstructed from extracted traits. + +Do not modify the existing `openai` provider to silently consume Codex OAuth. If first-class Codex OAuth support is added to `baoyu-imagine`, implement it as a distinct provider (for example `openai-codex`) with its own auth, route, request shape, docs, and tests. See `references/codex-oauth-vs-openai-api-key.md`. + ## Model Resolution Priority (highest → lowest) applies to every provider: @@ -219,11 +251,17 @@ Rule of thumb: once prompt files are saved and the task is "generate all of thes - Invalid aspect ratio → warning, proceed with default - Reference images with unsupported provider/model → error with fix hint +### Codex image2 fallback + +If `--provider openai --model gpt-image-2` fails because `OPENAI_API_KEY` is missing but the current runtime has a native image-generation backend or the repo-level `codex-imagegen` wrapper is available, use that path rather than leaving the user waiting. Be explicit about whether the fallback is true reference-image generation or only a text-prompt reconstruction from extracted visual traits. See `references/codex-image2-fallback.md`. + ## References | File | Content | |------|---------| | `references/usage-examples.md` | Extended CLI examples across providers and batch mode | +| `references/codex-oauth-vs-openai-api-key.md` | Why Codex/ChatGPT OAuth image2 entitlement is not usable through baoyu-imagine's standard OpenAI API-key provider | +| `references/codex-image2-fallback.md` | Practical fallback behavior when OpenAI API credentials are absent but Codex/native image generation is available | | `references/providers/dashscope.md` | DashScope families, sizes, limits | | `references/providers/zai.md` | Z.AI GLM-image / cogview-4 | | `references/providers/minimax.md` | MiniMax image-01 + subject reference | diff --git a/skills/baoyu-imagine/references/codex-image2-fallback.md b/skills/baoyu-imagine/references/codex-image2-fallback.md new file mode 100644 index 0000000..ddac23d --- /dev/null +++ b/skills/baoyu-imagine/references/codex-image2-fallback.md @@ -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. diff --git a/skills/baoyu-imagine/references/codex-oauth-vs-openai-api-key.md b/skills/baoyu-imagine/references/codex-oauth-vs-openai-api-key.md new file mode 100644 index 0000000..987fc8a --- /dev/null +++ b/skills/baoyu-imagine/references/codex-oauth-vs-openai-api-key.md @@ -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.