@molecule/api-ai-image-generation-stability

Stability AI image generation provider for molecule.dev.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

// npm install @molecule/api-ai-image-generation-stability --workspace=api
import { setProvider, requireProvider } from '@molecule/api-ai-image-generation'
import { provider } from '@molecule/api-ai-image-generation-stability'

setProvider(provider) // reads STABILITY_API_KEY from the environment

const { images } = await requireProvider().generate({
  prompt: 'A watercolor fox reading a book',
  aspectRatio: '16:9', // or width/height — see @molecule/api-ai-image-generation
})
// images[0] may carry url, base64, or data — persist what the app needs to keep.

Type

provider

Installation

npm install @molecule/api-ai-image-generation-stability @molecule/api-ai-image-generation @molecule/api-secrets

API

Interfaces

StabilityConfig

Configuration for the Stability AI image generation provider.

interface StabilityConfig {
  /** Stability AI API key. Defaults to STABILITY_API_KEY env var. */
  apiKey?: string
  /** Default generation model. Defaults to 'sd3.5-large'. */
  defaultModel?: string
  /** Base URL for the Stability AI API. Defaults to 'https://api.stability.ai'. */
  baseUrl?: string
  /** Maximum number of retry attempts for transient failures. Defaults to 3. */
  maxRetries?: number
}

Classes

StabilityAIProvider

Stability AI image generation provider.

Supports Stable Diffusion 3 (sd3.5-large, sd3.5-medium, sd3-large, etc.), Stable Image Core, and Stable Image Ultra models via the Stability AI REST API.

class StabilityAIProvider implements AIImageGenerationProvider {
  /** @inheritdoc */
  readonly name = 'stability'

  private readonly apiKey: string
  private readonly defaultModel: string
  private readonly baseUrl: string
  private readonly maxRetries: number

  /**
   * Create a new Stability AI provider.
   *
   * @param config - Provider configuration. API key defaults to STABILITY_API_KEY env var.
   */
  constructor(config: StabilityConfig = {}) {
    const apiKey = config.apiKey ?? process.env['STABILITY_API_KEY']
    if (!apiKey) {
      throw new Error(
        'Stability AI API key is required. Set STABILITY_API_KEY or pass apiKey in config.',
      )
    }
    this.apiKey = apiKey
    this.defaultModel = config.defaultModel ?? DEFAULT_MODEL
    this.baseUrl = config.baseUrl ?? process.env.STABILITY_BASE_URL ?? DEFAULT_BASE_URL
    this.maxRetries = config.maxRetries ?? 3
  }

  /**
   * Generate images from a text prompt using the Stability AI API.
   *
   * @param params - Generation parameters.
   * @returns Generated images with metadata.
   */
  async generate(params: GenerateImageParams): Promise<ImageGenerationResult> {
    const model = params.model ?? this.defaultModel
    const endpoint = this.getGenerateEndpoint(model)

    const outputFormat = params.outputFormat ?? 'png'
    const images: GeneratedImage[] = []
    const count = params.count ?? 1

    for (let i = 0; i < count; i++) {
      const form = new FormData()
      form.append('prompt', params.prompt)

      if (params.negativePrompt) {
        form.append('negative_prompt', params.negativePrompt)
      }

      if (SD3_MODELS.has(model)) {
        form.append('model', model)
      }

      this.appendDimensionParams(form, params, model)

      if (params.seed !== undefined) {
        form.append('seed', String(params.seed + i))
      }

      if (params.guidanceScale !== undefined) {
        form.append('cfg_scale', String(params.guidanceScale))
      }

      if (params.steps !== undefined && SD3_MODELS.has(model)) {
        form.append('steps', String(params.steps))
      }

      if (params.stylePreset && !SD3_MODELS.has(model)) {
        form.append('style_preset', params.stylePreset)
      }

      form.append('output_format', outputFormat)

      const response = await this.sendRequest(endpoint, form)
      images.push(this.parseImageResponse(response, outputFormat))
    }

    return { images, model }
  }

