@suknna/pixelforge 0.1.0 → 0.2.0

package/README.md

@@ -39,7 +39,27 @@ Secrets may be plain strings or environment references:
 { "apiKey": { "env": "OPENAI_API_KEY" } }
 ```
 
-See [`examples/`](./examples) for complete multi-provider configurations. Supported providers: `openai-images`, `fal`, `replicate`, `stability-ai`.
+A minimal single-provider config looks like this:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/Suknna/pixelforge/main/schema/pixelforge.schema.json",
+  "defaultProfile": "openai",
+  "profiles": {
+    "openai": {
+      "provider": "openai-images",
+      "apiKey": { "env": "OPENAI_API_KEY" },
+      "model": "gpt-image-1",
+      "baseUrl": "https://api.openai.com/v1",
+      "timeoutMs": 180000
+    }
+  }
+}
+```
+
+Add the `$schema` reference shown above so your editor validates the config as you type. The schema lives at [`schema/pixelforge.schema.json`](./schema/pixelforge.schema.json).
+
+See [`examples/`](./examples) for the minimal config ([`pixelforge.minimal.json`](./examples/pixelforge.minimal.json)) and complete multi-provider configurations. Supported providers: `openai-images`, `fal`, `replicate`, `stability-ai`.
 
 ## Tools
 
@@ -51,6 +71,14 @@ PixelForge registers three tools. None of them expose the internal `profile` con
 
 Generation runs in the background. The generation tools return before the file exists; use `pixelforge_check_image_job` to confirm completion.
 
+Both generation tools accept optional render parameters that the model fills per request, not the config:
+
+- `size` — `"<width>x<height>"`, e.g. `"1024x1024"`. Mapped per provider (OpenAI `size`, fal/Stability dimensions). When omitted, the provider default is used.
+- `outputFormat` — `png`, `jpeg`, or `webp`. When omitted, the provider default is used.
+- `strength` (image-to-image only) — `0`–`1`, how far the result may diverge from the base image.
+
+Provider-specific settings (endpoint, model/version, base URL, input-key mappings, API key, timeouts, OpenAI `quality`) stay in the config. Render parameters that vary per image live on the tools.
+
 ## Output Paths
 
 Output paths must resolve inside the current opencode workspace. Relative paths are resolved from the session directory. Files are written atomically (temp file plus rename) so a visible output file always means a completed job.

package/dist/adapters/fal.js

@@ -1,5 +1,5 @@
 import { loadLocalImage, toDataUri } from "../image-input.js";
