---
name: shujkimagegen-api
description: Generate or edit images through the repo-managed server6 Sub2API direct endpoint, using the OPENAI_API_KEY from ~/.codex/auth.json and a fixed OpenAI-compatible base URL at https://sub2apicn.shujk.top/v1. Use when image generation should bypass the Cloudflare-proxied sub2apius.shujk.top route, or when the user asks for Shujakuin direct image generation through sub2apicn.
---

# Shujk ImageGen API

Use this helper when image generation or editing should reach server6 directly instead of passing through Cloudflare.

## Boundary

- Do not print, copy, commit, or summarize API keys.
- Read only `OPENAI_API_KEY` from `~/.codex/auth.json`; do not read plaintext `.env` files or unrelated secrets.
- Keep the durable source in the Gitea repo `shujakuin/skill-shujkimagegen-api`; treat `ai-infra/skills/sources/shujkimagegen-api/` and HOME runtime copies as managed mirrors.
- Do not place this skill under the infra repo's `.agents/skills/` or manage it through cc-switch WebDAV.
- Treat this as a thin wrapper around the system `imagegen` CLI; do not copy or patch the system script.
- The current management state is repo source only. Do not create a HOME runtime placement unless the user explicitly requests it.

## Endpoint

- Direct origin: `https://sub2apicn.shujk.top`
- Exported OpenAI-compatible base URL: `https://sub2apicn.shujk.top/v1`

The `/v1` suffix is required because `/models` is an application page while `/v1/models` is the authenticated OpenAI-compatible API.

## Workflow

1. Use the system `imagegen` skill for prompt, composition, and asset decisions.
2. Run the repo source wrapper while the skill remains source-only:

   ```bash
   python3 ai-infra/skills/sources/shujkimagegen-api/scripts/shujk_imagegen.py generate \
     --prompt "..." \
     --out output/imagegen/example.png
   ```

3. For edits, pass through the system CLI arguments:

   ```bash
   python3 ai-infra/skills/sources/shujkimagegen-api/scripts/shujk_imagegen.py edit \
     --image input.png \
     --prompt "..." \
     --out output/imagegen/edited.png
   ```

4. Inspect non-secret configuration with:

   ```bash
   python3 ai-infra/skills/sources/shujkimagegen-api/scripts/shujk_imagegen.py \
     --print-config-redacted
   ```

5. Save project-bound assets inside the active workspace and report the output path and final prompt.

After an explicit HOME runtime placement, use the equivalent path under `~/.agents/skills/shujkimagegen-api/`.

## Installation Validation

After placing the skill in `~/.agents/skills/shujkimagegen-api/`, validate the installed copy before reporting success:

1. Confirm `SKILL.md`, `agents/openai.yaml`, and `scripts/shujk_imagegen.py` exist.
2. Check whether the selected Python environment can import `openai`. Do not add it to an unrelated project's dependencies just for validation. If it is absent and `uv` is available, use an ephemeral environment:

   ```bash
   uv run --with openai python ~/.agents/skills/shujkimagegen-api/scripts/shujk_imagegen.py \
     --print-config-redacted
   ```

3. Run a no-cost command-path test:

   ```bash
   uv run --with openai python ~/.agents/skills/shujkimagegen-api/scripts/shujk_imagegen.py \
     generate --prompt "installation validation" --out /tmp/shujkimagegen-dry-run.png \
     --dry-run --no-augment
   ```

4. When the user authorizes a real API test, generate one low-cost image with `gpt-image-2`, `quality=low`, and a simple prompt. Confirm the command exits successfully and inspect the resulting file as a real, non-empty image.
5. Remove test artifacts that are not intended deliverables.

If validation requires a compatibility fix, edit the standalone Gitea checkout first, rerun validation, commit and push it, then resync the infra mirror and selected runtime placement. Never leave the only fix in `~/.agents/skills/`.

## Failure Handling

- If `OPENAI_API_KEY` is absent, report that auth is unavailable without revealing file contents.
- If the system imagegen CLI is missing, report its expected path.
- If the endpoint rejects a model or option, retry only with an explicitly compatible model or option.
- Do not silently fall back to `sub2apius.shujk.top` or another Cloudflare-proxied endpoint.