  /**
   * Transform an existing image guided by a text prompt.
   *
   * @param params - Image-to-image parameters.
   * @returns Transformed images with metadata.
   */
  async imageToImage(params: ImageToImageParams): Promise<ImageGenerationResult> {
    const model = params.model ?? this.defaultModel
    const endpoint = `${this.baseUrl}/v2beta/stable-image/generate/sd3`

    const imageBuffer =
      typeof params.image === 'string' ? Buffer.from(params.image, 'base64') : params.image
    const outputFormat = params.outputFormat ?? 'png'
    const images: GeneratedImage[] = []
    const count = params.count ?? 1

    for (let i = 0; i < count; i++) {
      const form = new FormData()
      form.append('prompt', params.prompt)
      form.append('mode', 'image-to-image')
      form.append('image', new Blob([new Uint8Array(imageBuffer)]), 'image.png')

      if (SD3_MODELS.has(model)) {
        form.append('model', model)
      }

      if (params.strength !== undefined) {
        form.append('strength', String(params.strength))
      }

      if (params.negativePrompt) {
        form.append('negative_prompt', params.negativePrompt)
      }

      if (params.seed !== undefined) {
        form.append('seed', String(params.seed + i))
      }

      form.append('output_format', outputFormat)

      const response = await this.sendRequest(endpoint, form)
      images.push(this.parseImageResponse(response, outputFormat))
    }

    return { images, model }
  }

  /**
   * Upscale an image to a higher resolution using Stability AI's conservative upscaler.
   *
   * @param params - Upscale parameters.
   * @returns Upscaled image with metadata.
   */
  async upscale(params: UpscaleImageParams): Promise<ImageGenerationResult> {
    const endpoint = `${this.baseUrl}/v2beta/stable-image/upscale/conservative`

    const form = new FormData()

    const imageBuffer =
      typeof params.image === 'string' ? Buffer.from(params.image, 'base64') : params.image
    form.append('image', new Blob([new Uint8Array(imageBuffer)]), 'image.png')

    if (params.prompt) {
      form.append('prompt', params.prompt)
    }

    if (params.width) {
      form.append('width', String(params.width))
    }
    if (params.height) {
      form.append('height', String(params.height))
    }

    const outputFormat = params.outputFormat ?? 'png'
    form.append('output_format', outputFormat)

    const response = await this.sendRequest(endpoint, form)
    const image = this.parseImageResponse(response, outputFormat)

    return { images: [image], model: 'upscale-conservative' }
  }

  /**
   * Determine the generation endpoint URL for a given model.
   *
   * @param model - The model identifier.
   * @returns The full endpoint URL.
   */
  private getGenerateEndpoint(model: string): string {
    if (ULTRA_MODELS.has(model)) {
      return `${this.baseUrl}/v2beta/stable-image/generate/ultra`
    }
    if (CORE_MODELS.has(model)) {
      return `${this.baseUrl}/v2beta/stable-image/generate/core`
    }
    return `${this.baseUrl}/v2beta/stable-image/generate/sd3`
  }

  /**
   * Append width/height or aspect_ratio to the form data depending on the model.
   *
   * @param form - The FormData to append to.
   * @param params - The generation params.
   * @param model - The model being used.
   */
  private appendDimensionParams(form: FormData, params: GenerateImageParams, model: string): void {
    if (params.aspectRatio) {
      form.append('aspect_ratio', params.aspectRatio)
    } else if (params.width || params.height) {
      if (CORE_MODELS.has(model) || ULTRA_MODELS.has(model)) {
        const ratio = this.dimensionsToAspectRatio(params.width ?? 1024, params.height ?? 1024)
        form.append('aspect_ratio', ratio)
      } else {
        if (params.width) form.append('width', String(params.width))
        if (params.height) form.append('height', String(params.height))
      }
    }
  }

