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

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

@@ -0,0 +1,271 @@
+# Stable Image API Specifications
+
+> Extracted from `lib/API/stability.ai/openapi.json` for Stability AI's Stable Image services (v2beta).
+> This document serves as the source specification for generating the HTTP wrapper `image.js` (modeled after `lib/API/stability.ai/audio.js` and `lib/API/minimax/music.js`).
+
+## Overview
+
+Stability AI provides a comprehensive suite of image generation, editing, upscaling, and control tools powered by models like Stable Diffusion 3.5, Stable Image Ultra/Core, and specialized edit/control services.
+
+**Key Models & Services**:
+- **Generate**:
+  - `stable-image-ultra`: Photorealistic, high-quality (8 credits).
+  - `stable-image-core`: Fast & affordable (3 credits).
+  - `sd3` (Stable Diffusion 3.5): Large, Large Turbo, Medium, Flash variants.
+- **Upscale**:
+  - `conservative`: Preserves details, up to 4MP (40 credits).
+  - `creative`: Heavy reimagining for degraded images (60 credits, async).
+  - `fast`: 4x resolution boost, lightweight (~1s, 2 credits).
+- **Edit**:
+  - Erase, Inpaint, Outpaint, Search & Replace, Search & Recolor, Remove Background, Replace Background & Relight.
+- **Control**:
+  - Sketch, Structure, Style, Style Transfer.
+- **Results**: Async result fetching for generations that return IDs.
+
+- **Base URL**: `https://api.stability.ai`
+- **Authentication**: `Authorization: Bearer sk-...` header.
+- **Common Patterns**:
+  - Most endpoints support `multipart/form-data`.
+  - `accept: image/*` for binary image response or `application/json` for base64.
+  - Many return 200 with image bytes or 202 with `{ "id": "..." }` for async (poll `/v2beta/results/{id}` or specific result endpoints).
+  - Credits vary (see individual endpoints).
+  - Output formats: `jpeg`, `png` (default), `webp`.
+  - Max image size: Typically 4,096–9,437,184 pixels total; aspect ratios constrained.
+  - Content moderation: 403 responses for flagged content.
+  - Rate limit: 150 requests / 10 seconds.
+
+**Async Workflow** (for creative upscale, replace-background-and-relight, some generations):
+1. POST → 202 with `id`.
+2. Poll `GET /v2beta/results/{id}` (or specific result path) with `accept: image/*`.
+3. 200 = ready (binary or JSON); 202 = in-progress.
+
+**Notes**:
+- English prompts preferred; copyrighted/public figure content may be rejected.
+- See official docs: [Stability Platform API](https://platform.stability.ai/docs).
+
+## Endpoints
+
+### Generate
+
+#### 1. Stable Image Ultra
+**POST** `/v2beta/stable-image/generate/ultra`
+
+Highest quality photorealistic generation.
+
+**Request**:
+- `multipart/form-data`
+- Required: `prompt`
+- Optional: `negative_prompt`, `aspect_ratio` (default 1:1), `seed`, `output_format`, `image` + `strength` (for img2img), `style_preset`
+
+**Responses**:
+- 200: Image bytes or JSON `{ "image": "base64...", "seed", "finish_reason" }`
+- Errors: 400/422/403/429/500
+
+#### 2. Stable Image Core
+**POST** `/v2beta/stable-image/generate/core`
+
+Fast, affordable generation.
+
+Similar params to Ultra (no `image`/`strength` by default).
+
+#### 3. Stable Diffusion 3.5
+**POST** `/v2beta/stable-image/generate/sd3`
+
+Supports `sd3.5-large`, `sd3.5-large-turbo`, `sd3.5-medium`, `sd3.5-flash`.
+
+- `mode`: `text-to-image` or `image-to-image`
+- For img2img: `image` + `strength` required.
+- `cfg_scale`, `negative_prompt`, `style_preset`, etc.
+
+### Upscale
+
+#### 1. Conservative Upscale
+**POST** `/v2beta/stable-image/upscale/conservative`
+
+Preserves original while upscaling to 4MP.
+
+Required: `image`, `prompt`
+Optional: `negative_prompt`, `seed`, `output_format`, `creativity`
+
+#### 2. Creative Upscale (async)
+**POST** `/v2beta/stable-image/upscale/creative`
+
+For degraded images; returns `id` for polling `/v2beta/stable-image/upscale/creative/result/{id}`.
+
+#### 3. Fast Upscale
+**POST** `/v2beta/stable-image/upscale/fast`
+
+Quick 4x enhancement.
+
+Required: `image`
+Optional: `output_format`
+
+### Edit
+
+#### Erase
+**POST** `/v2beta/stable-image/edit/erase`
+
+Remove objects using mask or alpha channel.
+
+Required: `image`
+Optional: `mask`, `grow_mask`, `seed`, `output_format`
+
+#### Inpaint
+**POST** `/v2beta/stable-image/edit/inpaint`
+
+Fill/replace areas with prompt or search mode.
+
+Supports `mode: search` (with `search_prompt`) or `mask`.
+
+#### Outpaint
+**POST** `/v2beta/stable-image/edit/outpaint`
+
+Expand image in directions (`left`, `right`, `up`, `down` pixels).
+
+Required: `image` + at least one direction.
+Optional: `prompt`, `creativity`, `style_preset`
+
+#### Search and Replace
+**POST** `/v2beta/stable-image/edit/search-and-replace`
+
+Auto-segment and replace object described by `search_prompt`.
+
+Required: `image`, `prompt`, `search_prompt`
+
+#### Search and Recolor
+**POST** `/v2beta/stable-image/edit/search-and-recolor`
+
+Change color of object via `select_prompt`.
+
+#### Remove Background
+**POST** `/v2beta/stable-image/edit/remove-background`
+
+Segments and removes background.
+
+Required: `image`
+Optional: `output_format` (`png`/`webp`)
+
+#### Replace Background and Relight (async)
+**POST** `/v2beta/stable-image/edit/replace-background-and-relight`
+
+Swap background + adjust lighting.
+
+Required: `subject_image`
+Optional: `background_prompt` or `background_reference`, lighting params, etc.
+Returns `id` for polling.
+
+### Control
+
+#### Sketch
+**POST** `/v2beta/stable-image/control/sketch`
+
+Refine sketches or control via edges.
+
+Required: `image`, `prompt`
+Optional: `control_strength` (0-1), `negative_prompt`, `style_preset`
+
+#### Structure
+**POST** `/v2beta/stable-image/control/structure`
+
+Maintain structure of input image.
+
+Similar to Sketch.
+
+#### Style
+**POST** `/v2beta/stable-image/control/style`
+
+Apply style from control image.
+
+#### Style Transfer
+**POST** `/v2beta/stable-image/control/style-transfer`
+
+Transform content while preserving composition using style image.
+
+Required: `init_image`, `style_image`
+
+### Results
+
+#### Fetch Generation Result
+**GET** `/v2beta/results/{id}`
+
+Poll for image results (used by async endpoints).
+
+Headers: `accept: image/*` or `application/json`
+
+Responses:
+- 200: Image bytes + headers (`finish-reason`, `seed`, `content-type`)
+- 202: `{ "id": "...", "status": "in-progress" }`
+- 404: Expired/not found
+
+## Common Error Responses
+
+- **400**: Invalid parameters (e.g., missing required fields).
+- **403**: Content moderation flag.
+- **413**: Payload too large (>10MiB).
+- **422**: Rejected (copyright, public figure, language).
+- **429**: Rate limit.
+- **500**: Internal error.
+
+Error JSON example:
+```json
+{
+  "id": "...",
+  "name": "bad_request",
+  "errors": ["prompt: is required"]
+}
+```
+
+## OpenAPI Excerpts (Key Patterns)
+
+Most image endpoints follow this structure (multipart/form-data, accept header for binary/JSON, 200 with image or 202 with id).
+
+Example for Generate Ultra (simplified):
+```json
+{
+  "post": {
+    "tags": ["Generate"],
+    "summary": "Stable Image Ultra",
+    "requestBody": {
+      "content": {
+        "multipart/form-data": {
+          "schema": {
+            "properties": {
+              "prompt": { "type": "string", "maxLength": 10000 },
+              "aspect_ratio": { "enum": ["1:1", "16:9", ...] },
+              "image": { "type": "string", "format": "binary" },
+              "strength": { "type": "number", "minimum": 0, "maximum": 1 }
+            },
+            "required": ["prompt"]
+          }
+        }
+      }
+    },
+    "responses": {
+      "200": { "description": "Generation successful." },
+      "202": { "description": "Async started." }
+    }
+  }
+}
+```
+
+Similar patterns for Edit/Control/Upscale with file uploads (`image`, `mask`, `subject_image`, etc.) and specific params like `control_strength`, `grow_mask`, `search_prompt`.
+
+## Code Generation Notes for `image.js`
+
+- Implement methods: `generateUltra(params)`, `generateCore(params)`, `generateSD3(params)`, `upscaleConservative(params, imageFile)`, `upscaleCreative(...)`, `editInpaint(...)`, `controlSketch(...)`, `fetchResult(id)`, etc.
+- Use `FormData` for all uploads.
+- Handle async polling loop (similar to audio.js `fetchResult`).
+- Support binary download (`responseType: 'arraybuffer'`) and base64 JSON.
+- Validation: image dimensions, aspect ratios, credit costs, duration equivalents (N/A for images).
+- Error handling: Specific messages for moderation, size limits, etc.
+- Defaults: `output_format: "png"`, random seed=0.
+- Model-specific handling (e.g., SD3 modes).
+- Keep tiny & efficient like audio.js.
+
+## References
+- Full spec: `lib/API/stability.ai/openapi.json`
+- Related: `audio-3.md` for audio parity.
+- Official docs & Colab examples in OpenAPI `x-codeSamples`.
+
+---
+*Generated: May 22, 2026. Focused on v2beta Stable Image endpoints for wrapper implementation.*

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

@@ -0,0 +1,11 @@
+import * as music from './audio.js';
+import musicToolset from './MusicToolset.js'
+import * as image from './image.js';
+import imageToolset from './ImageToolset.js'
+
+export default {
+	music,
+	musicToolset,
+	image,
+	imageToolset
+}