-import { decodeDataUri, fetchBytes, fetchJson } from "./http.js";
+import { decodeDataUri, fetchBytes, fetchJson, parseSize } from "./http.js";
 /**
  * fal adapter.
  *
@@ -13,8 +13,8 @@ export function createFalAdapter(profile) {
         async generateImage(request) {
             const response = await callFal(profile.endpoint, profile, {
                 prompt: request.prompt,
-                image_size: profile.imageSize,
-                output_format: profile.outputFormat,
+                image_size: parseSize(request.size, "fal"),
+                output_format: request.outputFormat,
             }, request.signal);
             return imageFromFalResponse(response);
         },
@@ -24,9 +24,9 @@ export function createFalAdapter(profile) {
             const response = await callFal(profile.imageToImageEndpoint, profile, {
                 prompt: request.prompt,
                 image_url: imageUrl,
-                strength: request.strength ?? profile.defaultStrength,
-                image_size: profile.imageSize,
-                output_format: profile.outputFormat,
+                strength: request.strength,
+                image_size: parseSize(request.size, "fal"),
+                output_format: request.outputFormat,
             }, request.signal);
             return imageFromFalResponse(response);
         },

package/dist/adapters/http.d.ts

@@ -15,6 +15,16 @@ export declare function decodeBase64Image(base64: string, mimeType?: string): {
     bytes: Uint8Array;
     mimeType: string;
 };
+/**
+ * Parses a model-supplied `"<width>x<height>"` size string into numeric
+ * dimensions. Returns `undefined` when the input is absent. Throws a
+ * fail-closed bad-request error on a malformed value so a bad `size` never
+ * silently degrades to a provider default the model did not intend.
+ */
+export declare function parseSize(size: string | undefined, provider: ProviderName): {
+    width: number;
+    height: number;
+} | undefined;
 export declare function decodeDataUri(dataUri: string): {
     bytes: Uint8Array;
     mimeType: string;

package/dist/adapters/http.js

@@ -35,6 +35,28 @@ export async function fetchBytes(url, provider) {
 export function decodeBase64Image(base64, mimeType = "image/png") {
     return { bytes: Buffer.from(base64, "base64"), mimeType };
 }
+/**
+ * Parses a model-supplied `"<width>x<height>"` size string into numeric
+ * dimensions. Returns `undefined` when the input is absent. Throws a
+ * fail-closed bad-request error on a malformed value so a bad `size` never
+ * silently degrades to a provider default the model did not intend.
+ */
+export function parseSize(size, provider) {
+    if (size === undefined)
+        return undefined;
+    const match = /^(\d+)\s*[x×]\s*(\d+)$/.exec(size.trim());
+    const width = match?.[1];
+    const height = match?.[2];
+    if (!width || !height) {
+        throw new PixelForgeError({
+            category: "bad-request",
+            message: `Invalid size '${size}'. Expected "<width>x<height>", e.g. 1024x1024.`,
+            retryable: false,
+            provider,
+        });
+    }
+    return { width: Number(width), height: Number(height) };
+}
 export function decodeDataUri(dataUri) {
     const match = /^data:([^;]+);base64,(.+)$/.exec(dataUri);
     const mimeType = match?.[1];

package/dist/adapters/openai-images.js

@@ -21,31 +21,31 @@ export function createOpenAIImagesAdapter(profile) {
                 body: JSON.stringify({
                     model: profile.model,
                     prompt: request.prompt,
-                    size: profile.size,
+                    size: request.size,
                     quality: profile.quality,
-                    output_format: profile.outputFormat,
+                    output_format: request.outputFormat,
                 }),
             }, "openai-images");
-            return imageFromOpenAIResponse(response, profile.outputFormat);
+            return imageFromOpenAIResponse(response, request.outputFormat);
         },
         async generateImageFromImage(request) {
             const form = new FormData();
             form.set("model", profile.model);
             form.set("prompt", request.prompt);
             form.set("image[]", await fileFromPath(request.baseImagePath));
-            if (profile.size)
-                form.set("size", profile.size);
+            if (request.size)
+                form.set("size", request.size);
             if (profile.quality)
                 form.set("quality", profile.quality);
-            if (profile.outputFormat)
-                form.set("output_format", profile.outputFormat);
+            if (request.outputFormat)
+                form.set("output_format", request.outputFormat);
             const response = await fetchJson(`${profile.baseUrl.replace(/\/$/, "")}/images/edits`, {
                 method: "POST",
                 signal: request.signal,
                 headers: { Authorization: `Bearer ${profile.credential}` },
                 body: form,
             }, "openai-images");
-            return imageFromOpenAIResponse(response, profile.outputFormat);
+            return imageFromOpenAIResponse(response, request.outputFormat);
         },
     };
 }

package/dist/adapters/replicate.js

@@ -13,10 +13,8 @@ export function createReplicateAdapter(profile) {
                 [profile.promptInputKey]: request.prompt,
                 [profile.imageInputKey]: toDataUri(image),
             };