  /**
   * Convert pixel dimensions to the closest supported aspect ratio string.
   *
   * @param width - Image width in pixels.
   * @param height - Image height in pixels.
   * @returns An aspect ratio string (e.g. '16:9').
   */
  private dimensionsToAspectRatio(width: number, height: number): string {
    const ratio = width / height
    const supported: [string, number][] = [
      ['1:1', 1],
      ['16:9', 16 / 9],
      ['9:16', 9 / 16],
      ['21:9', 21 / 9],
      ['9:21', 9 / 21],
      ['2:3', 2 / 3],
      ['3:2', 3 / 2],
      ['4:5', 4 / 5],
      ['5:4', 5 / 4],
    ]
    let closest = '1:1'
    let closestDiff = Infinity
    for (const [name, value] of supported) {
      const diff = Math.abs(ratio - value)
      if (diff < closestDiff) {
        closestDiff = diff
        closest = name
      }
    }
    return closest
  }

  /**
   * Parse the raw API response into a GeneratedImage.
   *
   * @param response - The API response body as a Buffer.
   * @param outputFormat - The requested output format.
   * @returns A parsed GeneratedImage.
   */
  private parseImageResponse(response: StabilityResponse, outputFormat: string): GeneratedImage {
    const mimeType = `image/${outputFormat === 'jpeg' ? 'jpeg' : outputFormat}`

    if (response.image) {
      const data = Buffer.from(response.image, 'base64')
      return { data, mimeType, base64: response.image, seed: response.seed }
    }

    if (response.data) {
      return { data: response.data, mimeType, seed: response.seed }
    }

    throw new Error('Stability AI returned an unexpected response format.')
  }

  /**
// … truncated — the full declaration is in node_modules/@molecule/api-ai-image-generation-stability/dist/provider.d.ts

Functions

createProvider(config)

Create a Stability AI image generation provider.

function createProvider(config?: StabilityConfig): StabilityAIProvider

• config — Provider configuration. API key defaults to STABILITY_API_KEY env var.

Returns: A configured StabilityAIProvider instance.

Constants

provider

The provider implementation.

const provider: AIImageGenerationProvider

aiImageGenerationStabilitySecretDefinitions

Secret definitions required by the Stability AI image generation bond.

const aiImageGenerationStabilitySecretDefinitions: SecretDefinition[]

Core Interface

Implements @molecule/api-ai-image-generation interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/api-ai-image-generation'
import { provider } from '@molecule/api-ai-image-generation-stability'

export function setupAiImageGenerationStability(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-ai-image-generation >=1.0.1
• @molecule/api-secrets ^1.0.1

Environment Variables

• STABILITY_API_KEY (required) — Stability AI API key
  • Setup: Create an API key under Account → API keys on the Stability platform.
  • Get it here: https://platform.stability.ai/account/keys
  • Example: sk-...

Runtime Dependencies

• @molecule/api-ai-image-generation
• @molecule/api-secrets

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

• Entering a prompt in the UI and submitting produces a REAL rendered image in the live preview — not a broken img (image icon / alt text), a grey placeholder, or an error toast. Confirm the img element actually decoded (its naturalWidth/naturalHeight are non-zero) and the picture visibly reflects the prompt (a "red bicycle" prompt shows a red bicycle).
• Two different prompts produce two visibly different images — a fixed stub, or a cached first result that never changes, is a broken integration.
• The image is STORED AND SERVED FROM THE APP'S OWN ORIGIN: the rendered img src (and any saved record) points at the app's uploads/storage, not the provider's temporary URL. Provider url results expire — reload the page (or revisit the record later) and the image must still load. Download the provider result server-side and persist it (uploads bond); never hotlink the provider URL — it 404s later and can leak the API request context. (base64/data results must likewise be saved, not held only in the response.)
• Any exposed generation options take effect: changing size/dimensions yields a differently-sized image; requesting a count (n) of N renders N images. If the UI exposes no such options, this box is n/a — say so.
• A rejected or policy-violating prompt, or a provider/rate-limit error, surfaces a clear message in the UI — not a crash, a blank screen, or a silently-broken img. The user can recover and try another prompt.
• Generation is server-side and authorized: the provider API key never reaches the browser (check the network tab / built client bundle — no key, no direct provider call from the page), the generate endpoint requires auth, and a caller cannot run unbounded costly generations through an open or unrate-limited route. Every image is billed.