openrouter-genimage-kote-opencode 0.1.0

package/docs/image-to-image.md

@@ -0,0 +1,101 @@
+# Image-to-image guide
+
+`openrouter_edit_image` is the primary tool. Use it whenever an existing image must influence the result: editing, variations, identity preservation, pose/background/object changes, style transfer, multi-reference composition, or creation of a matching game/UI asset.
+
+It requires at least one reference and never falls back to text-to-image. Use `openrouter_generate_image` only when no existing image needs to be preserved or consulted.
+
+## Reference sources
+
+Three explicit reference types are available:
+
+```json
+[
+  { "type": "message_attachment", "index": 1 },
+  { "type": "project_file", "path": "assets/reference.webp" },
+  { "type": "https_url", "url": "https://example.com/reference.jpeg" }
+]
+```
+
+- `message_attachment` indexes image attachments only, starting at 1. It resolves against the parent user message, not the full session history.
+- `project_file` is relative to `context.worktree`. Only regular PNG, JPEG, and WebP files inside the real worktree are accepted.
+- `https_url` accepts only public HTTPS URLs without embedded credentials. Tool arguments cannot contain `http:`, `file:`, `data:`, `blob:`, or `javascript:` references.
+
+If `references` is omitted, all image attachments from the parent user message are used in original order. The plugin does not search older messages, scan the project, or reuse previous generations automatically.
+
+## Ordering and prompt roles
+
+Reference order is significant and preserved exactly. Reference 1 is primary; later references are supporting inputs. The plugin never sorts, drops, collages, or infers a role for a reference. State roles explicitly:
+
+```text
+Reference image 1 defines the character identity, face, proportions, and illustration style.
+Reference image 2 defines clothing only.
+Reference image 3 defines the palette and lighting.
+Change only the pose. Keep the full body visible. Do not add text or other characters.
+```
+
+A useful edit prompt describes:
+
+1. the role of each reference;
+2. properties to preserve;
+3. the exact requested change;
+4. composition, pose, camera, lighting, and output purpose;
+5. exclusions, especially text or extra objects.
+
+The plugin sends the prompt without translation, style injection, or a separate prompt-improvement LLM. Prompts are required, trimmed for validation, and limited to 32,000 characters.
+
+## Examples
+
+Single project asset:
+
+```json
+{
+  "prompt": "Reference 1 is the source crate. Preserve the isometric camera, proportions, palette, and painted style. Create a damaged version with broken boards and scratched metal corners. Keep the silhouette recognizable.",
+  "references": [
+    { "type": "project_file", "path": "assets/props/wooden-crate.png" }
+  ],
+  "output_path": "assets/props/wooden-crate-damaged.png",
+  "n": 1
+}
+```
+
+Two attachments:
+
+```json
+{
+  "prompt": "Reference 1 is the primary character and defines identity, face, and body proportions. Reference 2 defines clothing only. Preserve the rendering style from reference 1 and show the character waving with the right hand.",
+  "references": [
+    { "type": "message_attachment", "index": 1 },
+    { "type": "message_attachment", "index": 2 }
+  ],
+  "output_format": "png",
+  "background": "transparent"
+}
+```
+
+Style URL plus local subject:
+
+```json
+{
+  "prompt": "Reference 1 defines the subject and silhouette. Reference 2 defines only palette, brushwork, and lighting. Preserve the subject while matching that visual style.",
+  "references": [
+    { "type": "project_file", "path": "assets/source.png" },
+    { "type": "https_url", "url": "https://example.com/style.webp" }
+  ]
+}
+```
+
+## Encoding and limits
+
+Local references are validated by MIME and magic bytes, then encoded in memory as `data:image/...;base64,...` inside `input_references`. Explicit HTTPS references are passed without download when no technical reason requires one. No third-party storage is used.
+
+Defaults are 16 references, 20 MiB per local file, and 50 MiB total local bytes. All are configurable within documented constraints. Base64 growth and final request size are checked before building a huge JSON string. When limits are exceeded, the plugin does not silently resize, transcode, drop references, or fall back. Compress/resize the source, use fewer references, or supply a public HTTPS URL.
+
+## Output
+
+Outputs remain inside the worktree. `output_path` must be relative, may not escape through traversal or symlinks, and may not name a source or existing file. Multiple results receive `-01`, `-02`, and similar suffixes. Writes are atomic.
+
+The actual returned bytes determine PNG/JPEG/WebP format and extension. A provider may return fewer results than requested or one invalid item; valid results are preserved and returned as OpenCode attachments with warnings. Cost is displayed only when OpenRouter supplies `usage.cost`.
+
+## Capability failures
+
+The configured model must advertise image input, image output, and `input_references`. Unsupported models or parameters fail before the paid request when discoverable. The plugin never substitutes another model and never converts an edit into generation.