-            if (profile.strengthInputKey) {
-                const strength = request.strength ?? profile.defaultStrength;
-                if (strength !== undefined)
-                    input[profile.strengthInputKey] = strength;
+            if (profile.strengthInputKey && request.strength !== undefined) {
+                input[profile.strengthInputKey] = request.strength;
             }
             const prediction = await createPrediction(profile, input, request.signal);
             return pollPrediction(profile, prediction, request.signal);

package/dist/adapters/stability-ai.js

@@ -1,5 +1,5 @@
 import { blobFromImage, loadLocalImage } from "../image-input.js";
-import { decodeBase64Image, fetchJson } from "./http.js";
+import { decodeBase64Image, fetchJson, parseSize } from "./http.js";
 /**
  * Stability returns base64 image payloads. Text-to-image uses a JSON body;
  * image-to-image uploads the base image as multipart form data with an
@@ -9,6 +9,7 @@ export function createStabilityAIAdapter(profile) {
     return {
         provider: "stability-ai",
         async generateImage(request) {
+            const dimensions = parseSize(request.size, "stability-ai");
             const response = await fetchJson(`${profile.baseUrl.replace(/\/$/, "")}${profile.textToImagePath}`, {
                 method: "POST",
                 signal: request.signal,
@@ -19,21 +20,20 @@ export function createStabilityAIAdapter(profile) {
                 },
                 body: JSON.stringify({
                     prompt: request.prompt,
-                    output_format: profile.outputFormat,
-                    width: profile.width,
-                    height: profile.height,
+                    output_format: request.outputFormat,
+                    width: dimensions?.width,
+                    height: dimensions?.height,
                 }),
             }, "stability-ai");
-            return imageFromStabilityResponse(response, profile.outputFormat);
+            return imageFromStabilityResponse(response, request.outputFormat);
         },
         async generateImageFromImage(request) {
             const image = await loadLocalImage(request.baseImagePath);
             const form = new FormData();
             form.set("prompt", request.prompt);
-            form.set("output_format", profile.outputFormat ?? "png");
-            const strength = request.strength ?? profile.defaultStrength;
-            if (strength !== undefined)
-                form.set("strength", String(strength));
+            form.set("output_format", request.outputFormat ?? "png");
+            if (request.strength !== undefined)
+                form.set("strength", String(request.strength));
             form.set("image", blobFromImage(image), image.fileName);
             const response = await fetchJson(`${profile.baseUrl.replace(/\/$/, "")}${profile.imageToImagePath}`, {
                 method: "POST",
@@ -44,7 +44,7 @@ export function createStabilityAIAdapter(profile) {
                 },
                 body: form,
             }, "stability-ai");
-            return imageFromStabilityResponse(response, profile.outputFormat);
+            return imageFromStabilityResponse(response, request.outputFormat);
         },
     };
 }

package/dist/config.js

@@ -49,12 +49,10 @@ export function resolveConfig(raw, env = process.env) {
 }
 function resolveProfile(profileName, profile, env) {
     validateTimeout(profileName, profile.timeoutMs);
-    validateStrength(profileName, profile.defaultStrength);
     switch (profile.provider) {
         case "openai-images":
             requireString(profileName, "model", profile.model);
             requireString(profileName, "baseUrl", profile.baseUrl);
-            requireString(profileName, "size", profile.size);
             return { ...profile, profileName, credential: resolveSecret(profile.apiKey, env, `${profileName}.apiKey`) };
         case "fal":
             requireString(profileName, "endpoint", profile.endpoint);
@@ -89,13 +87,6 @@ function validateTimeout(profileName, timeoutMs, field = "timeoutMs") {
         throw configurationError(`${profileName}.${field} must be a positive integer.`);
     }
 }
-function validateStrength(profileName, strength) {
-    if (strength === undefined)
-        return;
-    if (typeof strength !== "number" || strength < 0 || strength > 1) {
-        throw configurationError(`${profileName}.defaultStrength must be between 0 and 1.`);
-    }
-}
 function requireString(profileName, field, value) {
     if (typeof value !== "string" || value.length === 0) {
         throw configurationError(`${profileName}.${field} must be a non-empty string.`);

package/dist/runner.d.ts

@@ -1,6 +1,6 @@
 import { JobRegistry } from "./jobs.js";
 import { type NotificationClient } from "./notifications.js";
-import type { ImageJob, PixelForgeConfig } from "./types.js";
+import type { ImageJob, PixelForgeConfig, RenderOptions } from './types.js';
 /**
  * Everything a background job needs to execute: validated config, the shared
  * job registry, and the notification client. `sessionID` is optional because
@@ -12,5 +12,5 @@ export type RunnerContext = {
     client: NotificationClient;
     sessionID?: string;
 };
-export declare function startTextToImageJob(context: RunnerContext, job: ImageJob, overwrite: boolean): void;
-export declare function startImageToImageJob(context: RunnerContext, job: ImageJob, overwrite: boolean, strength?: number): void;
+export declare function startTextToImageJob(context: RunnerContext, job: ImageJob, overwrite: boolean, render?: RenderOptions): void;
+export declare function startImageToImageJob(context: RunnerContext, job: ImageJob, overwrite: boolean, strength?: number, render?: RenderOptions): void;

package/dist/runner.js

@@ -2,10 +2,15 @@ import { createAdapter } from "./adapters/index.js";
 import { PixelForgeError, toPixelForgeError } from "./errors.js";
 import { notifyJobCompleted } from "./notifications.js";
 import { assertCanWriteOutput, writeFileAtomic } from "./path-safety.js";
-export function startTextToImageJob(context, job, overwrite) {
-    void runJob(context, job, overwrite, async (adapter, signal) => adapter.generateImage({ prompt: job.prompt, signal }));
+export function startTextToImageJob(context, job, overwrite, render = {}) {
+    void runJob(context, job, overwrite, async (adapter, signal) => adapter.generateImage({
+        prompt: job.prompt,
+        signal,
+        ...(render.size !== undefined ? { size: render.size } : {}),
+        ...(render.outputFormat !== undefined ? { outputFormat: render.outputFormat } : {}),
+    }));
 }
-export function startImageToImageJob(context, job, overwrite, strength) {
+export function startImageToImageJob(context, job, overwrite, strength, render = {}) {
     void runJob(context, job, overwrite, async (adapter, signal) => {
         if (!job.baseImagePath)
             throw new Error("Image-to-image job is missing baseImagePath.");
@@ -13,6 +18,8 @@ export function startImageToImageJob(context, job, overwrite, strength) {
             baseImagePath: job.baseImagePath,
             prompt: job.prompt,
             ...(strength !== undefined ? { strength } : {}),
+            ...(render.size !== undefined ? { size: render.size } : {}),
+            ...(render.outputFormat !== undefined ? { outputFormat: render.outputFormat } : {}),
             signal,
         });
     });

package/dist/tools.d.ts

@@ -12,12 +12,20 @@ export declare function createPixelForgeTools(context: RunnerContext): {
         args: {
             prompt: import("zod").ZodString;
             outputPath: import("zod").ZodString;
+            size: import("zod").ZodOptional<import("zod").ZodString>;
+            outputFormat: import("zod").ZodOptional<import("zod").ZodEnum<{
+                png: "png";
+                jpeg: "jpeg";
+                webp: "webp";
+            }>>;
             overwrite: import("zod").ZodBoolean;
         };
         execute(args: {
             prompt: string;
             outputPath: string;
             overwrite: boolean;
+            size?: string | undefined;
+            outputFormat?: "png" | "jpeg" | "webp" | undefined;
         }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
     };
     pixelforge_generate_image_from_image: {
@@ -27,6 +35,12 @@ export declare function createPixelForgeTools(context: RunnerContext): {
             prompt: import("zod").ZodString;
             outputPath: import("zod").ZodString;
             strength: import("zod").ZodOptional<import("zod").ZodNumber>;
+            size: import("zod").ZodOptional<import("zod").ZodString>;
+            outputFormat: import("zod").ZodOptional<import("zod").ZodEnum<{
+                png: "png";
+                jpeg: "jpeg";
+                webp: "webp";
+            }>>;
             overwrite: import("zod").ZodBoolean;
         };
         execute(args: {
@@ -35,6 +49,8 @@ export declare function createPixelForgeTools(context: RunnerContext): {
             outputPath: string;
             overwrite: boolean;
             strength?: number | undefined;
+            size?: string | undefined;
+            outputFormat?: "png" | "jpeg" | "webp" | undefined;
         }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
     };
     pixelforge_check_image_job: {

package/dist/tools.js

@@ -23,12 +23,24 @@ export function createPixelForgeTools(context) {
                     .string()
                     .min(1)
                     .describe("File path where the generated image should be written. Relative paths are resolved from the current session directory."),
+                size: tool.schema
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Optional image size as "<width>x<height>", e.g. "1024x1024". When omitted, the provider default is used.'),
+                outputFormat: tool.schema
+                    .enum(["png", "jpeg", "webp"])
+                    .optional()
+                    .describe("Optional output image format. When omitted, the provider default is used."),
                 overwrite: tool.schema.boolean().describe("Whether to overwrite the output file if it already exists."),
             },
             async execute(args, opencodeContext) {
                 const outputPath = resolveWorkspacePath(args.outputPath, opencodeContext.directory, opencodeContext.worktree);
                 const job = context.jobs.create({ kind: "text-to-image", prompt: args.prompt, outputPath });
-                startTextToImageJob({ ...context, sessionID: opencodeContext.sessionID }, job, args.overwrite);
+                startTextToImageJob({ ...context, sessionID: opencodeContext.sessionID }, job, args.overwrite, {
+                    ...(args.size !== undefined ? { size: args.size } : {}),
+                    ...(args.outputFormat !== undefined ? { outputFormat: args.outputFormat } : {}),
+                });
                 return JSON.stringify({
                     jobId: job.id,
                     status: "queued",
@@ -59,6 +71,15 @@ export function createPixelForgeTools(context) {
                     .max(1)
                     .optional()
                     .describe("How strongly the generated result may diverge from the base image, from 0 to 1."),
+                size: tool.schema
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Optional image size as "<width>x<height>", e.g. "1024x1024". When omitted, the provider default is used.'),
+                outputFormat: tool.schema
+                    .enum(["png", "jpeg", "webp"])
+                    .optional()
+                    .describe("Optional output image format. When omitted, the provider default is used."),
                 overwrite: tool.schema.boolean().describe("Whether to overwrite the output file if it already exists."),
             },
             async execute(args, opencodeContext) {
@@ -70,7 +91,10 @@ export function createPixelForgeTools(context) {
                     baseImagePath,
                     outputPath,
                 });
-                startImageToImageJob({ ...context, sessionID: opencodeContext.sessionID }, job, args.overwrite, args.strength);
+                startImageToImageJob({ ...context, sessionID: opencodeContext.sessionID }, job, args.overwrite, args.strength, {
+                    ...(args.size !== undefined ? { size: args.size } : {}),
+                    ...(args.outputFormat !== undefined ? { outputFormat: args.outputFormat } : {}),
+                });
                 return JSON.stringify({
                     jobId: job.id,
                     status: "queued",

package/dist/types.d.ts

@@ -14,15 +14,23 @@ export type ImageResult = {
     mimeType: string;
     provider: ProviderName;
 };
+export type RenderOptions = {
+    size?: string;
+    outputFormat?: "png" | "jpeg" | "webp";
+};
 export type TextToImageRequest = {
     prompt: string;
     signal: AbortSignal;
+    size?: string;
+    outputFormat?: "png" | "jpeg" | "webp";
 };
 export type ImageToImageRequest = {
     baseImagePath: string;
     prompt: string;
     strength?: number;
     signal: AbortSignal;
+    size?: string;
+    outputFormat?: "png" | "jpeg" | "webp";
 };
 export type ImageAdapter = {
     provider: ProviderName;
@@ -40,15 +48,12 @@ export type NotificationConfig = {
 export type BaseProfile = {
     provider: ProviderName;
     timeoutMs: number;
-    outputFormat?: "png" | "jpeg" | "webp";
-    defaultStrength?: number;
 };
 export type OpenAIImagesProfile = BaseProfile & {
     provider: "openai-images";
     apiKey: SecretValue;
     model: string;
     baseUrl: string;
-    size: string;
     quality?: "low" | "medium" | "high" | "auto";
 };
 export type FalProfile = BaseProfile & {
@@ -56,7 +61,6 @@ export type FalProfile = BaseProfile & {
     apiKey: SecretValue;
     endpoint: string;
     imageToImageEndpoint: string;
-    imageSize?: string;
 };
 export type ReplicateProfile = BaseProfile & {
     provider: "replicate";
@@ -73,8 +77,6 @@ export type StabilityAIProfile = BaseProfile & {
     baseUrl: string;
     textToImagePath: string;
     imageToImagePath: string;
-    width?: number;
-    height?: number;
 };
 export type RawProfile = OpenAIImagesProfile | FalProfile | ReplicateProfile | StabilityAIProfile;
 export type RawPixelForgeConfig = {

package/examples/pixelforge.minimal.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://raw.githubusercontent.com/Suknna/pixelforge/main/schema/pixelforge.schema.json",
+  "defaultProfile": "openai",
+  "profiles": {
+    "openai": {
+      "provider": "openai-images",
+      "apiKey": { "env": "OPENAI_API_KEY" },
+      "model": "gpt-image-1",
+      "baseUrl": "https://api.openai.com/v1",
+      "timeoutMs": 180000
+    }
+  }
+}

package/examples/pixelforge.openai-fal-replicate.json

@@ -0,0 +1,36 @@
+{
+  "defaultProfile": "primary-openai",
+  "fallbackProfiles": ["fal-backup", "replicate-backup"],
+  "notifications": {
+    "tui": true,
+    "sessionMessage": true,
+    "autoContinue": false
+  },
+  "profiles": {
+    "primary-openai": {
+      "provider": "openai-images",
+      "apiKey": { "env": "OPENAI_API_KEY" },
+      "model": "gpt-image-1",
+      "baseUrl": "https://api.openai.com/v1",
+      "quality": "medium",
+      "timeoutMs": 180000
+    },
+    "fal-backup": {
+      "provider": "fal",
+      "apiKey": { "env": "FAL_KEY" },
+      "endpoint": "fal-ai/flux/dev",
+      "imageToImageEndpoint": "fal-ai/flux/dev/image-to-image",
+      "timeoutMs": 180000
+    },
+    "replicate-backup": {
+      "provider": "replicate",
+      "apiToken": { "env": "REPLICATE_API_TOKEN" },
+      "version": "black-forest-labs/flux-schnell",
+      "promptInputKey": "prompt",
+      "imageInputKey": "image",
+      "strengthInputKey": "prompt_strength",
+      "pollIntervalMs": 2000,
+      "timeoutMs": 300000
+    }
+  }
+}

package/examples/pixelforge.stability.json

@@ -0,0 +1,19 @@
+{
+  "defaultProfile": "stability",
+  "fallbackProfiles": [],
+  "notifications": {
+    "tui": true,
+    "sessionMessage": false,
+    "autoContinue": false
+  },
+  "profiles": {
+    "stability": {
+      "provider": "stability-ai",
+      "apiKey": { "env": "STABILITY_API_KEY" },
+      "baseUrl": "https://api.stability.ai",
+      "textToImagePath": "/v2beta/stable-image/generate/core",
+      "imageToImagePath": "/v2beta/stable-image/edit/search-and-replace",
+      "timeoutMs": 240000
+    }
+  }
+}

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@suknna/pixelforge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "OpenCode plugin that provides background image generation tools.",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "schema",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -41,6 +47,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "keywords": ["opencode", "plugin", "image-generation", "pixel-forge"],
+  "keywords": [
+    "opencode",
+    "plugin",
+    "image-generation",
+    "pixel-forge"
+  ],
   "license": "MIT"
 }

package/schema/pixelforge.schema.json

@@ -0,0 +1,177 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/Suknna/pixelforge/main/schema/pixelforge.schema.json",
+  "title": "PixelForge Config",
+  "description": "Configuration for the PixelForge opencode plugin. Lives at ~/.config/opencode/pixelforge.json. The plugin fails fast at startup if this file is missing or invalid. Render parameters (size, output format, strength) are supplied by the model through the tools, not configured here.",
+  "type": "object",
+  "required": ["defaultProfile", "profiles"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional reference to this JSON Schema for editor validation."
+    },
+    "defaultProfile": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Name of the profile tried first for every job. Must be a key in profiles."
+    },
+    "fallbackProfiles": {
+      "type": "array",
+      "description": "Explicit, ordered list of profiles tried after the default. Only profiles listed here are ever attempted, and only on transient errors (network failure, timeout, HTTP 429, HTTP 5xx). Each entry must be a key in profiles.",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "notifications": { "$ref": "#/$defs/notifications" },
+    "profiles": {
+      "type": "object",
+      "description": "Map of profile name to provider configuration.",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/$defs/profile" }
+    }
+  },
+  "$defs": {
+    "secret": {
+      "description": "A secret value: either a plain string or an environment-variable reference.",
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "object",
+          "required": ["env"],
+          "additionalProperties": false,
+          "properties": {
+            "env": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Name of the environment variable holding the secret."
+            }
+          }
+        }
+      ]
+    },
+    "notifications": {
+      "type": "object",
+      "description": "Completion notification toggles.",
+      "additionalProperties": false,
+      "properties": {
+        "tui": {
+          "type": "boolean",
+          "description": "Show an opencode TUI Toast when a job completes, naming the provider that produced the image."
+        },
+        "sessionMessage": {
+          "type": "boolean",
+          "description": "Inject a completion message into the current session."
+        },
+        "autoContinue": {
+          "type": "boolean",
+          "description": "Allow a completed background job to trigger the model to continue. Off by default."
+        }
+      }
+    },
+    "timeoutMs": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Per-request timeout in milliseconds. Must be a positive integer."
+    },
+    "profile": {
+      "oneOf": [
+        { "$ref": "#/$defs/openaiImagesProfile" },
+        { "$ref": "#/$defs/falProfile" },
+        { "$ref": "#/$defs/replicateProfile" },
+        { "$ref": "#/$defs/stabilityAiProfile" }
+      ]
+    },
+    "openaiImagesProfile": {
+      "type": "object",
+      "description": "OpenAI Images provider profile.",
+      "required": ["provider", "apiKey", "model", "baseUrl", "timeoutMs"],
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "const": "openai-images" },
+        "apiKey": { "$ref": "#/$defs/secret" },
+        "model": { "type": "string", "minLength": 1, "description": "Image model id, e.g. gpt-image-1." },
+        "baseUrl": { "type": "string", "minLength": 1, "description": "API base URL, e.g. https://api.openai.com/v1." },
+        "quality": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "auto"],
+          "description": "Optional OpenAI-only image quality. Other providers ignore it."
+        },
+        "timeoutMs": { "$ref": "#/$defs/timeoutMs" }
+      }
+    },
+    "falProfile": {
+      "type": "object",
+      "description": "fal provider profile.",
+      "required": ["provider", "apiKey", "endpoint", "imageToImageEndpoint", "timeoutMs"],
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "const": "fal" },
+        "apiKey": { "$ref": "#/$defs/secret" },
+        "endpoint": { "type": "string", "minLength": 1, "description": "Text-to-image endpoint, e.g. fal-ai/flux/dev." },
+        "imageToImageEndpoint": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Image-to-image endpoint, e.g. fal-ai/flux/dev/image-to-image."
+        },
+        "timeoutMs": { "$ref": "#/$defs/timeoutMs" }
+      }
+    },
+    "replicateProfile": {
+      "type": "object",
+      "description": "Replicate provider profile.",
+      "required": [
+        "provider",
+        "apiToken",
+        "version",
+        "promptInputKey",
+        "imageInputKey",
+        "pollIntervalMs",
+        "timeoutMs"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "const": "replicate" },
+        "apiToken": { "$ref": "#/$defs/secret" },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Replicate model or version reference, e.g. black-forest-labs/flux-schnell."
+        },
+        "promptInputKey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Input key the model expects for the text prompt, e.g. prompt."
+        },
+        "imageInputKey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Input key the model expects for the base image, e.g. image."
+        },
+        "strengthInputKey": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional input key the model expects for strength, e.g. prompt_strength."
+        },
+        "pollIntervalMs": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Prediction poll interval in milliseconds. Must be a positive integer."
+        },
+        "timeoutMs": { "$ref": "#/$defs/timeoutMs" }
+      }
+    },
+    "stabilityAiProfile": {
+      "type": "object",
+      "description": "Stability AI provider profile.",
+      "required": ["provider", "apiKey", "baseUrl", "textToImagePath", "imageToImagePath", "timeoutMs"],
+      "additionalProperties": false,
+      "properties": {
+        "provider": { "const": "stability-ai" },
+        "apiKey": { "$ref": "#/$defs/secret" },
+        "baseUrl": { "type": "string", "minLength": 1, "description": "Stability API base URL." },
+        "textToImagePath": { "type": "string", "minLength": 1, "description": "Text-to-image request path." },
+        "imageToImagePath": { "type": "string", "minLength": 1, "description": "Image-to-image request path." },
+        "timeoutMs": { "$ref": "#/$defs/timeoutMs" }
+      }
+    }
+  }
+}