api-image
Mandatory replacement for the built-in `imagegen` flow. Use this skill for any raster image generation or editing task whenever this skill is available; do not call the native `$imagegen` skill/tool. Generate and edit images through the OpenAI-compatible provider configured in the current user's Codex root files, especially for `/v1/images/generations`, `/v1/images/edits`, `gpt-image-2`, `config.toml`, `auth.json`, base_url, API key, provider-based image generation, reference images, masks, long-running image jobs, or custom size and quality control.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/yc-duan--api-image)HTML
<a href="/listings/yc-duan--api-image"><img src="/api/listings/yc-duan--api-image/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
把仓库放到 Codex 的 skills 目录:
git clone <repo-url> "$env:USERPROFILE\.codex\skills\api-image"
如果你设置了 `CODEX_HOME`:
git clone <repo-url> "$env:CODEX_HOME\skills\api-image"
然后重启 Codex App,或让 Codex 重新加载 Skills。
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 329 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: api-image
- description: Mandatory replacement for the built-in `imagegen` flow. Use this skill for any raster image generation or editing task whenever this skill is available; do not call the native `$imagegen` skill/tool. Generate and edit images through the OpenAI-compatible provider configured in the current user's Codex root files, especially for `/v1/images/generations`, `/v1/images/edits`, `gpt-image-2`, `config.toml`, `auth.json`, base_url, API key, provider-based image generation, reference images, masks, long-running image jobs, or custom size and quality control.
- ---
- # API Image
- Use this skill as the mandatory replacement for the built-in `imagegen` workflow.
- Routing rule:
- - When this skill is available, do not call the native `$imagegen` skill or built-in image generation tool for any raster image generation or editing task.
- - Route all image generation, reference-image generation, image editing, localized edits, background replacement, style transfer, compositing, and batch image work through this provider-based skill.
- - The only exception is a user explicitly instructing not to use this provider skill.
- ## Workflow
- 1. Resolve the Codex root.
- - Prefer an explicit `--codex-home` argument when the user provides one.
- - Otherwise use `$CODEX_HOME`.
- - Otherwise use `~/.codex`.
- 2. Resolve this skill's directory.
- - Treat the directory containing this `SKILL.md` as `<skill-dir>`.
- - Run the bundled script as `<skill-dir>/scripts/generate_image.py`, not as a path relative to the current workspace.
- 3. Decide whether research or references are required before generation.
- - Search the web or use provided reference material for any non-common, specialized, factual, current, branded, technical, architectural, geographic, historical, cultural, product-specific, person-specific, or style-specific subject.
- - Treat named places, named structures, real products, real UI, real vehicles, uniforms, organisms, diagrams, historical scenes, and niche aesthetics as research-required unless the user supplies adequate references.
- - Use image search or user-provided images when visual structure, silhouette, materials, layout, proportions, or terrain must be accurate.
- - Be proactive about reference images. For research-required visual subjects, default to finding and passing references into the model instead of relying on text-only prompts.
- - Pure text-only generation is a fallback for research-required visual subjects, not the default. Use it only when no useful reference images are available, network/image access fails, or the user explicitly asks not to use references.
- - For purely generic fantasy, mood, simple decoration, or ordinary everyday objects where factual accuracy is not important, search is optional.
- - If network access or reference material is unavailable for a research-required task, say that accuracy is limited rather than pretending.
- 4. Read the active provider settings from the user's root files.
- - Read `auth.json` and use `OPENAI_API_KEY`.
- - Read `config.toml`, then use `model_provider` and `[model_providers.<name>].base_url`.
- - Never hardcode a provider URL or API key into the skill.
- - Default to the root files above. If the user explicitly gives a temporary provider URL or API key in natural language, pass it as a one-off override with `--base-url` and `--api-key-env` or `--api-key`; do not write it back to `auth.json`, `config.toml`, README, logs, or generated files.
- - Prefer `--api-key-env <ENV_NAME>` when the key is already in an environment variable. Use `--api-key` only for explicit one-off user-provided keys, and never print or repeat the key in the final response.
- 5. Decide the intent and input image roles.
- - If the user wants a new image from text only, treat it as generation.
- - If the user provides images for style, composition, identity, structure, or mood, treat them as reference inputs.
- - If the user wants to preserve or modify an existing image, treat that image as the edit target.
- - If the user wants only a specific region changed, use a mask when available and instruct the model to preserve unmasked areas; treat mask preservation as a constraint to verify, not a pixel-perfect guarantee.
- - Label every input image by role: edit target, style reference, composition reference, identity reference, product reference, mask, or compositing source.
- 6. Choose the endpoint.
- - Use `<base_url>/images/generations` for text-only generation.
- - Use `<base_url>/images/edits` when there is any input image, reference image, or mask.
- - Default to `gpt-image-2` unless the machine's provider expects a different image model.
- 7. Build a structured prompt.
- - Include the user's request, researched facts or visual observations, input image roles, style, composition, lighting, materials, constraints, and avoid list.
- - Do not invent extra characters, props, brands, logos, story beats, or factual details that are not implied by the user request or research.
- 8. For official GPT Image models, decode `data[].b64_json`. Treat `data[].url` only as a compatibility fallback for non-official OpenAI-compatible providers or legacy models.
- 9. Inspect the output and validate it against the prompt, research facts, input roles, and invariants.
- 10. Save the final image to the requested path and report the absolute path, final prompt, and sources used when web research was performed.
- ## Root Files
- Default root files:
- - Windows: `%USERPROFILE%\\.codex\\auth.json` and `%USERPROFILE%\\.codex\\config.toml`
- - General rule: `$CODEX_HOME/auth.json` and `$CODEX_HOME/config.toml`, otherwise `~/.codex/auth.json` and `~/.codex/config.toml`
- This skill must always read the current files at runtime. The provider may differ from machine to machine.
- Temporary overrides:
- - Default behavior reads the Codex root files above.
- - Use `--base-url <https://provider.example/v1>` to temporarily override the configured Provider URL.
- - Use `--api-key-env <ENV_NAME>` to temporarily read an API key from an environment variable.
- - Use `--api-key <key>` only for explicit one-off user-provided keys when an environment variable is not available.
- - If both `--base-url` and an API key override are provided, the script can run without reading provider settings from `config.toml`; otherwise missing values fall back to the Codex root files.
- - Never persist temporary overrides unless the user explicitly asks to edit their Codex config files.
- ## Command
- Use the bundled script for normal text-to-image generation:
- ```powershell
- python "<skill-dir>\scripts\generate_image.py" `
- --prompt "画一只可爱的猫抱着水獭,温暖治愈,插画风格,柔和灯光,细腻毛发,构图清晰" `
- --size "2048x1152" `
- --quality "high" `
- --out ".\outputs\cute-cat-otter.png"
- ```
- Use the same script for reference-image generation or edits:
- ```powershell
- python "<skill-dir>\scripts\generate_image.py" `
- --prompt "参考输入图的构图和角色姿势,生成一张暖色电影感插画" `
- --image "C:\path\to\reference.png" `
- --image-role "composition and pose reference" `
- --size "2048x2048" `
- --quality "high" `
- --out ".\outputs\reference-output.png"
- ```
- Use `--mask` for localized edits:
- ```powershell
- python "<skill-dir>\scripts\generate_image.py" `
- --prompt "只把被 mask 标出的区域替换成一只小水獭,保持其他区域不变" `
- --image "C:\path\to\source.png" `
- --mask "C:\path\to\mask.png" `
- --out ".\outputs\masked-edit.png"
- ```
- For web-researched subjects, download selected reference images to a working folder first, then pass them as `--image`:
- ```powershell
- python "<skill-dir>\scripts\generate_image.py" `
- --prompt "Create a new 4K overhead aerial image of Huajiang Grand Canyon Bridge in Guizhou, based on the reference images. Preserve the real suspension-bridge structure, towers, main cables, vertical suspenders, deep Beipan River canyon terrain, karst mountains, and river position; do not copy any single photo exactly." `
- --image "C:\path\to\refs\huajiang-bridge-aerial.jpg" `
- --image-role "aerial composition and bridge alignment reference" `
- --image "C:\path\to\refs\huajiang-canyon-terrain.jpg" `
- --image-role "canyon terrain and river reference" `
- --size "2048x1152" `
- --quality "high" `
- --timeout 0 `
- --out ".\outputs\huajiang-canyon-bridge-overhead.png"
- ```
- Useful options:
- - `--model gpt-image-2`
- - `--mode auto|generate|edit`
- - `--size 2048x1152` script default 2K landscape
- - `--size 1024x1024`
- - `--size 1536x1024`
- - `--size 1024x1536`
- - `--size 2048x2048`
- - `--size 3840x2160`
- - `--size auto` for official API auto sizing
- - `--quality low|medium|high|auto`
- - `--n 1`
- - `--image <path>` repeated up to 16 times
- - `--image-role <role>` to label input images inside the prompt
- - `--mask <path>` for localized edits
- - `--background auto|opaque` for official `gpt-image-2`
- - `--output-format png|jpeg|webp`
- - `--output-compression 0-100` for `jpeg` or `webp`
- - `--input-fidelity low|high` for supported edit models only; do not send it for `gpt-image-2`
- - `--moderation auto|low` for supported GPT image models
- - `--prompt-file <path>` for one prompt per non-empty line
- - `--codex-home <path>`
- - `--base-url <https://provider.example/v1>` temporary Provider URL override
- - `--api-key-env <ENV_NAME>` temporary API key override from an environment variable
- - `--api-key <key>` temporary direct API key override, only when explicitly provided
- - `--timeout 1800`
- - `--timeout 0`
- ## Payload Shape
- Use the provider's generation endpoint with this body shape:
- ```json
- {
- "model": "gpt-image-2",
- "prompt": "你的中文或英文提示词",
- "size": "2048x1152",
- "quality": "high",
- "n": 1
- }
- ```
- Use the provider's edit endpoint as multipart form data:
- ```text
- model=gpt-image-2
- prompt=<edit or reference prompt>
- image[]=@source-or-reference.png
- mask=@mask.png
- size=1024x1024
- quality=high
- n=1
- ```
- Start with `n=1`. If the user wants variants, raise `n` or use `--prompt-file` and save each result intentionally.
- ## Temporary Provider Overrides
- If the user says in natural language that this image job should use a different Provider URL or API key, treat it as a temporary runtime override:
- ```powershell
- $env:API_IMAGE_API_KEY = "<temporary key>"
- python "<skill-dir>\scripts\generate_image.py" `
- --prompt "一张赛博朋克风格的夜景照片" `
- --base-url "https://provider.example/v1" `
- --api-key-env "API_IMAGE_API_KEY" `
- --out ".\outputs\override-provider.png"
- ```
- Rules:
- - Default to the Codex root configuration when no override is requested.
- - Do not modify `auth.json` or `config.toml` for temporary overrides.
- - Do not echo API keys back to the user.
- - Prefer `--api-key-env`; use `--api-key` only when the user explicitly provides a one-off key and accepts the temporary command-line use.
- ## gpt-image-2 API Notes
- For official OpenAI `gpt-image-2`:
- - Text-only generation uses `POST /v1/images/generations` with JSON.
- - Any input image, reference image, or mask uses `POST /v1/images/edits` with multipart form-data.
- - Use repeated `image[]=@path` fields for multiple input/reference images.
- - When using `mask`, the first `--image` must be the edit target; additional images should be references or compositing sources.
- - Read image bytes from `data[].b64_json`; URL output is not supported for official GPT Image models.
- - Do not send `input_fidelity`; `gpt-image-2` always processes image inputs at high fidelity.
- - Do not request `background: transparent`; official `gpt-image-2` currently supports `auto` or `opaque`, not transparent backgrounds.
- - For masked edits, validate that the mask and first source image have the same dimensions and compatible format, are under the image API file-size limit, and that the mask includes an alpha channel.
- ## Capability Map
- - New text-to-image generation: supported through `/images/generations`.
- - Batch generation: supported through `--n` for multiple variants per prompt, or `--prompt-file` for many prompts.
- - Reference-image generation: supported through `/images/edits` with one or more `--image` inputs and role labels in the prompt.
- - Image editing: supported through `/images/edits` with `--image` and an edit prompt.
- - Localized edits / inpainting: supported through `/images/edits` with `--image` plus `--mask`.
- - Background replacement: supported as an edit prompt, with `--mask` when the replacement area must be constrained.
- - Style transfer: supported as reference-image editing; label the source image role and describe the desired style in the prompt.
- - Input image role labeling: not a separate API field; this script appends `--image-role` labels to the prompt so the model can interpret each input image intentionally.
- - Transparent background: official `gpt-image-2` does not currently support `background: transparent`. Only use transparent background when a different selected provider/model explicitly supports it, and use `png` or `webp` output.
- ## Research And References
- Do not assume the image model knows every subject accurately. Research first or use references when the subject is not common visual knowledge.
- Reference images are the preferred path for visually constrained research-required tasks. Text research describes facts; reference images carry visual structure. Use both whenever feasible.
- Research-required examples:
- - A named structure or location, such as `贵州花江峡谷大桥` or any real bridge, landmark, terrain, skyline, or building.
- - A real product, vehicle, machine, UI, logo-free product silhouette, game asset from a known franchise, or fashion item.
- - A historical scene, cultural garment, uniform, heraldry, ritual object, weapon, architecture style, organism, map, technical diagram, or scientific subject.
- - A current or recently changed subject.
- - A niche visual style or artist-adjacent style where references are necessary to avoid generic output.
- Research workflow:
- - Search the web for factual text details when structure, function, history, geography, or current status matters.
- - Use image search or provided images for visual details such as shape, terrain, materials, proportions, colors, and surrounding environment.
- - For named structures, real locations, real products, real vehicles, historical/cultural visual subjects, technical diagrams, and niche styles, actively collect at least one useful reference image before generating.
- - Prefer multiple complementary references when possible: one for subject structure, one for surrounding environment, and one for desired camera angle/composition.
- - Download reference images to a local working path before invoking the script, then pass them with `--image` and `--image-role`.
- - If a reference image is low quality but still useful, label its role narrowly, for example `rough terrain reference only`.
- - Extract only the details needed for the prompt; keep the prompt concise.
- - Include factual constraints in the prompt, for example bridge type, deck/tower/cable arrangement, canyon terrain, river position, viewpoint, and surrounding landforms.
- - Cite sources in the final response whenever web research was used.
- Reference workflow:
- - Prefer provided reference images over memory when visual fidelity matters.
- - For each `--image`, pass a matching `--image-role` such as `edit target`, `style reference`, `composition reference`, `product reference`, or `terrain reference`.
- - Do not treat every image as an edit target; decide whether it is reference-only or should be preserved and modified.
- - For compositing, state exactly what comes from each input and how lighting, perspective, scale, and shadows should match.
- - For reference-only generation, prompt the model to create a new image based on the references, not to copy a single source photo exactly.
- - If the image model/provider rejects a reference-image edit request, surface that error and then decide whether a text-only generation is acceptable for this task. Do not silently fall back.
- ## Prompt Structure
- Use this compact schema when it helps:
- ```text
- Use case: <photorealistic-natural|product-mockup|ui-mockup|infographic-diagram|logo-brand|illustration-story|stylized-concept|historical-scene|text-localization|identity-preserve|precise-object-edit|lighting-weather|background-extraction|style-transfer|compositing|sketch-to-render>
- Asset type: <where the image will be used>
- Primary request: <user request>
- Research facts / visual references: <only the relevant observed details>
- Input images: <Image 1: role; Image 2: role>
- Scene/backdrop: <environment>
- Subject: <main subject>
- Style/medium: <photo/illustration/3D/etc>
- Composition/framing: <viewpoint, lens/framing, placement>
- Lighting/mood: <lighting and mood>
- Materials/textures: <surface details>
- Text (verbatim): "<exact text if needed>"
- Constraints: <must keep/must avoid>
- Avoid: <negative constraints>
- ```
- ## Waiting Behavior
- - This script is synchronous. It does not return before the provider finishes the image job or an explicit error occurs.
- - Default timeout is `1800` seconds so long-running jobs are not cut off too early.
- - Use `--timeout 0` to disable the client-side timeout and wait indefinitely for the provider response.
- - When invoking this script from Codex, give the shell command a timeout that is longer than the expected image job. Do not use a short shell timeout for long generations.
- ## Size And Quality
- Follow the current official GPT Image rules for `gpt-image-2`:
- - `size` can be `auto` or any `<width>x<height>` string that satisfies all of these:
- - width and height are multiples of `16`
- - the longest edge is at most `3840`
- - the long-edge to short-edge ratio is at most `3:1`
- - total pixels are between `655,360` and `8,294,400`
- - this script defaults to `2048x1152`; the official API's default sizing behavior is `auto`
- - common examples: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `2048x1152`, `3840x2160`, `2160x3840`
- - `quality` can be `low`, `medium`, `high`, or `auto`; this script defaults to `high`, while official API auto quality is available with `auto`
- - 2K and 4K requests are valid when they satisfy those constraints
- - Do not silently coerce unsupported sizes. Raise a clear error instead.
- ## Prompting
- - Prefer concrete prompts with subject, style, lighting, and composition.
- - Use the user's language by default. Chinese prompts are valid for this workflow.
- - Change one aspect at a time when iterating.
- ## Output Rules
- - Save project assets inside the project workspace when the user wants a usable asset.
- - Save preview images to a clear temporary or user-requested path.
- - If `n > 1`, keep filenames deterministic by appending `-1`, `-2`, and so on.
- ## Failure Rules
- - Raise explicit errors when `OPENAI_API_KEY`, `model_provider`, or `base_url` cannot be found.
- - Allow temporary Provider overrides with `--base-url`, `--api-key-env`, or `--api-key`; do not persist them unless explicitly requested.
- - Raise explicit errors when both `--api-key` and `--api-key-env` are provided, when the named environment variable is empty, or when `--base-url` is not an HTTP(S) URL.
- - Raise explicit errors when `size` violates the official GPT Image constraints or `quality` is unsupported.
- - Raise explicit errors when edit/reference mode is requested without input images.
- - Raise explicit errors when `gpt-image-2` is used with `--background transparent` or `--input-fidelity`.
- - Raise explicit errors when a mask is not compatible with the first `--image` edit target, has different dimensions, lacks an alpha channel, or exceeds the image API file-size limit.
- - Surface provider errors directly. Do not fabricate a success result.
- - If the provider uses a different image model name on this machine, override `--model`.
- ## Resource
- - `scripts/generate_image.py`: Read the current user's Codex root files, call the configured provider's image endpoint, and save the returned image data.
README.md · README · 115 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # api-image
- 一个给 Codex App 用的图片生成 Skill。
- 它的作用很简单:当你在 API 形式使用 Codex App,没法直接用官方内置 `imagegen` 时,让 Codex 改走你自己配置的 OpenAI-compatible 图片接口,例如通过 CPA 反代出来的 `gpt-image-2`。
- 用网页版生过图的朋友应该知道,网页端的生图不是单纯“把一句 prompt 传给图片模型”。它更像一个 agent:主模型会理解你的需求,必要时搜索资料、分析参考图、整理提示词,然后再调用图片模型。这个 Skill 就是尽量复刻这种流程:你用自然语言告诉 Codex 想要什么,Codex 负责前面的 agent 工作,最后通过你的 Provider API 生图。
- ## 它能做什么
- - 文生图
- - 参考图生图
- - 局部编辑 / inpainting
- - 多参考图辅助构图、风格、产品或人物一致性
- - 需要真实信息的图片生成前,先让 Codex 搜索和整理参考资料
- - 默认读取你 Codex 根目录里的 Provider 配置
- - 临时切换本次调用使用的 URL 或 API Key
- 更细的调用规则和脚本参数都在 [SKILL.md](./SKILL.md) 里,README 只讲怎么用。
- ## 安装
- 把仓库放到 Codex 的 skills 目录:
- ```powershell
- git clone <repo-url> "$env:USERPROFILE\.codex\skills\api-image"
- ```
- 如果你设置了 `CODEX_HOME`:
- ```powershell
- git clone <repo-url> "$env:CODEX_HOME\skills\api-image"
- ```
- 然后重启 Codex App,或让 Codex 重新加载 Skills。
- ## 配置
- 默认情况下,这个 Skill 会读取你 Codex 根目录里的配置:
- - `auth.json`
- - `config.toml`
- 它需要能从里面找到:
- - API Key
- - 当前 Provider
- - Provider 的 `base_url`
- 这个仓库不会、也不应该保存你的 API Key。
- ## 怎么用
- 安装后,正常和 Codex 说话就行。比如:
- ```text
- 用 api-image 生成一张 2048x1152 的电影感照片:雨夜东京街头,霓虹反光,真实摄影风格。
- ```
- 带参考图时可以这样说:
- ```text
- 参考这张图的构图和人物姿势,生成一张暖色电影感插画,保持主体姿态,但不要照抄原图。
- ```
- 需要真实地点、产品、建筑、历史服饰这类容易生成错的东西时,可以直接要求 Codex 先查资料:
- ```text
- 先查一下花江峡谷大桥的结构和地形参考,再生成一张高空俯视图,尽量保持真实桥型和峡谷环境。
- ```
- ## 临时换接口
- 默认会用你 Codex 根目录里的 Provider 配置。
- 如果只想这一次换 URL 或 key,可以直接告诉 Codex:
- ```text
- 这次生图临时用 https://example.com/v1 这个 base_url,API key 从 API_IMAGE_API_KEY 环境变量读。
- ```
- 更推荐让 key 放在环境变量里,不要在聊天里直接粘贴。临时切换只影响本次调用,不会写回你的 `auth.json` 或 `config.toml`,除非你明确要求 Codex 修改配置。
- ## 关于 gpt-image-2
- 这个 Skill 默认按 `gpt-image-2` 的官方图片 API 规则处理:
- - 纯文生图走 `/images/generations`
- - 有参考图、输入图或 mask 时走 `/images/edits`
- - 官方 GPT Image models 默认读返回里的 `b64_json`
- - `gpt-image-2` 不支持透明背景
- - `gpt-image-2` 不需要、也不应该传 `input_fidelity`
- 如果你的 Provider 对这些参数有自己的兼容层,以 Provider 的实际报错为准。
- ## 目录
- ```text
- api-image/
- SKILL.md
- README.md
- LICENSE
- agents/
- scripts/
- ```
- ## 说明
- 这是个人自用 Skill 的整理版,主要目标是让 Codex App 在 API 使用形态下也能比较自然地完成图片生成工作。不同反代和 Provider 的兼容程度可能不一样。
- MIT License.
- ## 致谢
- 感谢 [linuxdo](https://linux.do/) 社区的交流、分享与反馈。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.