package/docs/security.md

@@ -0,0 +1,49 @@
+# Security model
+
+## Trust boundaries
+
+The plugin handles user-controlled prompts, references, paths, OpenRouter responses, and gateway descriptors. It treats all of them as untrusted until validated. OpenCode's current worktree and trusted attachment parts define filesystem and attachment boundaries.
+
+## Secrets and diagnostics
+
+OpenRouter generation and management keys are used in memory and are not persisted by the plugin. They must never appear in tool output, metadata, errors, logs, cache keys, gateway credentials, or bootstrap documents. Cache identity uses only an 8–12 character prefix of a SHA-256 key fingerprint.
+
+Full prompts, base64, binary bytes, request/response bodies, authorization headers, proxy authorization, cookies, and full external URLs with query strings are also excluded. Structured diagnostics may contain safe fields such as model, routing, request ID, HTTP status, counts, byte sizes, relative output path, prompt length, and a short prompt hash.
+
+Redaction covers at least `sk-or-*`, bearer/authorization values, proxy authorization, `OPENROUTER_API_KEY`, and `OPENROUTER_MANAGEMENT_API_KEY`. Upstream failures expose only a safe status, error code/message, and request ID—not an unredacted body or HTML response.
+
+## Network controls
+
+Production OpenRouter origin is fixed to `https://openrouter.ai/api/v1`. User-configurable base URLs are intentionally absent to prevent accidental key disclosure. Redirects are handled manually and all 3xx responses fail, so authorization is never forwarded to a redirect target.
+
+Idempotent GETs may retry only temporary statuses, at most twice. `POST /images` is never automatically retried because its charge/result may be ambiguous. A lost connection after submission returns `GENIMAGE_REQUEST_STATUS_UNKNOWN`.
+
+Explicit tool URLs must use HTTPS, contain no username/password, and stay within a bounded length. The plugin does not attach OpenRouter authorization to external URLs and does not automatically download arbitrary tool-supplied URLs. Internal OpenCode attachment URLs are resolved through trusted SDK/context mechanisms and are never forwarded externally.
+
+Response bodies and decoded image bytes have independent configured limits. All operations combine caller abort, timeout, and transport abort.
+
+## KoteGateway
+
+Proxy routing is per request and does not replace `globalThis.fetch`. Gateway bootstrap signatures and descriptor validity are checked by reusable gateway core. Target headers and proxy headers remain separate.
+
+The gateway sees a CONNECT tunnel. OpenRouter API keys, management keys, prompts, base64 references, and generated bytes stay inside TLS to OpenRouter and are never proxy credentials. Any bootstrap, signature, descriptor, cache, CONNECT, or proxy timeout failure ends the request. Direct fallback is forbidden.
+
+Synthetic network tests exercise both load orders with one real CONNECT and verify that the image request carries no global route marker. Real OpenCode runtime compatibility remains a release smoke requirement.
+
+## Files and images
+
+Project input/output paths are relative to `context.worktree`. Absolute Unix paths, Windows drive paths, UNC paths, `..` traversal, directories, and realpath/symlink escapes are rejected. Project references must be regular files.
+
+Input and output are limited to PNG, JPEG, and WebP and validated by magic bytes rather than extension/MIME alone. Source images are not modified or transcoded on disk. Output cannot overwrite a source or existing destination. Complete temporary writes are atomically published without replacement; failures clean up temporary data.
+
+Static symlink and junction escapes are rejected and local reads stay on one bounded file handle. The worktree itself remains an operating-system trust boundary: a hostile local process that can rename directories concurrently with an operation can create filesystem races that portable Node.js APIs cannot close with descriptor-relative `openat` operations. Do not run the plugin against a worktree concurrently controlled by an untrusted local account.
+
+Local images become base64 only in memory for the OpenRouter request. Base64 is prohibited in logs, errors, metadata, tool text output, command templates, and temporary text files.
+
+## Attachments
+
+Arbitrary file/data/blob URLs are not accepted from tool arguments. A file URL is trusted only when it originates from the current OpenCode message part. Attachment data URLs are parsed, bounded, decoded, magic-byte checked, and normalized. Internal OpenCode URLs are fetched only through the official SDK or a verified `context.serverUrl` origin.
+
+## Reporting vulnerabilities
+
+Do not open a public issue containing a vulnerability, key, prompt, private image, gateway descriptor, or full upstream response. Follow the private reporting process in [`SECURITY.md`](../SECURITY.md). Revoke any exposed OpenRouter key immediately.

