ImageAPI

imageapi is a Codex skill for text-to-image generation through the configured gzxsy.vip image endpoint.

It is designed for agent use, not manual one-off scripting. The skill:

• converts the user request into an optimized English prompt
• supports optional reference images and automatically switches to the edit flow when references are present
• supports size and quality controls
• returns a single JSON object on stdout for both success and failure
• keeps the API key in local config only

What it does

• Text-to-image generation
• Reference-image-conditioned editing/generation
• Structured output for agents
• Clear failure codes for config, prompt, reference-image, output, and API errors

What it does not do

• Mask-based editing
• Background removal
• Batch generation
• Cloud-side key management

Installation

For Codex users

1. Install or sync the skill into the local Codex skills directory: C:\Users\BenLi\.codex\skills\imageapi
2. Ensure config.json exists next to config.example.json.
3. Fill in your local api_key in config.json.
4. Restart or reload Codex so the skill is discoverable.

One-line install

Use this one-line command to install or update the skill from GitHub on a machine that already has the target agent runtime and git access:

powershell -NoProfile -ExecutionPolicy Bypass -Command "$ErrorActionPreference='Stop'; $root='C:\Users\BenLi'; if (-not (Test-Path \"$root\.codex\skills\imageapi\")) { git clone https://github.com/CercaTrovato/imageapi.git \"$root\.codex\skills\imageapi\" } else { git -C \"$root\.codex\skills\imageapi\" pull --ff-only }"

For an agent to install itself from a prompt, give it the command above and instruct it to run it unchanged.

One-line install for Claude / OpenCode

These agents can use their own skill directories with the same repository source:

• Claude:

  powershell -NoProfile -ExecutionPolicy Bypass -Command "$ErrorActionPreference='Stop'; $root='C:\Users\BenLi\.claude\skills'; New-Item -ItemType Directory -Force -Path $root | Out-Null; if (-not (Test-Path \"$root\imageapi\")) { git clone https://github.com/CercaTrovato/imageapi.git \"$root\imageapi\" } else { git -C \"$root\imageapi\" pull --ff-only }"

• OpenCode:

  powershell -NoProfile -ExecutionPolicy Bypass -Command "$ErrorActionPreference='Stop'; $root='C:\Users\BenLi\.agents\skills'; New-Item -ItemType Directory -Force -Path $root | Out-Null; if (-not (Test-Path \"$root\imageapi\")) { git clone https://github.com/CercaTrovato/imageapi.git \"$root\imageapi\" } else { git -C \"$root\imageapi\" pull --ff-only }"

Example config.json

{
  "api_base": "https://gzxsy.vip",
  "api_key": "your_api_key_here",
  "model": "gpt-image-2"
}

Usage

The skill is intended to be triggered by agent instructions such as:

• "Use imageapi to generate an image"
• "Use the imageapi skill"
• "Generate an image and include reference images if useful"

The CLI accepts:

python .\scripts\generate_image.py --prompt "optimized English prompt" --ref "ref1.png" "https://example.com/ref.png" --size 1024x1024 --quality auto

CLI output contract

The script always prints one JSON object to stdout:

• success:
  • ok: true
  • output
  • prompt
  • size
  • quality
  • reference_images
  • optional revised_prompt
  • optional usage
• failure:
  • ok: false
  • error.code
  • error.message
  • error.retryable
  • error.details

Error codes

Common codes include:

• CONFIG_MISSING
• CONFIG_INVALID_JSON
• CONFIG_MISSING_FIELD
• PROMPT_EMPTY
• REF_IMAGE_INVALID
• REF_IMAGE_UNREADABLE
• AUTH_FAILED
• RATE_LIMITED
• API_TIMEOUT
• API_HTTP_ERROR
• API_BAD_RESPONSE
• IMAGE_DOWNLOAD_FAILED
• OUTPUT_WRITE_FAILED
• UNSUPPORTED_SIZE
• UNSUPPORTED_QUALITY

For developers

Local development

• Keep config.json out of Git.
• Use config.example.json as the committed template.
• Run the script directly for smoke tests.
• Use the structured JSON contract when building agent integrations.

Validation checklist

• Config file loads
• Empty prompt returns PROMPT_EMPTY
• Invalid size / quality return UNSUPPORTED_*
• Invalid reference image returns REF_IMAGE_INVALID
• Success returns ok: true
• Failure returns ok: false

Security notes

• The repository must not contain your live API key.
• Only the local config.json should hold the actual key.
• If the key changes, update the local config and keep the Git-tracked example file empty.
• Do not paste config.json into chat or commit it to GitHub.

Repository layout

• SKILL.md - Codex skill instructions
• scripts/generate_image.py - CLI implementation
• config.example.json - committed config template
• config.json - local-only config, ignored by Git
• agents/openai.yaml - UI metadata for Codex