skill-shujkimagegen-async-api/SKILL.md

name, description

name	description
shujkimagegen-async-api	Generate images through the server4 asynchronous Sub2API endpoint, poll the task, and download the resulting image.

Shujk Async ImageGen API

Use this helper when image generation should run asynchronously on server4.

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.
• Current HOME runtime placements are pc and a100 under ~/.agents/skills/shujkimagegen-api/. Update only explicitly modeled placements.

Endpoint

• Async endpoint: https://sub2apius.shujk.top/v1/images/generations/async

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

Workflow

Run the wrapper:

python3 ~/.agents/skills/shujkimagegen-async-api/scripts/shujk_imagegen.py \
  --prompt "..." --out output/imagegen/example.png

The command submits a task, honors Retry-After, polls until completion, and downloads the object-storage URL.

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

For source validation before placement, use the equivalent wrapper under the standalone checkout or infra mirror.

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:

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

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

   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.