package/docs/testing.md

@@ -0,0 +1,81 @@
+# Testing
+
+Tests are layered so most behavior is verified without paid network calls.
+
+## Local checks
+
+```bash
+bun install
+bun run lint
+bun run typecheck
+bun run test
+bun run build
+npm pack
+```
+
+Useful focused commands:
+
+```bash
+bun run test:unit
+bun run test:integration
+bun run test:smoke
+bun run package:smoke
+```
+
+## Unit coverage
+
+Unit tests cover strict configuration and environment-key resolution; ordered attachment/project/HTTPS references; MIME, magic-byte, base64, path, count, and size validation; generation parameter ranges and cross-field rules; model/capability caching; response parsing and partial success; atomic collision-safe output; balance terminology and partial credits failure; and redaction of secrets, prompts, and base64.
+
+Important invariants include:
+
+- edit requires a reference and cannot become text-to-image;
+- model always comes from configuration;
+- `n` is 1–10 and reference count is 1–16;
+- transparent JPEG and PNG compression fail locally;
+- source/existing files cannot be overwritten;
+- absolute/traversing/symlink-escaping paths fail;
+- key limit is never labeled account balance.
+
+## Synthetic integration coverage
+
+OpenRouter client tests use an injected fetch implementation to verify exact endpoints, authorization separation, manual redirect behavior, GET retry, no POST retry, timeout/abort, bounded bodies, and sanitized upstream failures. They do not start a real HTTPS server.
+
+Tool integration tests decode received data URLs and compare bytes, preserve multiple-reference order, preserve prompts, use only the configured model, save results, and return attachment-shaped tool results.
+
+Transport unit tests use injected gateway and fetch fakes to verify direct/gateway separation, lazy bootstrap, fail-closed errors, descriptor forwarding, target-header isolation, cancellation, and disposal.
+
+The socket-level harness additionally starts a TLS signed-bootstrap service, TLS CONNECT proxy, and separate HTTPS OpenRouter target. It verifies direct bypass, one CONNECT in proxy mode, Ed25519 verification, ordered target bodies, TLS secrecy at the proxy boundary, invalid/expired bootstrap failures, refused CONNECT without direct fallback, and both image/gateway-plugin load orders without a route marker or double CONNECT. Test trust is scoped to per-request custom CA configuration; TLS verification is not disabled globally.
+
+## OpenCode smoke tests
+
+The baseline runtime is OpenCode **1.18.21**; the scaffold currently pins `@opencode-ai/plugin` **1.18.18**. The automated CLI smoke loads the installed tarball through a tuple and verifies its options, all three executable tool definitions, `/openrouter-balance`, plugin context (`directory`, `worktree`, `serverUrl`), the message-client attachment access shape, permissions, and CLI skill installation without executing a model request.
+
+The CLI configuration probe does not execute a tool, so it does not validate `sessionID`/`messageID` tool context, a returned ToolResult attachment, or TUI/Desktop/Web rendering. Those are separate manual real-host release checks. Test the latest stable OpenCode again at release time.
+
+The synthetic KoteGateway proxy/coexistence matrix runs in ordinary integration tests. CI also loads the installed tarball in real baseline/latest OpenCode runtimes. The KoteGateway adapter's narrower peer metadata is documented in the README; this plugin consumes its runtime-independent `/core` export.
+
+Skill CLI tests cover project and global paths (the latter is always `~/.config/opencode/...`, including Windows), `check-skill --global`, nonzero checks for missing/modified files, SHA-256 no-op installs, refusal to replace modifications without `--force`, and atomic forced replacement.
+
+## Real OpenRouter E2E (paid, opt-in)
+
+Real tests are disabled in ordinary CI and pull requests. Run them only with an explicitly budgeted key/model:
+
+Set `OPENROUTER_IMAGE_REFERENCE_URL_E2E` to a public PNG/JPEG/WebP URL to include the real HTTPS-reference check, or omit that assignment.
+
+```bash
+RUN_OPENROUTER_E2E=1 \
+OPENROUTER_API_KEY=... \
+OPENROUTER_IMAGE_MODEL_E2E=... \
+OPENROUTER_IMAGE_REFERENCE_URL_E2E=https://... \
+bun test tests/e2e
+```
+
+The current harness covers `/key`, text-to-image, one/two ordered inline data references, and an optional `usage.cost` field. One combined tool-level request also resolves an OpenCode message attachment plus a project file, optionally appends `OPENROUTER_IMAGE_REFERENCE_URL_E2E` unchanged, persists the generated image, and validates the returned ToolResult attachment. `/credits` is a separate opt-in test: set `RUN_OPENROUTER_CREDITS_E2E=1` and `OPENROUTER_MANAGEMENT_API_KEY`. Configure the public HTTPS variable for that release check; TUI/Desktop/Web rendering remains manual.
+
+Never place E2E credentials, prompts with private content, or generated base64 in fixtures, logs, snapshots, artifacts, or the npm tarball.
+
+## Package smoke
+
+After `npm pack`, the package smoke installs the produced tarball with an isolated npm cache, imports its package-root and `/server` exports under Node with network blocked, invokes its installed bin to install/check the skill, runs the OpenCode smoke against the installed package, checks the file list, and scans for secrets/test credentials. It does not load the source tree as the plugin under test.
+
+Do not claim a compatibility target or workflow as working until its automated test or documented manual smoke has passed.

