foxapi-imagegen-skill 0.1.1

package/README.md

@@ -0,0 +1,36 @@
+# FoxAPI Imagegen Skill CLI
+
+This package installs the FoxAPI image generation skill for Codex.
+
+## Install from npm
+
+```bash
+npx --yes foxapi-imagegen-skill install
+```
+
+The shortest hosted command is:
+
+```bash
+npx --yes https://course.foxapi.cn/f.tgz
+```
+
+On Windows, the default destination is `%USERPROFILE%\\.codex\\skills\\foxapi-imagegen`.
+On macOS and Linux, it is `~/.codex/skills/foxapi-imagegen`.
+
+To replace an existing copy:
+
+```bash
+npx --yes foxapi-imagegen-skill install --force
+```
+
+The package does not contain API keys or generated images. The installed skill reads
+`FOXAPI_API_KEY` or another supported credential source when it runs.
+
+## Run the installed skill
+
+```bash
+python ~/.codex/skills/foxapi-imagegen/scripts/foxapi_imagegen.py generate --prompt "A clean product illustration"
+```
+
+The skill calls `https://foxapi.cn/v1/responses` with the
+`image_generation` tool and saves the returned Base64 image locally.

package/bin/foxapi-imagegen-skill.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const packageRoot = path.resolve(__dirname, "..");
+const sourceDir = path.join(packageRoot, "skill");
+
+function printUsage() {
+  console.log(`FoxAPI Imagegen Skill installer
+
+Usage:
+  npx --yes https://course.foxapi.cn/f.tgz
+  npx --yes foxapi-imagegen-skill install
+  npx --yes foxapi-imagegen-skill path
+  npx --yes foxapi-imagegen-skill uninstall --yes
+
+Commands:
+  install                 Install the skill into CODEX_HOME/skills.
+  install --force         Replace an existing FoxAPI Imagegen skill.
+  path                    Print the installation path.
+  uninstall --yes         Remove the installed skill.
+
+Options:
+  --codex-home <path>     Override CODEX_HOME for this command.
+  --force                 Allow install to replace the target directory.
+  --yes                   Confirm uninstall.
+`);
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exitCode = 1;
+}
+
+function parseArgs(argv) {
+  const positionals = [];
+  const options = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--force" || value === "--yes") {
+      options[value.slice(2)] = true;
+      continue;
+    }
+    if (value === "--help" || value === "-h") {
+      options.help = true;
+      continue;
+    }
+    if (value === "--version" || value === "-v") {
+      options.version = true;
+      continue;
+    }
+    if (value === "--codex-home") {
+      const next = argv[index + 1];
+      if (!next || next.startsWith("--")) {
+        throw new Error("--codex-home requires a path.");
+      }
+      options.codexHome = next;
+      index += 1;
+      continue;
+    }
+    if (value.startsWith("--")) {
+      throw new Error(`Unknown option: ${value}`);
+    }
+    positionals.push(value);
+  }
+  return { command: positionals[0] || "install", options };
+}
+
+function resolveCodexHome(options) {
+  const raw = options.codexHome || process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+  return path.resolve(raw);
+}
+
+function targetPath(options) {
+  return path.join(resolveCodexHome(options), "skills", "foxapi-imagegen");
+}
+
+function validateSource() {
+  const required = [
+    path.join(sourceDir, "SKILL.md"),
+    path.join(sourceDir, "agents", "openai.yaml"),
+    path.join(sourceDir, "scripts", "foxapi_imagegen.py"),
+  ];
+  for (const file of required) {
+    if (!fs.existsSync(file)) {
+      throw new Error(`Package is missing ${path.relative(packageRoot, file)}.`);
+    }
+  }
+}
+
+function install(options) {
+  validateSource();
+  const destination = targetPath(options);
+  if (fs.existsSync(destination)) {
+    if (!options.force) {
+      throw new Error(`Target already exists: ${destination}. Use install --force to replace it.`);
+    }
+    fs.rmSync(destination, { recursive: true, force: true });
+  }
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.cpSync(sourceDir, destination, { recursive: true });
+  console.log(`Installed FoxAPI Imagegen Skill to ${destination}`);
+  console.log("Restart Codex to load the new skill.");
+}
+
+function uninstall(options) {
+  const destination = targetPath(options);
+  if (!fs.existsSync(destination)) {
+    console.log(`Skill is not installed at ${destination}`);
+    return;
+  }
+  if (!options.yes) {
+    throw new Error("Uninstall is destructive. Add --yes to confirm.");
+  }
+  fs.rmSync(destination, { recursive: true, force: true });
+  console.log(`Removed FoxAPI Imagegen Skill from ${destination}`);
+}
+
+try {
+  const { command, options } = parseArgs(process.argv.slice(2));
+  if (options.version) {
+    console.log(require(path.join(packageRoot, "package.json")).version);
+  } else if (options.help || command === "help") {
+    printUsage();
+  } else if (command === "path") {
+    console.log(targetPath(options));
+  } else if (command === "install") {
+    install(options);
+  } else if (command === "uninstall") {
+    uninstall(options);
+  } else {
+    throw new Error(`Unknown command: ${command}`);
+  }
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "foxapi-imagegen-skill",
+  "version": "0.1.1",
+  "description": "Install the FoxAPI image generation Codex skill.",
+  "bin": {
+    "foxapi-imagegen-skill": "bin/foxapi-imagegen-skill.js"
+  },
+  "files": [
+    "bin",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "license": "MIT",
+  "preferGlobal": false
+}

package/skill/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: foxapi-imagegen
+description: Use when the user asks Codex to generate or edit an image through FoxAPI instead of the built-in image_gen tool, including poster, avatar, cover, illustration, website promotional image, text-to-image, image-to-image, reference-image generation, attached-image edits, or "use image2/gpt-image-2 through foxapi.cn". This reusable skill calls FoxAPI's OpenAI-compatible Responses API image_generation tool and saves the returned Base64 image locally.
+---
+
+# FoxAPI Imagegen
+
+Generate or edit images through FoxAPI's OpenAI-compatible Responses API:
+
+```text
+POST https://foxapi.cn/v1/responses
+tools: [{ "type": "image_generation", "action": "generate" }]
+```
+
+## Sharing / Installation
+
+This skill is reusable. To share it, distribute only the `foxapi-imagegen` folder or a zip of that folder. Do not include any `outputs/`, `.codex/auth.json`, API keys, or generated images.
+
+To install, copy the `foxapi-imagegen` folder into the user's Codex skills directory and start a new Codex task:
+
+- Windows: `%USERPROFILE%\.codex\skills\foxapi-imagegen`
+- macOS/Linux: `~/.codex/skills/foxapi-imagegen`
+
+## Routing
+
+When this skill is selected:
+
+1. Do not use the built-in `image_gen` tool.
+2. Do not use the system `.system/imagegen` skill workflow.
+3. Run `scripts/foxapi_imagegen.py`.
+4. Use FoxAPI by default: `https://foxapi.cn/v1/responses`.
+5. Pass user-provided reference images with `--image` or `--image-url` when available.
+6. Save the decoded image file locally and show it inline in the final response.
+
+## Credentials
+
+Never print API keys.
+
+The script resolves credentials in this order:
+
+1. `--api-key`
+2. `FOXAPI_API_KEY`
+3. `FOXAPI_KEY`
+4. `OPENAI_API_KEY`
+5. Codex `auth.json`, looking for API-key fields such as `OPENAI_API_KEY`, `FOXAPI_API_KEY`, or `api_key`
+
+This means a Codex desktop session logged in with an API key can usually be used without passing a key in chat.
+
+Users who are not logged in through Codex can set:
+
+```bash
+FOXAPI_API_KEY="<their-key>"
+```
+
+Optional environment overrides:
+
+- `FOXAPI_RESPONSES_URL`: full endpoint, for example `https://foxapi.cn/v1/responses`.
+- `FOXAPI_BASE_URL`: base URL, for example `https://foxapi.cn/v1`.
+- `FOXAPI_RESPONSES_MODEL`, `FOXAPI_IMAGE_MODEL`, or `FOXAPI_MODEL`: model used for the Responses call.
+- `FOXAPI_IMAGE_SIZE`: requested size, for example `1024x1024`.
+- `FOXAPI_IMAGE_QUALITY`: requested quality.
+- `FOXAPI_IMAGE_OUTPUT_FORMAT`: `png`, `jpeg`, or `webp`.
+- `FOXAPI_IMAGE_OUTPUT_DIR`: output folder.
+
+## Commands
+
+Text-to-image:
+
+```bash
+python scripts/foxapi_imagegen.py generate --prompt "<prompt>" --cwd "<current workspace>"
+```
+
+Reference-image generation / edit:
+
+```bash
+python scripts/foxapi_imagegen.py generate --prompt "<prompt>" --image "<attached image path>" --cwd "<current workspace>"
+```
+
+Useful options:
+
+- `--output-dir "<folder>"`: save somewhere specific.
+- `--model "gpt-5.5"`: Responses model, default `gpt-5.5`.
+- `--size "1024x1024"`: requested image size.
+- `--quality "high"`: requested quality.
+- `--image "<path>"`: local reference image path; repeat for multiple reference images.
+- `--image-url "<url-or-data-url>"`: remote reference image or existing data URL; repeat for multiple reference images.
+- `--endpoint "https://foxapi.cn/v1/responses"`: override the full Responses endpoint.
+- `--base-url "https://foxapi.cn/v1"`: override the default base URL.
+- `--n 2`: generate multiple images by making repeated requests.
+
+For local attachments supplied by Codex, pass the absolute file path exactly as provided. The script converts it to a `data:image/...;base64,...` `input_image` item and sends it together with the prompt.
+
+## Output Location
+
+Choose the output directory in this order:
+
+1. `--output-dir`
+2. `FOXAPI_IMAGE_OUTPUT_DIR`
+3. `<current workspace>/outputs/foxapi-imagegen/`
+
+## Display
+
+The script prints JSON. If `ok` is true:
+
+1. Insert each returned `markdown` image line directly in the reply.
+2. Include the `saved_markdown` lines.
+3. Include the `folder_markdown` line.
+4. Mention `actual_size` and `actual_quality` if they differ from the requested values.
+5. Do not show Base64 or raw SSE data.
+
+## Notes
+
+FoxAPI's Responses image tool may return an actual size or quality different from the requested `--size` and `--quality`. Report the actual values from the JSON response when present.
+
+## Errors
+
+Use friendly Chinese explanations:
+
+- Missing key: ask the user to confirm Codex is logged in with an API key, or set `FOXAPI_API_KEY` / `OPENAI_API_KEY`.
+- 401: key invalid, disabled, expired, or missing.
+- 403: key lacks permission or account access.
+- 402/quota/balance: balance or quota is insufficient.
+- Missing image result: the API did not return an `image_generation_call.result` field.
+- Unreadable reference image: the referenced local file path is missing or cannot be read.

package/skill/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "FoxAPI Imagegen"
+  short_description: "Reusable FoxAPI Responses image generation"
+  default_prompt: "Use $foxapi-imagegen to generate or edit an image through FoxAPI."
+
+policy:
+  allow_implicit_invocation: true

package/skill/scripts/foxapi_imagegen.py

@@ -0,0 +1,453 @@
+#!/usr/bin/env python3
+"""Generate images through FoxAPI Responses image_generation."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import mimetypes
+import os
+import re
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Iterable
+
+
+DEFAULT_BASE_URL = "https://foxapi.cn/v1"
+DEFAULT_MODEL = "gpt-5.5"
+DEFAULT_SIZE = "1024x1024"
+DEFAULT_QUALITY = "high"
+DEFAULT_OUTPUT_FORMAT = "png"
+OUTPUT_SUBDIR = Path("outputs") / "foxapi-imagegen"
+USER_AGENT = "codex-foxapi-imagegen/1.0"
+
+
+class ImagegenError(Exception):
+    def __init__(self, error_type: str, message: str) -> None:
+        super().__init__(message)
+        self.error_type = error_type
+        self.message = message
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    try:
+        result = run(args)
+    except ImagegenError as exc:
+        result = {"ok": False, "error_type": exc.error_type, "message": exc.message}
+    except Exception as exc:  # noqa: BLE001 - command boundary
+        result = {
+            "ok": False,
+            "error_type": "unexpected_error",
+            "message": f"Unexpected image generation error: {exc}",
+        }
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result.get("ok") else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Generate images through FoxAPI Responses.")
+    subparsers = parser.add_subparsers(dest="mode", required=True)
+
+    generate = subparsers.add_parser("generate", help="Text-to-image or reference-image generation.")
+    generate.add_argument("--prompt", required=True, help="Image prompt.")
+    generate.add_argument(
+        "--image",
+        action="append",
+        default=[],
+        help="Reference image file path. Can be repeated.",
+    )
+    generate.add_argument(
+        "--image-url",
+        action="append",
+        default=[],
+        help="Reference image URL or data URL. Can be repeated.",
+    )
+    generate.add_argument("--cwd", help="Current Codex workspace folder.")
+    generate.add_argument("--output-dir", help="Explicit output folder.")
+    generate.add_argument(
+        "--model",
+        default=first_env(["FOXAPI_RESPONSES_MODEL", "FOXAPI_IMAGE_MODEL", "FOXAPI_MODEL"], DEFAULT_MODEL),
+        help="Responses model.",
+    )
+    generate.add_argument(
+        "--size",
+        default=first_env(["FOXAPI_IMAGE_SIZE"], DEFAULT_SIZE),
+        help="Requested size, e.g. 1024x1024.",
+    )
+    generate.add_argument(
+        "--quality",
+        default=first_env(["FOXAPI_IMAGE_QUALITY"], DEFAULT_QUALITY),
+        help="Requested quality.",
+    )
+    generate.add_argument("--background", help="Optional image background setting.")
+    generate.add_argument("--api-key", help="API key override. Prefer environment variables.")
+    generate.add_argument("--endpoint", help="Full Responses endpoint, e.g. https://foxapi.cn/v1/responses.")
+    generate.add_argument("--base-url", help="Base URL, default https://foxapi.cn/v1.")
+    generate.add_argument(
+        "--output-format",
+        default=first_env(["FOXAPI_IMAGE_OUTPUT_FORMAT"], DEFAULT_OUTPUT_FORMAT),
+    )
+    generate.add_argument("--n", type=int, default=1, help="Number of images to generate.")
+    generate.add_argument("--timeout", type=int, default=240)
+    generate.add_argument("--mock-b64", help="Offline test hook: save this Base64 image.")
+    return parser
+
+
+def run(args: argparse.Namespace) -> dict[str, Any]:
+    validate_args(args)
+    output_dir = resolve_output_dir(args)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if args.mock_b64:
+        api_key = ""
+        credential_source = "mock_b64"
+    else:
+        api_key, credential_source = resolve_api_key(args)
+
+    saved: list[dict[str, Any]] = []
+    for index in range(args.n):
+        if args.mock_b64:
+            item = {
+                "result": args.mock_b64,
+                "output_format": normalize_output_format(args.output_format),
+                "status": "completed",
+                "action": "generate",
+            }
+        else:
+            item = request_image(args, api_key)
+        saved.append(save_image_item(item, args, output_dir, index))
+
+    paths = [entry["path"] for entry in saved]
+    markdown = [to_markdown_image(path) for path in paths]
+    saved_markdown = [f"Saved to: {to_markdown_link(path, path)}" for path in paths]
+    folder = to_display_path(output_dir)
+
+    return {
+        "ok": True,
+        "mode": "generate",
+        "provider": "foxapi",
+        "endpoint": resolve_responses_url(args),
+        "model": args.model,
+        "credential_source": credential_source,
+        "requested_size": args.size,
+        "requested_quality": args.quality,
+        "reference_image_count": reference_image_count(args),
+        "images": saved,
+        "paths": paths,
+        "markdown": markdown,
+        "saved_markdown": saved_markdown,
+        "folder_markdown": to_markdown_link("Open folder", folder),
+    }
+
+
+def validate_args(args: argparse.Namespace) -> None:
+    if args.n < 1 or args.n > 4:
+        raise ImagegenError("invalid_n", "--n must be between 1 and 4.")
+    if not re.fullmatch(r"\d+x\d+", args.size):
+        raise ImagegenError("invalid_size", "Use WIDTHxHEIGHT for --size, for example 1024x1024.")
+    if args.output_format.lower() not in {"png", "jpg", "jpeg", "webp"}:
+        raise ImagegenError("invalid_output_format", "--output-format must be png, jpg, jpeg, or webp.")
+    if args.timeout < 1:
+        raise ImagegenError("invalid_timeout", "--timeout must be positive.")
+    for image in args.image:
+        path = Path(image).expanduser()
+        if not path.is_file():
+            raise ImagegenError("unreadable_reference_image", f"Reference image is not readable: {image}")
+
+
+def resolve_output_dir(args: argparse.Namespace) -> Path:
+    if args.output_dir:
+        return Path(args.output_dir).expanduser()
+    env_dir = os.getenv("FOXAPI_IMAGE_OUTPUT_DIR")
+    if env_dir:
+        return Path(env_dir).expanduser()
+    cwd = Path(args.cwd).expanduser() if args.cwd else Path.cwd()
+    return cwd / OUTPUT_SUBDIR
+
+
+def resolve_api_key(args: argparse.Namespace) -> tuple[str, str]:
+    candidates = [
+        ("--api-key", args.api_key),
+        ("FOXAPI_API_KEY", os.getenv("FOXAPI_API_KEY")),
+        ("FOXAPI_KEY", os.getenv("FOXAPI_KEY")),
+        ("OPENAI_API_KEY", os.getenv("OPENAI_API_KEY")),
+    ]
+    for source, value in candidates:
+        if value:
+            return value, source
+
+    auth_key = read_codex_auth_json_key()
+    if auth_key:
+        return auth_key, "codex_auth_json"
+
+    raise ImagegenError(
+        "missing_api_key",
+        "No API key found. Log in to Codex with an API key, or set FOXAPI_API_KEY / OPENAI_API_KEY.",
+    )
+
+
+def read_codex_auth_json_key() -> str | None:
+    paths: list[Path] = []
+    codex_home = os.getenv("CODEX_HOME")
+    if codex_home:
+        paths.append(Path(codex_home).expanduser() / "auth.json")
+    paths.append(Path.home() / ".codex" / "auth.json")
+
+    for path in paths:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+            continue
+        value = find_api_key(data)
+        if value:
+            return value
+    return None
+
+
+def find_api_key(value: Any) -> str | None:
+    names = {"OPENAI_API_KEY", "FOXAPI_API_KEY", "FOXAPI_KEY", "api_key", "openai_api_key", "foxapi_api_key"}
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if key in names and isinstance(item, str) and item.strip():
+                return item.strip()
+        for item in value.values():
+            found = find_api_key(item)
+            if found:
+                return found
+    elif isinstance(value, list):
+        for item in value:
+            found = find_api_key(item)
+            if found:
+                return found
+    return None
+
+
+def normalize_base_url(raw: str | None) -> str:
+    base_url = raw or os.getenv("FOXAPI_BASE_URL") or os.getenv("OPENAI_BASE_URL") or DEFAULT_BASE_URL
+    base_url = base_url.rstrip("/")
+    if base_url.endswith("/v1"):
+        return base_url
+    return f"{base_url}/v1"
+
+
+def resolve_responses_url(args: argparse.Namespace) -> str:
+    endpoint = args.endpoint or os.getenv("FOXAPI_RESPONSES_URL")
+    if endpoint:
+        endpoint = endpoint.rstrip("/")
+        if endpoint.endswith("/responses"):
+            return endpoint
+        if endpoint.endswith("/v1"):
+            return f"{endpoint}/responses"
+        return f"{endpoint}/v1/responses"
+    return f"{normalize_base_url(args.base_url)}/responses"
+
+
+def first_env(names: list[str], fallback: str) -> str:
+    for name in names:
+        value = os.getenv(name)
+        if value:
+            return value
+    return fallback
+
+
+def normalize_output_format(value: str) -> str:
+    fmt = value.lower()
+    return "jpeg" if fmt == "jpg" else fmt
+
+
+def request_image(args: argparse.Namespace, api_key: str) -> dict[str, Any]:
+    url = resolve_responses_url(args)
+    tool: dict[str, Any] = {
+        "type": "image_generation",
+        "action": "generate",
+        "size": args.size,
+        "quality": args.quality,
+    }
+    if args.background:
+        tool["background"] = args.background
+    if args.output_format:
+        tool["output_format"] = normalize_output_format(args.output_format)
+
+    payload = {
+        "model": args.model,
+        "input": build_input(args),
+        "tools": [tool],
+        "tool_choice": {"type": "image_generation"},
+        "stream": True,
+    }
+    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    request = urllib.request.Request(
+        url=url,
+        data=body,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "Accept": "text/event-stream",
+            "User-Agent": USER_AGENT,
+        },
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=args.timeout) as response:
+            return read_image_item_from_sse(response)
+    except urllib.error.HTTPError as exc:
+        detail = safe_read_error(exc)
+        raise ImagegenError("http_error", f"FoxAPI returned HTTP {exc.code}: {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise ImagegenError("network_error", f"Could not reach FoxAPI: {exc.reason}") from exc
+
+
+def build_input(args: argparse.Namespace) -> str | list[dict[str, Any]]:
+    if not args.image and not args.image_url:
+        return args.prompt
+
+    content: list[dict[str, str]] = [{"type": "input_text", "text": args.prompt}]
+    for image in args.image:
+        content.append({"type": "input_image", "image_url": encode_image_file_as_data_url(image)})
+    for image_url in args.image_url:
+        content.append({"type": "input_image", "image_url": image_url})
+
+    return [{"role": "user", "content": content}]
+
+
+def encode_image_file_as_data_url(image: str) -> str:
+    path = Path(image).expanduser()
+    try:
+        image_bytes = path.read_bytes()
+    except OSError as exc:
+        raise ImagegenError("unreadable_reference_image", f"Could not read reference image: {image}") from exc
+
+    mime_type = mimetypes.guess_type(path.name)[0] or "image/png"
+    b64 = base64.b64encode(image_bytes).decode("ascii")
+    return f"data:{mime_type};base64,{b64}"
+
+
+def reference_image_count(args: argparse.Namespace) -> int:
+    return len(args.image) + len(args.image_url)
+
+
+def read_image_item_from_sse(lines: Iterable[bytes]) -> dict[str, Any]:
+    event_name: str | None = None
+    data_lines: list[str] = []
+    last_error: Any = None
+    last_item: dict[str, Any] | None = None
+
+    def process_event(event: str | None, data: str) -> None:
+        nonlocal last_error, last_item
+        if not data or data == "[DONE]":
+            return
+        try:
+            obj = json.loads(data)
+        except json.JSONDecodeError:
+            return
+        error = obj.get("error")
+        if error:
+            last_error = error
+        for item in find_image_items(obj):
+            last_item = item
+
+    for raw in lines:
+        line = raw.decode("utf-8", errors="replace").rstrip("\r\n")
+        if line == "":
+            process_event(event_name, "\n".join(data_lines).strip())
+            event_name = None
+            data_lines = []
+            continue
+        if line.startswith("event:"):
+            event_name = line[len("event:") :].strip()
+        elif line.startswith("data:"):
+            data_lines.append(line[len("data:") :].lstrip())
+
+    if data_lines:
+        process_event(event_name, "\n".join(data_lines).strip())
+
+    if last_item and last_item.get("result"):
+        return last_item
+    if last_error:
+        raise ImagegenError("api_error", format_api_error(last_error))
+    raise ImagegenError("missing_image_result", "FoxAPI response did not contain image_generation_call.result.")
+
+
+def find_image_items(value: Any) -> list[dict[str, Any]]:
+    found: list[dict[str, Any]] = []
+    if isinstance(value, dict):
+        if value.get("type") == "image_generation_call" and value.get("result"):
+            found.append(value)
+        for item in value.values():
+            found.extend(find_image_items(item))
+    elif isinstance(value, list):
+        for item in value:
+            found.extend(find_image_items(item))
+    return found
+
+
+def save_image_item(item: dict[str, Any], args: argparse.Namespace, output_dir: Path, index: int) -> dict[str, Any]:
+    b64 = item.get("result")
+    if not isinstance(b64, str) or not b64:
+        raise ImagegenError("missing_image_result", "Image item has no Base64 result.")
+    try:
+        image_bytes = base64.b64decode(b64)
+    except Exception as exc:  # noqa: BLE001
+        raise ImagegenError("decode_error", f"Could not decode image Base64: {exc}") from exc
+
+    output_format = normalize_output_format(str(item.get("output_format") or args.output_format))
+    suffix = "jpg" if output_format == "jpeg" else output_format
+    timestamp = f"{time.strftime('%Y%m%d-%H%M%S')}-{str(time.time_ns())[-6:]}"
+    slug = slugify(args.prompt)
+    path = output_dir / f"{timestamp}-{index + 1}-{slug}.{suffix}"
+    path.write_bytes(image_bytes)
+
+    return {
+        "path": to_display_path(path),
+        "bytes": len(image_bytes),
+        "item_id": item.get("id"),
+        "status": item.get("status"),
+        "action": item.get("action"),
+        "actual_size": item.get("size"),
+        "actual_quality": item.get("quality"),
+        "output_format": output_format,
+    }
+
+
+def slugify(value: str) -> str:
+    value = value.strip().lower()
+    value = re.sub(r"[^a-z0-9]+", "-", value)
+    value = re.sub(r"-{2,}", "-", value).strip("-")
+    return value[:48] or "image"
+
+
+def to_display_path(path: Path | str) -> str:
+    return str(Path(path).resolve()).replace("\\", "/")
+
+
+def to_markdown_image(path: str) -> str:
+    return f"![Generated image]({path})"
+
+
+def to_markdown_link(label: str, path: str) -> str:
+    return f"[{label}]({path})"
+
+
+def safe_read_error(exc: urllib.error.HTTPError) -> str:
+    try:
+        body = exc.read().decode("utf-8", errors="replace")
+    except Exception:  # noqa: BLE001
+        return exc.reason
+    return body[:2000]
+
+
+def format_api_error(error: Any) -> str:
+    if isinstance(error, dict):
+        message = error.get("message") or error.get("type") or json.dumps(error, ensure_ascii=False)
+        return str(message)
+    return str(error)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())