add apikey image generation media endpoint (#872)

2026-05-20 15:10:30 +08:00
parent 201330652d
commit 204058502e
4 changed files with 505 additions and 1 deletions
@@ -0,0 +1,166 @@
+---
+name: apikey-image-gen
+description: "Generate or edit images through Hermes Web UI using the active profile's fun-codex provider from config.yaml."
+version: 1.0.0
+author: Ekko
+license: MIT
+platforms: [linux, macos, windows, termux]
+metadata:
+  hermes:
+    tags: [api.apikey.fun, image-generation, image-editing, media]
+prerequisites:
+  commands: [curl]
+---
+
+# APIKEY Image Generation
+
+Use this skill when the user wants to generate an image, generate an image from a reference image, or edit an existing image.
+
+Always call Hermes Web UI's media endpoint. Do not call `api.apikey.fun` directly, and do not ask the user for an API key. The server reads the active profile's `config.yaml` and uses the `custom_providers` entry named `fun-codex`:
+
+```yaml
+custom_providers:
+  - name: fun-codex
+    base_url: https://api.apikey.fun/v1
+    api_key: ...
+    model: gpt-5.5
+    api_mode: codex_responses
+```
+
+Endpoint:
+
+```bash
+POST <Hermes Web UI base URL>/api/hermes/media/apikey-image-generate
+```
+
+Resolve the Hermes Web UI base URL in this order:
+
+1. `HERMES_WEB_UI_URL` environment variable, if set.
+2. `http://127.0.0.1:${PORT}`, if `PORT` is set.
+3. `http://127.0.0.1:8648` for local development.
+
+When Hermes Web UI is running from Docker Compose, the default external URL is `http://127.0.0.1:6060`.
+
+Authentication:
+
+Send the Hermes Web UI bearer token.
+
+Resolve the token in this order:
+
+1. `AUTH_TOKEN` environment variable, if set.
+2. `${HERMES_WEB_UI_HOME}/.token`, if `HERMES_WEB_UI_HOME` is set.
+3. `${HERMES_WEBUI_STATE_DIR}/.token`, if `HERMES_WEBUI_STATE_DIR` is set.
+4. `~/.hermes-web-ui/.token`.
+
+## Modes
+
+### Text To Image
+
+Use when there is no input image.
+
+```json
+{
+  "mode": "text",
+  "prompt": "A high quality product image of a matte black mechanical keyboard on a clean desk",
+  "size": "1024x1024",
+  "output_path": "/absolute/path/to/output.png"
+}
+```
+
+The server calls `POST /v1/images/generations` against the `fun-codex` base URL.
+
+### Image To Image
+
+Use when the user provides a reference image and wants a new image based on it.
+
+```json
+{
+  "mode": "image",
+  "prompt": "Use this reference composition and generate a refined technology brand poster",
+  "image_path": "/absolute/path/to/reference.png",
+  "size": "1024x1024",
+  "output_path": "/absolute/path/to/output.png"
+}
+```
+
+The server calls `POST /v1/responses` against the `fun-codex` base URL.
+
+### Image Edit
+
+Use when the user wants to modify an existing image while preserving parts of it.
+
+```json
+{
+  "mode": "edit",
+  "prompt": "Change the background to blue and keep the subject unchanged",
+  "image_path": "/absolute/path/to/source.png",
+  "size": "1024x1024",
+  "output_path": "/absolute/path/to/edited.png"
+}
+```
+
+The server calls `POST /v1/images/edits` against the `fun-codex` base URL.
+
+## Request Fields
+
+- `mode`: `text`, `image`, or `edit`.
+- `prompt`: required.
+- `image_path`: local png, jpeg, or webp path. Required for `image` and `edit` unless using `image_url` or `image_base64`.
+- `image_url`: optional alternative image input.
+- `image_base64`: optional alternative image input. If it is not a data URI, include `mime_type`.
+- `n`: number of images. Defaults to `1`.
+- `size`: defaults to `1024x1024`. Common values: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`, `2160x3840`, `auto`.
+- `quality`: defaults to `auto`.
+- `model`: optional override. Text/edit default to `gpt-image-2`; image mode defaults to the `fun-codex` model in `config.yaml`.
+- `image_model`: optional image tool model for image mode. Defaults to `gpt-image-2`.
+- `output_path`: optional absolute output file path. If omitted, the server saves to `${HERMES_WEB_UI_HOME:-~/.hermes-web-ui}/media/*.png`.
+- `timeout_ms`: defaults to `600000`.
+
+## Curl Template
+
+```bash
+TOKEN="${AUTH_TOKEN:-}"
+if [ -z "$TOKEN" ] && [ -n "${HERMES_WEB_UI_HOME:-}" ] && [ -f "$HERMES_WEB_UI_HOME/.token" ]; then
+  TOKEN="$(cat "$HERMES_WEB_UI_HOME/.token")"
+fi
+if [ -z "$TOKEN" ] && [ -n "${HERMES_WEBUI_STATE_DIR:-}" ] && [ -f "$HERMES_WEBUI_STATE_DIR/.token" ]; then
+  TOKEN="$(cat "$HERMES_WEBUI_STATE_DIR/.token")"
+fi
+if [ -z "$TOKEN" ] && [ -f "$HOME/.hermes-web-ui/.token" ]; then
+  TOKEN="$(cat "$HOME/.hermes-web-ui/.token")"
+fi
+if [ -z "$TOKEN" ]; then
+  echo "Missing Hermes Web UI token. Check AUTH_TOKEN, HERMES_WEB_UI_HOME, HERMES_WEBUI_STATE_DIR, or ~/.hermes-web-ui/.token." >&2
+  exit 1
+fi
+
+BASE_URL="${HERMES_WEB_UI_URL:-}"
+if [ -z "$BASE_URL" ]; then
+  BASE_URL="http://127.0.0.1:${PORT:-8648}"
+fi
+BASE_URL="${BASE_URL%/}"
+
+curl -sS -X POST "$BASE_URL/api/hermes/media/apikey-image-generate" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "mode": "text",
+    "prompt": "A cinematic 4K photo of a silver robot hand holding a small glowing cube",
+    "size": "3840x2160",
+    "output_path": "/absolute/path/to/output.png"
+  }'
+```
+
+Successful responses include:
+
+```json
+{
+  "ok": true,
+  "mode": "text",
+  "output_paths": ["/absolute/path/to/output.png"],
+  "provider": "fun-codex",
+  "base_url": "https://api.apikey.fun/v1"
+}
+```
+
+If the response code is `missing_fun_codex_provider`, tell the user to configure `fun-codex` in the active profile's `config.yaml`.