package/docs/troubleshooting.md

@@ -0,0 +1,73 @@
+# Troubleshooting
+
+Errors use a stable `GENIMAGE_*` code, a safe message, optional sanitized details, and a suggested action. They must not contain keys, prompts, base64, full upstream bodies, query-bearing URLs, or bootstrap documents.
+
+## Configuration
+
+| Code | Cause and action |
+|---|---|
+| `GENIMAGE_CONFIG_INVALID` | A required field is absent, an object contains unknown fields, a string is blank, a numeric/cross-field limit is invalid, or a forbidden base URL was supplied. Validate against `schema/plugin-options.schema.json`; also ensure `maxTotalBytes >= maxFileBytes`. No network request is made while blocked. |
+| `GENIMAGE_OPENROUTER_KEY_MISSING` | Set `apiKey` via `{env:OPENROUTER_API_KEY}` or expose `OPENROUTER_API_KEY` to the OpenCode process. Restart OpenCode if its environment changed. |
+
+## References
+
+| Code | Cause and action |
+|---|---|
+| `GENIMAGE_REFERENCE_REQUIRED` | `openrouter_edit_image` found no explicit reference and no image in the parent user message. Attach an image or pass a reference; there is no text-to-image fallback. |
+| `GENIMAGE_REFERENCE_NOT_FOUND` | Verify the project-relative path and current worktree. |
+| `GENIMAGE_REFERENCE_INDEX_INVALID` | Attachment indexes start at 1 and count only image attachments in the parent user message. |
+| `GENIMAGE_REFERENCE_FORMAT_UNSUPPORTED` | Convert the input to PNG, JPEG, or WebP. Renaming an extension is insufficient. |
+| `GENIMAGE_REFERENCE_TOO_LARGE` | Resize/compress that local image or use a public HTTPS URL. |
+| `GENIMAGE_TOTAL_REFERENCE_SIZE_EXCEEDED` | Use fewer/smaller local references or public HTTPS URLs. |
+| `GENIMAGE_REFERENCE_INVALID` | The MIME, base64, magic bytes, or file contents are invalid/mismatched. Re-export the image. |
+| `GENIMAGE_REFERENCE_URL_INVALID` | Use a public `https://` URL without embedded credentials. `http:`, `file:`, `data:`, `blob:`, and `javascript:` tool URLs are rejected. |
+| `GENIMAGE_TOO_MANY_REFERENCES` | Reduce references to the configured limit (maximum 16). Order is never changed automatically. |
+| `GENIMAGE_ATTACHMENT_ACCESS_FAILED` | Reattach the image to the current message. For internal OpenCode URLs, confirm the client/runtime smoke target supports attachment retrieval. |
+
+## Model and parameters
+
+| Code | Cause and action |
+|---|---|
+| `GENIMAGE_MODEL_NOT_FOUND` | Correct the configured OpenRouter model ID. The tool cannot select another model. |
+| `GENIMAGE_MODEL_DOES_NOT_SUPPORT_IMAGE_INPUT` | Configure a model/endpoint with image input and `input_references`; edit never falls back to generation. |
+| `GENIMAGE_MODEL_DOES_NOT_SUPPORT_IMAGE_OUTPUT` | Configure a model with image output. |
+| `GENIMAGE_PARAMETER_UNSUPPORTED` | Remove the unsupported tool/default parameter or deliberately change the configured model. Also check transparent JPEG, PNG compression, `n`, resolution, and endpoint-specific capabilities. |
+
+## OpenRouter
+
+| Code | Cause and action |
+|---|---|
+| `GENIMAGE_OPENROUTER_AUTH` | Verify/recreate the generation key and its environment mapping. Do not paste it into logs/issues. |
+| `GENIMAGE_OPENROUTER_FORBIDDEN` | Check key permissions and endpoint/model access. `/credits` needs management authorization. |
+| `GENIMAGE_INSUFFICIENT_CREDITS` | Add credits or use a key/account with available funds. The plugin cannot purchase credits. |
+| `GENIMAGE_RATE_LIMITED` | Wait for `Retry-After`; safe GETs have bounded retries, but paid POST generation is not retried. |
+| `GENIMAGE_BAD_REQUEST` | Recheck prompt and parameters against model capabilities. |
+| `GENIMAGE_REQUEST_TOO_LARGE` | Reduce image count/size. Base64 expands local payloads. |
+| `GENIMAGE_PROVIDER_ERROR` | Retry later after checking OpenRouter/provider status. The plugin does not switch provider/model automatically. |
+| `GENIMAGE_TIMEOUT` | Increase `requestTimeoutMs` only if appropriate and check connectivity. An image POST is not retried automatically. |
+| `GENIMAGE_REQUEST_STATUS_UNKNOWN` | The connection failed after submission and the charge/result may be ambiguous. Check OpenRouter activity before manually repeating. |
+| `GENIMAGE_RESPONSE_INVALID` / `GENIMAGE_IMAGE_INVALID` | OpenRouter returned missing, malformed, oversized, unsupported, or MIME-mismatched data. Valid partial results may still be saved with warnings. |
+
+## KoteGateway
+
+`GENIMAGE_GATEWAY_BOOTSTRAP_FAILED`, `GENIMAGE_GATEWAY_SIGNATURE_INVALID`, `GENIMAGE_GATEWAY_CACHE_EXPIRED`, `GENIMAGE_GATEWAY_CONNECT_FAILED`, and `GENIMAGE_GATEWAY_TIMEOUT` all stop a proxy-mode operation. Check bootstrap reachability, clock/signature/cache state, descriptor, proxy connectivity, and TLS CONNECT. Proxy mode intentionally never retries direct. Switch to `routing: "direct"` only as an explicit user configuration decision, not as an automated recovery.
+
+When both gateway packages are installed, verify the tested versions and plugin load-order smoke matrix. The intended behavior is one per-request proxy for image traffic and no impact on ordinary OpenCode provider traffic.
+
+## Output filesystem
+
+| Code | Cause and action |
+|---|---|
+| `GENIMAGE_OUTPUT_PATH_INVALID` | Use a relative file path, not an absolute path, drive/UNC path, directory, or traversal. |
+| `GENIMAGE_OUTPUT_OUTSIDE_WORKTREE` | Remove `..` or a symlink that resolves outside `context.worktree`. |
+| `GENIMAGE_OUTPUT_FORMAT_MISMATCH` | Use an extension consistent with the actual PNG/JPEG/WebP bytes; the plugin may correct the saved extension and warn. |
+| `GENIMAGE_OUTPUT_WRITE_FAILED` | Check directory permissions/free space. Atomic writes should leave no partial final file. Existing files are not overwritten; choose another name. |
+| `GENIMAGE_SOURCE_OVERWRITE_FORBIDDEN` | Choose a destination different from every source reference. |
+
+## Balance terminology
+
+`Remaining API-key spending limit` comes from `/key` and is not account balance. Full `Account credits` come from `/credits`, require a management key, and may legitimately calculate to a negative value. If credits are unavailable but key usage appears, this is intentional partial success.
+
+## Safe diagnostic report
+
+Include package version, OpenCode version/client, OS/runtime, routing mode, configured model ID, error code, safe HTTP status/request ID, reference count and byte sizes, and relative output path. Remove keys, authorization/proxy headers, full prompts, base64, private images, query strings, full upstream bodies, and gateway bootstrap data.

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "openrouter-genimage-kote-opencode",
+  "version": "0.1.0",
+  "description": "OpenRouter image generation and image-to-image tools for OpenCode with optional KoteGateway routing",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/koteyye/openrouter-genimage-kote-opencode.git"
+  },
+  "bugs": {
+    "url": "https://github.com/koteyye/openrouter-genimage-kote-opencode/issues"
+  },
+  "homepage": "https://github.com/koteyye/openrouter-genimage-kote-opencode#readme",
+  "keywords": [
+    "opencode",
+    "openrouter",
+    "image-generation",
+    "image-to-image",
+    "plugin",
+    "kote-gateway"
+  ],
+  "packageManager": "bun@1.3.14",
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./skill": "./.opencode/skills/openrouter-image-generation/SKILL.md",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "openrouter-genimage-kote-opencode": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    ".opencode/skills",
+    "docs",
+    "schema",
+    "README.md",
+    "README.ru.md",
+    "LICENSE",
+    "SECURITY.md",
+    "THIRD_PARTY_NOTICES.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "opencode": ">=1.18.21 <2"
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "test:unit": "bun test tests/unit",
+    "test:integration": "bun test tests/integration tests/contract",
+    "test:smoke": "bun test tests/smoke",
+    "test:e2e": "bun test tests/e2e",
+    "opencode:smoke": "bun run build && bun scripts/opencode-smoke.ts",
+    "package:smoke": "bun run build && bun scripts/package-smoke.ts",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "@koteye/kote-gateway-opencode": "0.1.1",
+    "@opencode-ai/plugin": "1.18.18",
+    "undici": "6.28.0",
+    "zod": "4.1.8"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.35.0",
+    "@types/bun": "1.3.14",
+    "eslint": "9.35.0",
+    "typescript": "5.9.2",
+    "typescript-eslint": "8.42.0"
+  }
+}

