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

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

@@ -0,0 +1,679 @@
+/**
+ * @file lib/API/stability.ai/audio.js
+ * @module stability.ai/audio
+ * @description Pure HTTP wrapper for the Stability AI Stable Audio 3 API.
+ *              Fully aligned with the official specifications extracted from:
+ *              - lib/API/stability.ai/audio-3.md
+ *              - lib/API/stability.ai/openapi.json
+ *
+ *              This is a clean, production-ready library providing four main workflows:
+ *              1. textToAudio()   → Text-to-audio generation using the `stable-audio-3` model
+ *              2. audioToAudio()  → Audio-to-audio transformation / style transfer
+ *              3. inpaint()       → Audio inpainting with time-based mask (replace sections)
+ *              4. fetchResult()   → Manual polling for async generation results
+ *
+ *              All generation endpoints are asynchronous (HTTP 202 Accepted + polling).
+ *              High-level methods (`textToAudio`, `audioToAudio`, `inpaint`) handle
+ *              submission + internal polling automatically and return a local audio file
+ *              path plus rich metadata.
+ *
+ *              Key Technical Details:
+ *              - Uses `multipart/form-data` for all audio uploads (robust handling of
+ *                local paths, remote URLs, Buffers, and Blobs).
+ *              - Supports both binary (`audio/*`) and JSON (`application/json` for base64) responses.
+ *              - Model: `stable-audio-3` (fixed; 26 credits per successful generation).
+ *              - Max duration: 380 seconds (default 190s). Sample rate: 44.1 kHz stereo.
+ *              - Output formats: `mp3` (default) or `wav`.
+ *              - English prompts only. No copyrighted content permitted.
+ *              - Remote audio URL handling includes automatic download + proper MIME/filename.
+ *              - Comprehensive error handling with specific messages for 400/403/422/429/500.
+ *
+ *              Usage Pattern (recommended):
+ *              ```js
+ *              import { textToAudio, audioToAudio, inpaint } from './audio.js';
+ *              const result = await textToAudio('cinematic orchestral score', { duration: 240 });
+ *              ```
+ *
+ *              @see {@link https://platform.stability.ai/docs} Official Stability AI docs
+ *              @see {@link ./audio-3.md} Detailed API specification
+ */
+
+/**
+ * @constant {string} BASE_URL
+ * @description Base URL for the Stability AI API v2beta audio endpoints.
+ */
+const BASE_URL = 'https://api.stability.ai';
+
+/**
+ * @constant {string} TMP_DIR
+ * @description Local temporary directory for storing generated and reference audio 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='audio/*'] - Accept header value.
+ *        Use `'audio/*'` for binary audio 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.
+ *
+ * @example
+ * const headers = getHeaders('application/json');
+ */
+const getHeaders = (acceptHeader = 'audio/*') => {
+  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 audio files exists.
+ * Creates `.cache/stability` recursively if needed.
+ *
+ * @async
+ * @returns {Promise<void>}
+ */
+async function ensureTmpDir() {
+  await fs.mkdir(TMP_DIR, { recursive: true });
+}
+
+/**
+ * Saves audio data (Buffer, base64 string, URL, Blob, or ArrayBuffer) to a local file.
+ *
+ * @async
+ * @param {Buffer|string|Blob|ArrayBuffer} audioData - Audio content to save.
+ *        - Buffer: raw bytes
+ *        - string starting with 'http': remote URL (auto-downloaded)
+ *        - base64 string: decoded
+ *        - Blob/ArrayBuffer: converted
+ * @param {string} [filenamePrefix='stability-audio'] - Prefix for the generated filename.
+ * @param {string} [ext='mp3'] - File extension (`mp3` or `wav` recommended).
+ * @returns {Promise<string>} Absolute local file path of the saved audio.
+ * @throws {Error} For unsupported formats or download failures.
+ */
+async function saveAudioToLocal(audioData, filenamePrefix = 'stability-audio', ext = 'mp3') {
+  await ensureTmpDir();
+
+  const filename = `${filenamePrefix}-${Date.now()}.${ext}`;
+  const localPath = path.join(TMP_DIR, filename);
+
+  let buffer;
+  if (typeof audioData === 'string') {
+    if (audioData.startsWith('http')) {
+      const response = await fetch(audioData);
+      if (!response.ok) {
+        throw new Error(`Failed to download audio: ${response.status} ${response.statusText}`);
+      }
+      buffer = Buffer.from(await response.arrayBuffer());
+    } else if (audioData.match(/^[A-Za-z0-9+/=]+$/)) {
+      // base64
+      buffer = Buffer.from(audioData, 'base64');
+    } else {
+      throw new Error('Unsupported audioData string format');
+    }
+  } else if (audioData instanceof Buffer) {
+    buffer = audioData;
+  } else if (audioData instanceof Blob || audioData instanceof ArrayBuffer) {
+    buffer = Buffer.from(await (audioData instanceof Blob ? audioData.arrayBuffer() : audioData));
+  } else {
+    throw new Error('Unsupported audioData type for saving');
+  }
+
+  await fs.writeFile(localPath, buffer);
+  return localPath;
+}
+
+/* ============================================================
+   INTERNAL: Submit generation request (returns generation id)
+   ============================================================ */
+
+/**
+ * Submits a generation request to a Stable Audio endpoint.
+ * Internal helper used by textToAudio, audioToAudio, and inpaint.
+ *
+ * @async
+ * @param {string} endpoint - Endpoint slug: 'text-to-audio', 'audio-to-audio', or 'inpaint'.
+ * @param {FormData} formData - Populated multipart form data.
+ * @param {string} [acceptHeader='audio/*'] - Accept header for response type.
+ * @returns {Promise<string>} Generation ID (from 202 response) for polling.
+ * @throws {Error} On non-202 responses or missing ID.
+ */
+async function submitGeneration(endpoint, formData, acceptHeader = 'audio/*') {
+  const url = `${BASE_URL}/v2beta/audio/stable-audio/${endpoint}`;
+  const headers = getHeaders(acceptHeader);
+
+  const res = await doRequest(url, 'POST', headers, formData);
+
+  if (res.status === 202) {
+    const id = res.response?.id;
+    if (!id) {
+      throw new Error(`No generation id in 202 response: ${JSON.stringify(res.response)}`);
+    }
+    return id;
+  }
+
+  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 generation result
+   ============================================================ */
+
+/**
+ * Polls the results endpoint until the generation completes or times out.
+ * Internal helper with exponential backoff-style interval.
+ *
+ * @async
+ * @param {string} id - Generation ID returned by submitGeneration.
+ * @param {string} [acceptHeader='audio/*'] - Accept header.
+ * @param {number} [maxAttempts=72] - Maximum polling attempts (~6 minutes at 5s interval).
+ * @param {number} [intervalMs=5000] - Delay between polls in milliseconds.
+ * @returns {Promise<Object>} The successful 200 response object from doRequest.
+ * @throws {Error} On 404, other errors, or timeout.
+ */
+async function pollForResult(id, acceptHeader = 'audio/*', maxAttempts = 72, intervalMs = 5000) {
+  const url = `${BASE_URL}/v2beta/audio/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) {
+      // still in progress
+      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 result into usable output
+   ============================================================ */
+
+/**
+ * Processes a successful poll result into a standardized output object.
+ * Handles both binary (blob) and JSON (base64) response types.
+ *
+ * @async
+ * @param {Object} res - Response from doRequest or pollForResult.
+ * @param {Object} [options={}] - Processing options.
+ * @param {string} [options.filenamePrefix='stability-audio'] - Filename prefix.
+ * @param {string} [options.output_format='mp3'] - Desired extension.
+ * @returns {Promise<Object>} Standardized result:
+ *          - local_path: string | null (saved file)
+ *          - audio_base64?: string
+ *          - finish_reason, seed, x_request_id, raw metadata
+ */
+async function processResult(res, options = {}) {
+  const prefix = options.filenamePrefix || 'stability-audio';
+  const ext = options.output_format || 'mp3';
+
+  if (res.responseType === 'blob') {
+    const buffer = Buffer.from(await res.response.arrayBuffer());
+    const localPath = await saveAudioToLocal(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.audio && typeof data.audio === 'string') {
+      localPath = await saveAudioToLocal(data.audio, prefix, ext);
+    }
+
+    return {
+      local_path: localPath,
+      audio_base64: data.audio || null,
+      seed: data.seed,
+      finish_reason: data.finish_reason || 'SUCCESS',
+      raw: data
+    };
+  }
+
+  // fallback
+  return {
+    raw: res.response,
+    status: res.status
+  };
+}
+
+/* ============================================================
+   HELPER: Download remote audio to local temp file
+   ============================================================ */
+
+/**
+ * Downloads a remote audio URL to a temporary local file.
+ * Used internally by appendAudioToFormData for robust remote support.
+ *
+ * @async
+ * @param {string} url - HTTP/HTTPS URL to an audio file (mp3/wav recommended).
+ * @returns {Promise<string>} Absolute path to the downloaded temp file.
+ * @throws {Error} If download fails or URL is invalid.
+ */
+async function downloadRemoteAudioToTemp(url) {
+  await ensureTmpDir();
+
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download reference audio: ${response.status} ${response.statusText}`);
+  }
+
+  const buffer = Buffer.from(await response.arrayBuffer());
+
+  // Create a proper filename based on URL
+  let filename = 'reference-audio.mp3';
+  try {
+    const urlObj = new URL(url);
+    const base = path.basename(urlObj.pathname);
+    if (base && base.includes('.')) {
+      filename = base;
+    }
+  } catch (_) {}
+
+  const ext = path.extname(filename).toLowerCase() || '.mp3';
+  const tempFilename = `temp-ref-${Date.now()}${ext}`;
+  const tempPath = path.join(TMP_DIR, tempFilename);
+
+  await fs.writeFile(tempPath, buffer);
+  return tempPath;
+}
+
+/* ============================================================
+   HELPER: Append audio file/URL to FormData (robust)
+   ============================================================ */
+
+/**
+ * Appends an audio input (path, URL, Buffer, or Blob) to a FormData instance
+ * with correct filename and MIME type. Handles remote URLs by downloading first.
+ *
+ * @async
+ * @param {FormData} formData - Target FormData object.
+ * @param {string|Buffer|Blob} audioInput - Audio source:
+ *        - string: local file path or http(s):// URL
+ *        - Buffer: raw audio bytes
+ *        - Blob: browser-style blob with optional .name and .type
+ * @throws {Error} If audioInput is missing or of unsupported type.
+ */
+async function appendAudioToFormData(formData, audioInput) {
+  if (!audioInput) {
+    throw new Error('Audio input is required (file path, URL, Buffer, or Blob)');
+  }
+
+  let filePath;
+  let filename;
+  let mimeType = 'audio/mpeg';
+
+  if (typeof audioInput === 'string') {
+    if (audioInput.startsWith('http://') || audioInput.startsWith('https://')) {
+      // Remote URL → download to temp file first (most reliable)
+      filePath = await downloadRemoteAudioToTemp(audioInput);
+      filename = path.basename(filePath);
+      const ext = path.extname(filePath).toLowerCase();
+      mimeType = ext === '.wav' ? 'audio/wav' : 'audio/mpeg';
+    } else {
+      // Local file path
+      filePath = audioInput;
+      filename = path.basename(audioInput);
+      const ext = path.extname(audioInput).toLowerCase();
+      mimeType = ext === '.wav' ? 'audio/wav' : 'audio/mpeg';
+    }
+  } else if (audioInput instanceof Buffer) {
+    // Write buffer to temp file
+    await ensureTmpDir();
+    const tempFilename = `temp-audio-${Date.now()}.mp3`;
+    filePath = path.join(TMP_DIR, tempFilename);
+    await fs.writeFile(filePath, audioInput);
+    filename = tempFilename;
+  } else if (audioInput instanceof Blob) {
+    // Convert Blob to temp file
+    await ensureTmpDir();
+    const buffer = Buffer.from(await audioInput.arrayBuffer());
+    const tempFilename = audioInput.name || `temp-audio-${Date.now()}.mp3`;
+    filePath = path.join(TMP_DIR, tempFilename);
+    await fs.writeFile(filePath, buffer);
+    filename = tempFilename;
+    mimeType = audioInput.type || 'audio/mpeg';
+  } else {
+    throw new Error('audioInput must be a file path (string), URL (string), Buffer, or Blob');
+  }
+
+  // Read the file and append with proper filename + MIME
+  const buffer = await fs.readFile(filePath);
+  const blob = new Blob([buffer], { type: mimeType });
+  formData.append('audio', blob, filename);
+}
+
+/* ============================================================
+   WORKFLOW 1: TEXT-TO-AUDIO
+   ============================================================ */
+
+/**
+ * Generates high-quality audio from a text prompt using Stable Audio 3.
+ *
+ * This is the primary text-to-audio endpoint. It submits a prompt and optional
+ * parameters, receives a generation ID (202), polls until ready, and returns
+ * the generated audio saved locally plus metadata.
+ *
+ * **Constraints** (from Stable Audio 3 spec):
+ * - Prompt: English only, max 10,000 characters, descriptive (instruments, mood, genre, style).
+ * - Duration: 1–380 seconds (default 190).
+ * - Steps: 4–8 (default 8).
+ * - CFG Scale: 1–25 (default 1).
+ * - Seed: 0 (random) or 0–4,294,967,294.
+ * - Output: mp3 (default) or wav at 44.1 kHz stereo.
+ * - Cost: Flat 26 credits per successful generation.
+ *
+ * @async
+ * @function textToAudio
+ * @param {string} prompt - Required descriptive text prompt. Must be non-empty English string.
+ * @param {Object} [options={}] - Optional generation parameters.
+ * @param {string} [options.model='stable-audio-3'] - Model identifier. Must be exactly `'stable-audio-3'`.
+ * @param {number} [options.duration=190] - Target duration in seconds (1 ≤ duration ≤ 380).
+ * @param {number} [options.seed=0] - Random seed for reproducibility (0 = random).
+ * @param {number} [options.steps=8] - Number of sampling steps (4–8).
+ * @param {number} [options.cfg_scale=1] - Prompt adherence strength (1–25).
+ * @param {string} [options.output_format='mp3'] - `'mp3'` or `'wav'`.
+ * @param {string} [options.accept='audio/*'] - Response format: `'audio/*'` (binary) or `'application/json'`.
+ * @param {string} [options.filenamePrefix='stability-text-to-audio'] - Prefix for saved file.
+ * @returns {Promise<Object>} Result object:
+ *          ```js
+ *          {
+ *            local_path: '/path/to/.cache/stability/stability-text-to-audio-1234567890.mp3',
+ *            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, unsupported model,
+ *                   API errors (400/403/422/429/500), polling timeout, or download failures.
+ *
+ * @example
+ * // Basic usage
+ * const result = await textToAudio('upbeat electronic synthwave with driving bass');
+ * console.log('Saved to:', result.local_path);
+ *
+ * @example
+ * // Advanced with options
+ * const result = await textToAudio(
+ *   'cinematic orchestral music, epic brass, strings, choir, 120 BPM',
+ *   {
+ *     duration: 240,
+ *     seed: 42,
+ *     steps: 8,
+ *     cfg_scale: 7,
+ *     output_format: 'wav',
+ *     accept: 'application/json'
+ *   }
+ * );
+ * if (result.audio_base64) {
+ *   // handle base64
+ * }
+ */
+async function textToAudio(prompt, options = {}) {
+  const model = options.model || 'stable-audio-3';
+
+  if (model !== 'stable-audio-3') {
+    throw new Error(
+      `textToAudio() expects model 'stable-audio-3'. Got: ${model}`
+    );
+  }
+
+  if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('textToAudio() requires a non-empty prompt string');
+  }
+
+  const formData = new FormData();
+  formData.append('prompt', prompt);
+  formData.append('model', model);
+
+  if (options.duration != null) formData.append('duration', String(options.duration));
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.steps != null) formData.append('steps', String(options.steps));
+  if (options.cfg_scale != null) formData.append('cfg_scale', String(options.cfg_scale));
+  if (options.output_format) formData.append('output_format', options.output_format);
+
+  const accept = options.accept || 'audio/*';
+  const id = await submitGeneration('text-to-audio', formData, accept);
+  const resultRes = await pollForResult(id, accept);
+
+  return processResult(resultRes, { ...options, filenamePrefix: 'stability-text-to-audio' });
+}
+
+/* ============================================================
+   WORKFLOW 2: AUDIO-TO-AUDIO
+   ============================================================ */
+
+/**
+ * Transforms an existing audio sample using a text prompt (audio-to-audio / style transfer).
+ *
+ * Uploads a reference audio file (or URL) and applies the prompt to generate a new
+ * composition that incorporates elements of the input while following the text description.
+ *
+ * **Additional Parameter**:
+ * - `strength`: Denoising strength (0.0 = identical to input, 1.0 = no influence from input).
+ *
+ * All other constraints and behavior are identical to `textToAudio`.
+ *
+ * @async
+ * @function audioToAudio
+ * @param {string} prompt - Descriptive text prompt (English, max 10k chars).
+ * @param {string|Buffer|Blob} audioInput - Reference audio:
+ *        - Local file path (string)
+ *        - Remote HTTP/HTTPS URL (string) – auto-downloaded with proper MIME
+ *        - Buffer (raw bytes)
+ *        - Blob (with optional name/type)
+ * @param {Object} [options={}] - Generation options (see textToAudio for common params).
+ * @param {number} [options.strength=1] - Denoising strength (0–1).
+ * @param {string} [options.filenamePrefix='stability-audio-to-audio']
+ * @returns {Promise<Object>} Same structure as textToAudio result.
+ * @throws {Error} Same as textToAudio plus audio input validation errors.
+ *
+ * @example
+ * const result = await audioToAudio(
+ *   'transform into orchestral version with strings and choir',
+ *   './reference-track.mp3',
+ *   { strength: 0.75, duration: 180 }
+ * );
+ */
+async function audioToAudio(prompt, audioInput, options = {}) {
+  const model = options.model || 'stable-audio-3';
+
+  if (model !== 'stable-audio-3') {
+    throw new Error(
+      `audioToAudio() expects model 'stable-audio-3'. Got: ${model}`
+    );
+  }
+
+  if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('audioToAudio() requires a non-empty prompt string');
+  }
+
+  const formData = new FormData();
+  formData.append('prompt', prompt);
+  formData.append('model', model);
+
+  if (options.duration != null) formData.append('duration', String(options.duration));
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.steps != null) formData.append('steps', String(options.steps));
+  if (options.cfg_scale != null) formData.append('cfg_scale', String(options.cfg_scale));
+  if (options.output_format) formData.append('output_format', options.output_format);
+  if (options.strength != null) formData.append('strength', String(options.strength));
+
+  // Handle audio input (URL, file path, Buffer, or Blob)
+  await appendAudioToFormData(formData, audioInput);
+
+  const accept = options.accept || 'audio/*';
+  const id = await submitGeneration('audio-to-audio', formData, accept);
+  const resultRes = await pollForResult(id, accept);
+
+  return processResult(resultRes, { ...options, filenamePrefix: 'stability-audio-to-audio' });
+}
+
+/* ============================================================
+   WORKFLOW 3: INPAINT
+   ============================================================ */
+
+/**
+ * Performs audio inpainting: replaces a specified time segment of an audio file
+ * with new content generated from a text prompt.
+ *
+ * Uses `mask_start` and `mask_end` to define the region to inpaint (in seconds).
+ * The model fills the masked section while preserving the rest of the audio.
+ *
+ * Default mask: 30s → 380s (inpaint most of a long track).
+ *
+ * @async
+ * @function inpaint
+ * @param {string} prompt - Text prompt describing the desired replacement content.
+ * @param {string|Buffer|Blob} audioInput - Reference audio (same as audioToAudio).
+ * @param {Object} [options={}] - Generation options.
+ * @param {number} [options.mask_start=30] - Start time (seconds) of the inpaint mask (0–380).
+ * @param {number} [options.mask_end=380] - End time (seconds) of the inpaint mask (0–380).
+ * @param {string} [options.filenamePrefix='stability-inpaint']
+ * @returns {Promise<Object>} Same result structure as other generation methods.
+ * @throws {Error} Validation errors for mask ranges, audio input, etc.
+ *
+ * @example
+ * // Inpaint the middle section
+ * const result = await inpaint(
+ *   'add a soaring guitar solo in this section',
+ *   'full-track.mp3',
+ *   { mask_start: 60, mask_end: 120, duration: 180 }
+ * );
+ */
+async function inpaint(prompt, audioInput, options = {}) {
+  const model = options.model || 'stable-audio-3';
+
+  if (model !== 'stable-audio-3') {
+    throw new Error(
+      `inpaint() expects model 'stable-audio-3'. Got: ${model}`
+    );
+  }
+
+  if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') {
+    throw new Error('inpaint() requires a non-empty prompt string');
+  }
+
+  const formData = new FormData();
+  formData.append('prompt', prompt);
+  formData.append('model', model);
+
+  if (options.duration != null) formData.append('duration', String(options.duration));
+  if (options.seed != null) formData.append('seed', String(options.seed));
+  if (options.steps != null) formData.append('steps', String(options.steps));
+  if (options.cfg_scale != null) formData.append('cfg_scale', String(options.cfg_scale));
+  if (options.output_format) formData.append('output_format', options.output_format);
+
+  // Inpaint specific
+  formData.append('mask_start', String(options.mask_start ?? 30));
+  formData.append('mask_end', String(options.mask_end ?? 380));
+
+  // Handle audio input
+  await appendAudioToFormData(formData, audioInput);
+
+  const accept = options.accept || 'audio/*';
+  const id = await submitGeneration('inpaint', formData, accept);
+  const resultRes = await pollForResult(id, accept);
+
+  return processResult(resultRes, { ...options, filenamePrefix: 'stability-inpaint' });
+}
+
+/* ============================================================
+   WORKFLOW 4: FETCH RESULT (manual polling)
+   ============================================================ */
+
+/**
+ * Manually fetches or checks the status of a generation using its ID.
+ * Useful for custom polling logic or resuming after a previous submission.
+ *
+ * @async
+ * @function fetchResult
+ * @param {string} id - Generation ID (from a previous 202 response).
+ * @param {string} [acceptHeader='audio/*'] - `'audio/*'` or `'application/json'`.
+ * @returns {Promise<Object>} Either:
+ *          - Completed result (same as processResult)
+ *          - `{ status: 'in-progress', id, raw }` if still 202
+ * @throws {Error} If ID missing, 404 (expired), or other API error.
+ *
+ * @example
+ * // Manual polling example
+ * const id = await submit...; // or from previous call
+ * let result;
+ * while (true) {
+ *   result = await fetchResult(id);
+ *   if (result.status !== 'in-progress') break;
+ *   await new Promise(r => setTimeout(r, 5000));
+ * }
+ */
+async function fetchResult(id, acceptHeader = 'audio/*') {
+  if (!id) {
+    throw new Error('fetchResult() requires a generation id');
+  }
+
+  const headers = getHeaders(acceptHeader);
+
+  const url = `${BASE_URL}/v2beta/audio/results/${id}`;
+  const res = await doRequest(url, 'GET', headers);
+
+  if (res.status === 200) {
+    return processResult(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(`fetchResult error ${res.status}: ${JSON.stringify(res.response)}`);
+}
+
+export {
+  getHeaders,
+  saveAudioToLocal,
+  textToAudio,
+  audioToAudio,
+  inpaint,
+  fetchResult
+};