@j-o-r/hello-dave 0.0.10 → 0.1.0

package/lib/API/stability.ai/image.js

@@ -0,0 +1,911 @@
+/**
+ * @file lib/API/stability.ai/image.js
+ * @module stability.ai/image
+ * @description Pure HTTP wrapper for the Stability AI Stable Image API (v2beta).
+ *              Fully aligned with the official specifications extracted from:
+ *              - lib/API/stability.ai/image.md
+ *              - lib/API/stability.ai/openapi.json
+ *
+ *              This is a clean, production-ready library providing core image workflows:
+ *              1. generateUltra()     → Highest quality photorealistic generation
+ *              2. generateCore()      → Fast & affordable generation
+ *              3. generateSD3()       → Stable Diffusion 3.5 (text-to-image + image-to-image)
+ *              4. upscaleConservative() → Detail-preserving upscale to 4MP
+ *              5. editErase()         → Remove objects using mask or alpha
+ *              6. editInpaint()       → Intelligent inpainting / search-and-replace
+ *              7. editOutpaint()      → Expand image in any direction
+ *              8. editSearchAndReplace() → Auto-segment and replace object
+ *              9. editSearchAndRecolor() → Change color of specific object
+ *             10. editRemoveBackground() → Segment and remove background
+ *             11. editReplaceBackgroundAndRelight() → Swap background + relight (async)
+ *             12. fetchImageResult()  → Manual polling for async generation results
+ *
+ *              Many endpoints support async (202 + polling via /v2beta/results/{id}).
+ *              High-level methods handle submission + internal polling and return
+ *              a local image file path plus rich metadata.
+ *
+ *              Key Technical Details:
+ *              - Uses `multipart/form-data` for all image uploads.
+ *              - Supports local paths, remote URLs, Buffers, and Blobs.
+ *              - Binary (`image/*`) or JSON (`application/json` for base64) responses.
+ *              - Output formats: png (default), jpeg, webp.
+ *              - Comprehensive error handling matching the spec.
+ *
+ *              Usage Pattern (recommended):
+ *              ```js
+ *              import { generateUltra, editInpaint } from './image.js';
+ *              const result = await generateUltra('majestic mountain landscape at sunset');
+ *              ```
+ *
+ *              @see {@link https://platform.stability.ai/docs} Official Stability AI docs
+ *              @see {@link ./image.md} Detailed API specification
+ */
+
+/**
+ * @constant {string} BASE_URL
+ * @description Base URL for the Stability AI API v2beta image endpoints.
+ */
+const BASE_URL = 'https://api.stability.ai';
+
+/**
+ * @constant {string} TMP_DIR
+ * @description Local temporary directory for storing generated and reference image files.
+ *              Located at `<cwd>/.cache/stability`.
+ */
+const TMP_DIR = path.join(process.cwd(), '.cache', 'stability');
+
+import { request as doRequest } from '@j-o-r/apiserver';
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Builds authenticated headers for Stability AI requests.
+ *
+ * @param {string} [acceptHeader='image/*'] - Accept header value.
+ *        Use `'image/*'` for binary image response or `'application/json'` for base64 JSON.
+ * @returns {Object} Headers object containing Authorization (Bearer) and Accept.
+ * @throws {Error} If `STABILITY_API_KEY` environment variable is not set.
+ */
+const getHeaders = (acceptHeader = 'image/*') => {
+  if (!process.env.STABILITY_API_KEY) {
+    throw new Error('Missing STABILITY_API_KEY! Please export STABILITY_API_KEY=your_key');
+  }
+  return {
+    'Authorization': `Bearer ${process.env.STABILITY_API_KEY}`,
+    'Accept': acceptHeader
+  };
+};
+
+/**
+ * Ensures the temporary directory for image files exists.
+ *
+ * @async
+ * @returns {Promise<void>}
+ */
+async function ensureTmpDir() {
+  await fs.mkdir(TMP_DIR, { recursive: true });
+}
+
+/**
+ * Saves image data (Buffer, base64 string, URL, Blob, or ArrayBuffer) to a local file.
+ *
+ * @async
+ * @param {Buffer|string|Blob|ArrayBuffer} imageData - Image content to save.
+ * @param {string} [filenamePrefix='stability-image'] - Prefix for the generated filename.
+ * @param {string} [ext='png'] - File extension (`png`, `jpeg`, `webp`).
+ * @returns {Promise<string>} Absolute local file path of the saved image.
+ * @throws {Error} For unsupported formats or download failures.
+ */
+async function saveImageToLocal(imageData, filenamePrefix = 'stability-image', ext = 'png') {
+  await ensureTmpDir();
+
+  const filename = `${filenamePrefix}-${Date.now()}.${ext}`;
+  const localPath = path.join(TMP_DIR, filename);
+
+  let buffer;
+  if (typeof imageData === 'string') {
+    if (imageData.startsWith('http')) {
+      const response = await fetch(imageData);
+      if (!response.ok) {
+        throw new Error(`Failed to download image: ${response.status} ${response.statusText}`);
+      }
+      buffer = Buffer.from(await response.arrayBuffer());
+    } else if (imageData.match(/^[A-Za-z0-9+/=]+$/)) {
+      buffer = Buffer.from(imageData, 'base64');
+    } else {
+      throw new Error('Unsupported imageData string format');
+    }
+  } else if (imageData instanceof Buffer) {
+    buffer = imageData;
+  } else if (imageData instanceof Blob || imageData instanceof ArrayBuffer) {
+    buffer = Buffer.from(await (imageData instanceof Blob ? imageData.arrayBuffer() : imageData));
+  } else {
+    throw new Error('Unsupported imageData type for saving');
+  }
+
+  await fs.writeFile(localPath, buffer);
+  return localPath;
+}
+
+/* ============================================================
+   INTERNAL: Submit image generation request
+   ============================================================ */
+
+async function submitImageGeneration(endpoint, formData, acceptHeader = 'image/*') {
+  const url = `${BASE_URL}/v2beta/${endpoint}`;
+  const headers = getHeaders(acceptHeader);
+
+  const res = await doRequest(url, 'POST', headers, formData);
+
+  if (res.status === 200 || res.status === 202) {
+    if (res.response?.id) {
+      return res.response.id;
+    }
+    // Some endpoints return the image directly on 200
+    return res;
+  }
+
+  if (res.status >= 400) {
+    throw new Error(`Stability API error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  throw new Error(`Unexpected status ${res.status} from ${endpoint}`);
+}
+
+/* ============================================================
+   INTERNAL: Poll for image result
+   ============================================================ */
+
+async function pollForImageResult(id, acceptHeader = 'image/*', maxAttempts = 60, intervalMs = 5000) {
+  const url = `${BASE_URL}/v2beta/results/${id}`;
+  const headers = getHeaders(acceptHeader);
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const res = await doRequest(url, 'GET', headers);
+
+    if (res.status === 200) {
+      return res;
+    }
+
+    if (res.status === 202) {
+      await new Promise(resolve => setTimeout(resolve, intervalMs));
+      continue;
+    }
+
+    if (res.status === 404) {
+      throw new Error(`Generation ${id} not found or expired`);
+    }
+
+    throw new Error(`Poll error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  throw new Error(`Timeout after ${maxAttempts} attempts polling generation ${id}`);
+}
+
+/* ============================================================
+   INTERNAL: Process image result
+   ============================================================ */
+
+async function processImageResult(res, options = {}) {
+  const prefix = options.filenamePrefix || 'stability-image';
+  const ext = options.output_format || 'png';
+
+  if (res.responseType === 'blob') {
+    const buffer = Buffer.from(await res.response.arrayBuffer());
+    const localPath = await saveImageToLocal(buffer, prefix, ext);
+
+    return {
+      local_path: localPath,
+      finish_reason: res.headers.get('finish-reason') || 'SUCCESS',
+      seed: res.headers.get('seed'),
+      x_request_id: res.headers.get('x-request-id'),
+      raw: { headers: Object.fromEntries(res.headers.entries()) }
+    };
+  }
+
+  if (res.responseType === 'js' || typeof res.response === 'object') {
+    const data = res.response;
+    let localPath = null;
+
+    if (data.image && typeof data.image === 'string') {
+      localPath = await saveImageToLocal(data.image, prefix, ext);
+    }
+
+    return {
+      local_path: localPath,
+      image_base64: data.image || null,
+      seed: data.seed,
+      finish_reason: data.finish_reason || 'SUCCESS',
+      raw: data
+    };
+  }
+
+  return {
+    raw: res.response,
+    status: res.status
+  };
+}
+
+/* ============================================================
+   HELPER: Append image file/URL to FormData
+   ============================================================ */
+
+async function appendImageToFormData(formData, imageInput, fieldName = 'image') {
+  if (!imageInput) {
+    throw new Error(`${fieldName} input is required (file path, URL, Buffer, or Blob)`);
+  }
+
+  let filePath;
+  let filename;
+  let mimeType = 'image/png';
+
+  if (typeof imageInput === 'string') {
+    if (imageInput.startsWith('http://') || imageInput.startsWith('https://')) {
+      const response = await fetch(imageInput);
+      if (!response.ok) {
+        throw new Error(`Failed to download reference image: ${response.status} ${response.statusText}`);
+      }
+      const buffer = Buffer.from(await response.arrayBuffer());
+      await ensureTmpDir();
+      const tempFilename = `temp-ref-${Date.now()}.png`;
+      filePath = path.join(TMP_DIR, tempFilename);
+      await fs.writeFile(filePath, buffer);
+      filename = tempFilename;
+    } else {
+      filePath = imageInput;
+      filename = path.basename(imageInput);
+      const ext = path.extname(imageInput).toLowerCase();
+      mimeType = ext === '.jpg' || ext === '.jpeg' ? 'image/jpeg' : ext === '.webp' ? 'image/webp' : 'image/png';
+    }
+  } else if (imageInput instanceof Buffer) {
+    await ensureTmpDir();
+    const tempFilename = `temp-image-${Date.now()}.png`;
+    filePath = path.join(TMP_DIR, tempFilename);
+    await fs.writeFile(filePath, imageInput);
+    filename = tempFilename;
+  } else if (imageInput instanceof Blob) {
+    await ensureTmpDir();
+    const buffer = Buffer.from(await imageInput.arrayBuffer());
+    const tempFilename = imageInput.name || `temp-image-${Date.now()}.png`;
+    filePath = path.join(TMP_DIR, tempFilename);
+    await fs.writeFile(filePath, buffer);
+    filename = tempFilename;
+    mimeType = imageInput.type || 'image/png';
+  } else {
+    throw new Error(`${fieldName} must be a file path (string), URL (string), Buffer, or Blob`);
+  }
+
+  const buffer = await fs.readFile(filePath);
+  const blob = new Blob([buffer], { type: mimeType });
+  formData.append(fieldName, blob, filename);
+}
+
+/* ============================================================
+   WORKFLOW: GENERATE ULTRA
+   ============================================================ */
+
+/**
+ * Generates the highest quality photorealistic image using Stable Image Ultra.
+ *
+ * Our most advanced text-to-image model based on Stable Diffusion 3.5.
+ * Produces exceptional detail, realism, and prompt adherence — ideal for professional print and large-format applications.
+ *
+ * **Constraints** (from Stable Image Ultra spec):
+ * - Prompt: Max 10,000 characters. Strong descriptive prompt recommended.
+ * - Aspect ratio: One of `1:1` (default), `16:9`, `9:16`, `21:9`, `9:21`, `2:3`, `3:2`, `4:5`, `5:4`.
+ * - Image-to-image: Provide `image` + `strength` (0–1). Image must be 64px–16,384px per side.
+ * - Output resolution: 1 megapixel (default 1024×1024).
+ * - Cost: 8 credits per successful generation.
+ * - Output formats: `png` (default), `jpeg`, `webp`.
+ *
+ * @async
+ * @function generateUltra
+ * @param {string} prompt - Required descriptive prompt. Must be non-empty English string (max 10,000 chars).
+ * @param {Object} [options={}] - Optional generation parameters.
+ * @param {string} [options.negative_prompt] - Keywords describing what you do **not** want to see.
+ * @param {string} [options.aspect_ratio='1:1'] - Controls aspect ratio of the output image.
+ * @param {number} [options.seed=0] - Specific seed for reproducibility (0 = random, 0–4,294,967,294).
+ * @param {string} [options.output_format='png'] - `'png'`, `'jpeg'`, or `'webp'`.
+ * @param {string|Buffer|Blob} [options.image] - Optional reference image for image-to-image generation.
+ * @param {number} [options.strength] - Denoising strength (0–1). Required when `image` is provided.
+ * @param {string} [options.style_preset] - Guides the model toward a particular style (e.g. 'photographic', 'cinematic').
+ * @param {string} [options.accept='image/*'] - `'image/*'` (binary) or `'application/json'` (base64).
+ * @param {string} [options.filenamePrefix='stability-ultra'] - Prefix for saved local file.
+ * @returns {Promise<Object>} Standardized result:
+ *          ```js
+ *          {
+ *            local_path: '/path/to/.cache/stability/stability-ultra-1234567890.png',
+ *            finish_reason: 'SUCCESS',
+ *            seed: 123456789,
+ *            x_request_id: 'req_...',
+ *            raw: { headers: {...} }   // or full JSON if accept=application/json
+ *          }
+ *          ```
+ * @throws {Error} - 'Missing STABILITY_API_KEY', invalid prompt, API errors (400/403/422/429/500), polling timeout, or download failures.
+ *
+ * @example
+ * // Basic text-to-image
+ * const result = await generateUltra('majestic mountain landscape at sunset, cinematic lighting');
+ * console.log('Saved to:', result.local_path);
+ *
+ * @example
+ * // Image-to-image with strength
+ * const result = await generateUltra(
+ *   'same scene but with dramatic storm clouds',
+ *   {
+ *     image: './reference.png',
+ *     strength: 0.65,
+ *     aspect_ratio: '16:9',
+ *     output_format: 'webp'
+ *   }
+ * );
+ */
+async function generateUltra(prompt, options = {}) {
+  if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('generateUltra() requires a non-empty prompt string');
+  }
+
+  const formData = new FormData();
+  formData.append('prompt', prompt);
+
+  if (options.negative_prompt) formData.append('negative_prompt', options.negative_prompt);
+  if (options.aspect_ratio) formData.append('aspect_ratio', options.aspect_ratio);
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.output_format) formData.append('output_format', options.output_format);
+  if (options.style_preset) formData.append('style_preset', options.style_preset);
+
+  if (options.image) {
+    await appendImageToFormData(formData, options.image, 'image');
+    if (options.strength != null) formData.append('strength', String(options.strength));
+  }
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/generate/ultra', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-ultra' });
+  }
+
+  const id = result;
+  const polled = await pollForImageResult(id, accept);
+  return processImageResult(polled, { ...options, filenamePrefix: 'stability-ultra' });
+}
+
+/* ============================================================
+   WORKFLOW: GENERATE CORE
+   ============================================================ */
+
+/**
+ * Generates fast and affordable images using Stable Image Core.
+ *
+ * Optimized for rapid iteration during ideation. Next-generation model following SDXL.
+ *
+ * **Constraints**:
+ * - Prompt: Max 10,000 characters.
+ * - Aspect ratio: Same options as Ultra.
+ * - Output resolution: 1.5 megapixels.
+ * - Cost: 3 credits per successful generation.
+ *
+ * @async
+ * @function generateCore
+ * @param {string} prompt - Required descriptive prompt.
+ * @param {Object} [options={}] - Optional parameters (negative_prompt, aspect_ratio, seed, output_format, style_preset, accept, filenamePrefix).
+ * @returns {Promise<Object>} Same result structure as generateUltra.
+ */
+async function generateCore(prompt, options = {}) {
+  if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('generateCore() requires a non-empty prompt string');
+  }
+
+  const formData = new FormData();
+  formData.append('prompt', prompt);
+
+  if (options.negative_prompt) formData.append('negative_prompt', options.negative_prompt);
+  if (options.aspect_ratio) formData.append('aspect_ratio', options.aspect_ratio);
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.output_format) formData.append('output_format', options.output_format);
+  if (options.style_preset) formData.append('style_preset', options.style_preset);
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/generate/core', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-core' });
+  }
+
+  const id = result;
+  const polled = await pollForImageResult(id, accept);
+  return processImageResult(polled, { ...options, filenamePrefix: 'stability-core' });
+}
+
+/* ============================================================
+   WORKFLOW: GENERATE SD3
+   ============================================================ */
+
+/**
+ * Generates images using Stable Diffusion 3.5 models.
+ *
+ * Supports `sd3.5-large`, `sd3.5-large-turbo`, `sd3.5-medium`, `sd3.5-flash`.
+ *
+ * **Key Parameters**:
+ * - `mode`: `'text-to-image'` (default) or `'image-to-image'`.
+ * - For image-to-image: `image` + `strength` required.
+ * - `cfg_scale`: Prompt adherence (default 4 for Large/Medium, 1 for Turbo/Flash).
+ *
+ * @async
+ * @function generateSD3
+ * @param {string} prompt - Required prompt.
+ * @param {Object} [options={}] - Optional parameters including `mode`, `model`, `image`, `strength`, `cfg_scale`, etc.
+ * @returns {Promise<Object>} Same result structure.
+ */
+async function generateSD3(prompt, options = {}) {
+  if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('generateSD3() requires a non-empty prompt string');
+  }
+
+  const formData = new FormData();
+  formData.append('prompt', prompt);
+  formData.append('mode', options.mode || 'text-to-image');
+
+  if (options.negative_prompt) formData.append('negative_prompt', options.negative_prompt);
+  if (options.aspect_ratio) formData.append('aspect_ratio', options.aspect_ratio);
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.output_format) formData.append('output_format', options.output_format);
+  if (options.style_preset) formData.append('style_preset', options.style_preset);
+  if (options.cfg_scale != null) formData.append('cfg_scale', String(options.cfg_scale));
+  if (options.model) formData.append('model', options.model);
+
+  if (options.image) {
+    await appendImageToFormData(formData, options.image, 'image');
+    if (options.strength != null) formData.append('strength', String(options.strength));
+  }
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/generate/sd3', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-sd3' });
+  }
+
+  const id = result;
+  const polled = await pollForImageResult(id, accept);
+  return processImageResult(polled, { ...options, filenamePrefix: 'stability-sd3' });
+}
+
+/* ============================================================
+   WORKFLOW: UPSCALE CONSERVATIVE
+   ============================================================ */
+
+/**
+ * Upscales an image conservatively while preserving original details.
+ *
+ * Takes images 64×64 to 1MP and upscales to 4MP with minimal alteration.
+ *
+ * **Constraints**:
+ * - Image: 64px–9,437,184 total pixels, aspect ratio 1:2.5 to 2.5:1.
+ * - Cost: 40 credits.
+ *
+ * @async
+ * @function upscaleConservative
+ * @param {string|Buffer|Blob} imageInput - Image to upscale.
+ * @param {string} prompt - Prompt describing desired output.
+ * @param {Object} [options={}] - Optional: negative_prompt, seed, output_format, creativity (0.2–0.5).
+ * @returns {Promise<Object>} Result with upscaled image.
+ */
+async function upscaleConservative(imageInput, prompt, options = {}) {
+  if (!imageInput) {
+    throw new Error('upscaleConservative() requires an image input');
+  }
+  if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('upscaleConservative() requires a prompt');
+  }
+
+  const formData = new FormData();
+  await appendImageToFormData(formData, imageInput, 'image');
+  formData.append('prompt', prompt);
+
+  if (options.negative_prompt) formData.append('negative_prompt', options.negative_prompt);
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.output_format) formData.append('output_format', options.output_format);
+  if (options.creativity != null) formData.append('creativity', String(options.creativity));
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/upscale/conservative', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-upscale-conservative' });
+  }
+
+  const id = result;
+  const polled = await pollForImageResult(id, accept);
+  return processImageResult(polled, { ...options, filenamePrefix: 'stability-upscale-conservative' });
+}
+
+/* ============================================================
+   EDIT: ERASE
+   ============================================================ */
+
+/**
+ * Removes unwanted objects from an image using a mask or the alpha channel.
+ *
+ * The mask can be provided explicitly or derived from the alpha channel of the input image.
+ *
+ * **Constraints**:
+ * - Image: 64px–9,437,184 total pixels.
+ * - Cost: 5 credits.
+ *
+ * @async
+ * @function editErase
+ * @param {string|Buffer|Blob} imageInput - Image to edit.
+ * @param {Object} [options={}] - Optional parameters.
+ * @param {string|Buffer|Blob} [options.mask] - Optional mask image.
+ * @param {number} [options.grow_mask=5] - Grow mask edges by this many pixels.
+ * @param {number} [options.seed=0]
+ * @param {string} [options.output_format='png']
+ * @returns {Promise<Object>} Result with edited image.
+ */
+async function editErase(imageInput, options = {}) {
+  if (!imageInput) {
+    throw new Error('editErase() requires an image input');
+  }
+
+  const formData = new FormData();
+  await appendImageToFormData(formData, imageInput, 'image');
+
+  if (options.mask) await appendImageToFormData(formData, options.mask, 'mask');
+  if (options.grow_mask != null) formData.append('grow_mask', String(options.grow_mask));
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.output_format) formData.append('output_format', options.output_format);
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/edit/erase', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-edit-erase' });
+  }
+
+  const id = result;
+  const polled = await pollForImageResult(id, accept);
+  return processImageResult(polled, { ...options, filenamePrefix: 'stability-edit-erase' });
+}
+
+/* ============================================================
+   EDIT: INPAINT (enhanced)
+   ============================================================ */
+
+/**
+ * Intelligently modifies images by filling or replacing areas based on a mask or search prompt.
+ *
+ * Supports two modes:
+ * - `mask` mode: Provide explicit `mask` or use alpha channel.
+ * - `search` mode: Provide `search_prompt` for automatic object segmentation.
+ *
+ * **Constraints**:
+ * - Image: 64px–9,437,184 total pixels.
+ * - Cost: 5 credits.
+ *
+ * @async
+ * @function editInpaint
+ * @param {string|Buffer|Blob} imageInput - Base image.
+ * @param {string} prompt - What the replaced area should become.
+ * @param {Object} [options={}] - Optional: negative_prompt, seed, output_format, style_preset, grow_mask, mask, mode, search_prompt.
+ * @returns {Promise<Object>} Result with edited image.
+ */
+async function editInpaint(imageInput, prompt, options = {}) {
+  if (!imageInput) {
+    throw new Error('editInpaint() requires an image input');
+  }
+  if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('editInpaint() requires a prompt');
+  }
+
+  const formData = new FormData();
+  await appendImageToFormData(formData, imageInput, 'image');
+  formData.append('prompt', prompt);
+
+  if (options.negative_prompt) formData.append('negative_prompt', options.negative_prompt);
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.output_format) formData.append('output_format', options.output_format);
+  if (options.style_preset) formData.append('style_preset', options.style_preset);
+  if (options.grow_mask != null) formData.append('grow_mask', String(options.grow_mask));
+
+  if (options.mode === 'search' && options.search_prompt) {
+    formData.append('mode', 'search');
+    formData.append('search_prompt', options.search_prompt);
+  } else if (options.mask) {
+    await appendImageToFormData(formData, options.mask, 'mask');
+  }
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/edit/inpaint', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-edit-inpaint' });
+  }
+
+  const id = result;
+  const polled = await pollForImageResult(id, accept);
+  return processImageResult(polled, { ...options, filenamePrefix: 'stability-edit-inpaint' });
+}
+
+/* ============================================================
+   EDIT: OUTPAINT
+   ============================================================ */
+
+/**
+ * Expands an image by adding content in any direction (left, right, up, down).
+ *
+ * At least one direction must be non-zero.
+ *
+ * **Constraints**:
+ * - Image: 64px–9,437,184 total pixels, aspect ratio 1:2.5–2.5:1.
+ * - Cost: 4 credits.
+ *
+ * @async
+ * @function editOutpaint
+ * @param {string|Buffer|Blob} imageInput - Image to expand.
+ * @param {Object} [options={}] - Direction values in pixels (0–2000).
+ * @param {number} [options.left=0]
+ * @param {number} [options.right=0]
+ * @param {number} [options.up=0]
+ * @param {number} [options.down=0]
+ * @param {string} [options.prompt]
+ * @param {number} [options.creativity=0.5]
+ * @param {string} [options.style_preset]
+ * @returns {Promise<Object>} Result with expanded image.
+ */
+async function editOutpaint(imageInput, options = {}) {
+  if (!imageInput) {
+    throw new Error('editOutpaint() requires an image input');
+  }
+
+  const formData = new FormData();
+  await appendImageToFormData(formData, imageInput, 'image');
+
+  if (options.left != null) formData.append('left', String(options.left));
+  if (options.right != null) formData.append('right', String(options.right));
+  if (options.up != null) formData.append('up', String(options.up));
+  if (options.down != null) formData.append('down', String(options.down));
+
+  if (options.prompt) formData.append('prompt', options.prompt);
+  if (options.creativity != null) formData.append('creativity', String(options.creativity));
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.output_format) formData.append('output_format', options.output_format);
+  if (options.style_preset) formData.append('style_preset', options.style_preset);
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/edit/outpaint', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-edit-outpaint' });
+  }
+
+  const id = result;
+  const polled = await pollForImageResult(id, accept);
+  return processImageResult(polled, { ...options, filenamePrefix: 'stability-edit-outpaint' });
+}
+
+/* ============================================================
+   EDIT: SEARCH AND REPLACE
+   ============================================================ */
+
+/**
+ * Automatically segments an object described by `search_prompt` and replaces it with new content from `prompt`.
+ *
+ * **Constraints**:
+ * - Image: 64px–9,437,184 total pixels.
+ * - Cost: 5 credits.
+ *
+ * @async
+ * @function editSearchAndReplace
+ * @param {string|Buffer|Blob} imageInput - Base image.
+ * @param {string} prompt - What to replace the object with.
+ * @param {string} search_prompt - Short description of the object to find.
+ * @param {Object} [options={}] - Optional: negative_prompt, seed, output_format, style_preset, grow_mask.
+ * @returns {Promise<Object>} Result with edited image.
+ */
+async function editSearchAndReplace(imageInput, prompt, search_prompt, options = {}) {
+  if (!imageInput) {
+    throw new Error('editSearchAndReplace() requires an image input');
+  }
+  if (!prompt || !search_prompt) {
+    throw new Error('editSearchAndReplace() requires prompt and search_prompt');
+  }
+
+  const formData = new FormData();
+  await appendImageToFormData(formData, imageInput, 'image');
+  formData.append('prompt', prompt);
+  formData.append('search_prompt', search_prompt);
+
+  if (options.negative_prompt) formData.append('negative_prompt', options.negative_prompt);
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.output_format) formData.append('output_format', options.output_format);
+  if (options.style_preset) formData.append('style_preset', options.style_preset);
+  if (options.grow_mask != null) formData.append('grow_mask', String(options.grow_mask));
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/edit/search-and-replace', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-edit-search-replace' });
+  }
+
+  const id = result;
+  const polled = await pollForImageResult(id, accept);
+  return processImageResult(polled, { ...options, filenamePrefix: 'stability-edit-search-replace' });
+}
+
+/* ============================================================
+   EDIT: SEARCH AND RECOLOR
+   ============================================================ */
+
+/**
+ * Automatically segments an object and recolors it according to the prompt.
+ *
+ * @async
+ * @function editSearchAndRecolor
+ * @param {string|Buffer|Blob} imageInput - Base image.
+ * @param {string} prompt - Desired new color description.
+ * @param {string} select_prompt - Short description of the object to recolor.
+ * @param {Object} [options={}] - Optional parameters.
+ * @returns {Promise<Object>} Result with recolored image.
+ */
+async function editSearchAndRecolor(imageInput, prompt, select_prompt, options = {}) {
+  if (!imageInput || !prompt || !select_prompt) {
+    throw new Error('editSearchAndRecolor() requires image, prompt, and select_prompt');
+  }
+
+  const formData = new FormData();
+  await appendImageToFormData(formData, imageInput, 'image');
+  formData.append('prompt', prompt);
+  formData.append('select_prompt', select_prompt);
+
+  if (options.negative_prompt) formData.append('negative_prompt', options.negative_prompt);
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.output_format) formData.append('output_format', options.output_format);
+  if (options.style_preset) formData.append('style_preset', options.style_preset);
+  if (options.grow_mask != null) formData.append('grow_mask', String(options.grow_mask));
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/edit/search-and-recolor', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-edit-search-recolor' });
+  }
+
+  const id = result;
+  const polled = await pollForImageResult(id, accept);
+  return processImageResult(polled, { ...options, filenamePrefix: 'stability-edit-search-recolor' });
+}
+
+/* ============================================================
+   EDIT: REMOVE BACKGROUND
+   ============================================================ */
+
+/**
+ * Accurately segments the foreground and removes the background.
+ *
+ * @async
+ * @function editRemoveBackground
+ * @param {string|Buffer|Blob} imageInput - Image to process.
+ * @param {Object} [options={}] - Optional: output_format ('png' or 'webp').
+ * @returns {Promise<Object>} Result with background removed.
+ */
+async function editRemoveBackground(imageInput, options = {}) {
+  if (!imageInput) {
+    throw new Error('editRemoveBackground() requires an image input');
+  }
+
+  const formData = new FormData();
+  await appendImageToFormData(formData, imageInput, 'image');
+  if (options.output_format) formData.append('output_format', options.output_format);
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/edit/remove-background', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-edit-remove-bg' });
+  }
+
+  const id = result;
+  const polled = await pollForImageResult(id, accept);
+  return processImageResult(polled, { ...options, filenamePrefix: 'stability-edit-remove-bg' });
+}
+
+/* ============================================================
+   EDIT: REPLACE BACKGROUND AND RELIGHT (async)
+   ============================================================ */
+
+/**
+ * Replaces the background and adjusts lighting to match the subject.
+ *
+ * Async endpoint — returns a generation ID for polling.
+ *
+ * @async
+ * @function editReplaceBackgroundAndRelight
+ * @param {string|Buffer|Blob} subjectImage - Main subject image.
+ * @param {Object} [options={}] - Optional parameters.
+ * @returns {Promise<string|Object>} Generation ID or processed result.
+ */
+async function editReplaceBackgroundAndRelight(subjectImage, options = {}) {
+  if (!subjectImage) {
+    throw new Error('editReplaceBackgroundAndRelight() requires a subject_image');
+  }
+
+  const formData = new FormData();
+  await appendImageToFormData(formData, subjectImage, 'subject_image');
+
+  if (options.background_prompt) formData.append('background_prompt', options.background_prompt);
+  if (options.background_reference) await appendImageToFormData(formData, options.background_reference, 'background_reference');
+  if (options.foreground_prompt) formData.append('foreground_prompt', options.foreground_prompt);
+  if (options.negative_prompt) formData.append('negative_prompt', options.negative_prompt);
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.output_format) formData.append('output_format', options.output_format);
+
+  const accept = options.accept || 'image/*';
+  const result = await submitImageGeneration('stable-image/edit/replace-background-and-relight', formData, accept);
+
+  if (result && result.status === 200) {
+    return processImageResult(result, { ...options, filenamePrefix: 'stability-edit-replace-bg' });
+  }
+
+  return result; // returns id for async polling
+}
+
+/* ============================================================
+   WORKFLOW: FETCH IMAGE RESULT (manual)
+   ============================================================ */
+
+/**
+ * Manually fetches or checks the status of an image generation using its ID.
+ *
+ * @async
+ * @function fetchImageResult
+ * @param {string} id - Generation ID.
+ * @param {string} [acceptHeader='image/*'] - `'image/*'` or `'application/json'`.
+ * @returns {Promise<Object>} Completed result or `{ status: 'in-progress', id }`.
+ */
+async function fetchImageResult(id, acceptHeader = 'image/*') {
+  if (!id) {
+    throw new Error('fetchImageResult() requires a generation id');
+  }
+
+  const headers = getHeaders(acceptHeader);
+  const url = `${BASE_URL}/v2beta/results/${id}`;
+  const res = await doRequest(url, 'GET', headers);
+
+  if (res.status === 200) {
+    return processImageResult(res);
+  }
+
+  if (res.status === 202) {
+    return {
+      status: 'in-progress',
+      id,
+      raw: res.response
+    };
+  }
+
+  if (res.status === 404) {
+    throw new Error(`Generation ${id} not found or expired`);
+  }
+
+  throw new Error(`fetchImageResult error ${res.status}: ${JSON.stringify(res.response)}`);
+}
+
+export {
+  getHeaders,
+  saveImageToLocal,
+  generateUltra,
+  generateCore,
+  generateSD3,
+  upscaleConservative,
+  editErase,
+  editInpaint,
+  editOutpaint,
+  editSearchAndReplace,
+  editSearchAndRecolor,
+  editRemoveBackground,
+  editReplaceBackgroundAndRelight,
+  fetchImageResult
+};