package/schema/plugin-options.schema.json

@@ -0,0 +1,182 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/koteyye/openrouter-genimage-kote-opencode/blob/v0.1.0/schema/plugin-options.schema.json",
+  "title": "openrouter-genimage-kote-opencode plugin options",
+  "description": "Strict options for the OpenCode plugin tuple. Runtime validation additionally enforces trim-aware strings and cross-field relationships.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "routing",
+    "model"
+  ],
+  "properties": {
+    "routing": {
+      "type": "string",
+      "enum": [
+        "direct",
+        "proxy"
+      ]
+    },
+    "model": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "\\S"
+    },
+    "apiKey": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096,
+      "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F]+$"
+    },
+    "managementApiKey": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096,
+      "pattern": "^(?=.*\\S)[^\\u0000-\\u001F\\u007F]+$"
+    },
+    "outputDirectory": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4096,
+      "pattern": "^(?![A-Za-z]:)(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))[^\\u0000-\\u001F\\u007F]+$",
+      "default": "assets/generated"
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "aspect_ratio": {
+          "$ref": "#/$defs/imageAspectRatio"
+        },
+        "background": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "transparent",
+            "opaque"
+          ]
+        },
+        "n": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10,
+          "default": 1
+        },
+        "output_format": {
+          "type": "string",
+          "enum": [
+            "png",
+            "jpeg",
+            "webp"
+          ]
+        },
+        "output_compression": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "quality": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "low",
+            "medium",
+            "high"
+          ]
+        },
+        "resolution": {
+          "type": "string",
+          "enum": [
+            "512",
+            "1K",
+            "2K",
+            "4K"
+          ]
+        },
+        "seed": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      }
+    },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "maxReferences": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 16,
+          "default": 16
+        },
+        "maxFileBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "default": 20971520
+        },
+        "maxTotalBytes": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 9007199254740991,
+          "default": 52428800,
+          "description": "Runtime validation requires maxTotalBytes to be greater than or equal to maxFileBytes. Standard JSON Schema cannot compare arbitrary sibling numeric values."
+        }
+      }
+    },
+    "requestTimeoutMs": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "default": 300000
+    },
+    "modelCacheTtlMs": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "default": 3600000
+    },
+    "maxResponseBytes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "default": 134217728
+    },
+    "maxDecodedBytes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991,
+      "default": 134217728
+    }
+  },
+  "$defs": {
+    "imageAspectRatio": {
+      "type": "string",
+      "enum": [
+        "1:1",
+        "1:2",
+        "1:4",
+        "1:8",
+        "2:1",
+        "2:3",
+        "3:2",
+        "3:4",
+        "4:1",
+        "4:3",
+        "4:5",
+        "5:4",
+        "8:1",
+        "9:16",
+        "16:9",
+        "9:19.5",
+        "19.5:9",
+        "9:20",
+        "20:9",
+        "9:21",
+        "21:9",
+        "auto"
+      ]
+    }
+  }
+}