Stability AI Image Generation Service

A TypeScript/Node.js wrapper for the Stability AI API that provides easy access to Stable Diffusion 3.5, image upscaling, editing, and control models. Generate stunning AI images, upscale, edit, and control them with professional quality through a simple command-line interface.

This service follows the data-collection architecture pattern with organized data storage, automatic polling for async operations, retry logic, comprehensive logging, and CLI orchestration.

Quick Start

CLI Usage

# Install globally
npm install -g stability-ai-api

# Set your API key
export STABILITY_API_KEY="your-api-key"

# Generate an image
sai generate ultra --prompt "a serene mountain landscape"

# Upscale an image
sai upscale fast --image ./photo.jpg

Demo

Programmatic Usage

import { StabilityAPI } from 'stability-ai-api';

const api = new StabilityAPI();

// Generate an image with Stable Image Ultra
const result = await api.generateUltra({
  prompt: 'a serene mountain landscape',
  aspect_ratio: '16:9'
});

console.log('Image saved to:', result.image_path);

Full TypeScript support with exported types for all parameters and responses.

Overview

The Stability AI API provides access to state-of-the-art image generation and upscaling models. This Node.js service implements:

17 Endpoints - 3 Generate + 3 Upscale + 7 Edit + 4 Control operations
Production Security - API key redaction, error sanitization, HTTPS enforcement, comprehensive SSRF protection (including IPv4-mapped IPv6 bypass prevention)
DoS Prevention - Request timeouts (30s API calls), file size limits (50MB), redirect limits
Parameter Validation - Pre-flight validation catches invalid parameters before API calls
API Key Authentication - Multiple configuration methods with secure handling
Auto-polling with Spinner - Automatic result polling for async operations with progress indicator
Batch Processing - Generate multiple images sequentially from multiple prompts
Retry Logic - Transient error handling with smart retry
Image Input Support - Convert local files to Buffers with validation
Organized Storage - Structured directories with timestamped files and metadata
CLI Orchestration - Command-line tool with subcommands for generation and upscaling
Full TypeScript Support - Complete type definitions for all API methods, parameters, and responses
Comprehensive Testing - 283 tests with 76% coverage (api.ts: 64.56%, config.ts: 92.22%, utils.ts: 73.38%)

Endpoint Summary

Operation	CLI Command	API Method	Sync/Async	Notes
Generate
Stable Image Ultra	`sai generate ultra`	`generateUltra(options)`	Sync	Photorealistic 1MP, optional image-to-image
Stable Image Core	`sai generate core`	`generateCore(options)`	Sync	Fast SDXL successor, style presets
Stable Diffusion 3.5	`sai generate sd3`	`generateSD3(options)`	Sync	Three variants: large, medium, turbo
Upscale
Fast Upscale	`sai upscale fast`	`upscaleFast(image, options)`	Sync	4x in ~1 second (input ≤1MP)
Conservative Upscale	`sai upscale conservative`	`upscaleConservative(image, options)`	Sync	20-40x to 4MP, minimal alteration
Creative Upscale	`sai upscale creative`	`upscaleCreative(image, options)`	Async	20-40x with reimagining (input ≤1MP)
Edit
Erase	`sai edit erase`	`erase(image, options)`	Sync	Remove objects using mask
Inpaint	`sai edit inpaint`	`inpaint(image, prompt, options)`	Sync	Fill masked area with prompt
Outpaint	`sai edit outpaint`	`outpaint(image, options)`	Sync	Extend image boundaries
Search & Replace	`sai edit search-replace`	`searchAndReplace(image, prompt, search, options)`	Sync	Replace objects by description
Search & Recolor	`sai edit search-recolor`	`searchAndRecolor(image, prompt, select, options)`	Sync	Recolor selected objects
Remove Background	`sai edit remove-bg`	`removeBackground(image, options)`	Sync	Extract subject from background
Replace Background	`sai edit replace-bg`	`replaceBackgroundAndRelight(image, options)`	Async	New background with relighting (polling)
Control
Control: Sketch	`sai control sketch`	`controlSketch(image, prompt, options)`	Sync	Convert sketches to refined images
Control: Structure	`sai control structure`	`controlStructure(image, prompt, options)`	Sync	Preserve structure while transforming
Control: Style	`sai control style`	`controlStyle(image, prompt, options)`	Sync	Match reference image style
Control: Style Transfer	`sai control style-transfer`	`controlStyleTransfer(initImage, styleImage, options)`	Sync	Transfer style between images

Note: All API methods use snake_case parameters to match the Stability AI HTTP API (e.g., aspect_ratio, output_format, style_preset).

Models

Stable Image Ultra

Photorealistic 1MP image generation with image-to-image support.

Best for: Photorealistic renders, product photos, portraits

Parameters:

prompt - Text description of desired image (required)
aspect_ratio - Image proportions (1:1, 16:9, 21:9, 2:3, 3:2, 4:5, 5:4, 9:16, 9:21)
seed - Random seed (0 to 4,294,967,294)
image - Optional input image for image-to-image generation
strength - Image influence strength (0.0-1.0, for image-to-image)

Stable Image Core

Fast and affordable SDXL successor with style presets.

Best for: Fast generation, stylized images, production workflows

Parameters:

prompt - Text description of desired image (required)
aspect_ratio - Image proportions (1:1, 16:9, 21:9, 2:3, 3:2, 4:5, 5:4, 9:16, 9:21)
seed - Random seed (0 to 4,294,967,294)
style_preset - Style preset (photographic, anime, cinematic, digital-art, fantasy-art, etc.)

Stable Diffusion 3.5

Latest SD3.5 models with three variants.

Models: sd3.5-large, sd3.5-medium, sd3.5-large-turbo Best for: General-purpose generation, fast turbo mode

Parameters:

prompt - Text description of desired image (required)
model - Model variant (sd3.5-large, sd3.5-medium, sd3.5-large-turbo)
aspect_ratio - Image proportions (1:1, 16:9, 21:9, 2:3, 3:2, 4:5, 5:4, 9:16, 9:21)
seed - Random seed (0 to 4,294,967,294)

Upscale Fast

4x upscaling in approximately 1 second (synchronous).

Best for: Quick upscales, batch processing

Parameters:

image - Input image to upscale (required)
output_format - Output format (jpeg, png, webp)

Upscale Conservative

20-40x upscaling to 4MP with minimal alteration (synchronous).

Best for: Preserving original details, minimal changes

Parameters:

image - Input image to upscale (required)
prompt - Optional guidance for upscaling
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)

Upscale Creative

20-40x upscaling with creative reimagining (asynchronous with polling).

Best for: Enhancing and reimagining images, artistic upscales

Parameters:

image - Input image to upscale (required)
prompt - Optional guidance for creative upscaling
creativity - Creative freedom level (0.1-0.5, higher = more creative)
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)

Edit Operations

7 powerful image editing operations for professional image manipulation.

Erase

Remove unwanted objects from images using masks.

Best for: Removing blemishes, items, or unwanted elements

Parameters:

image - Input image (required)
mask - Mask image where white = erase (optional, uses alpha channel if omitted)
grow_mask - Pixels to expand mask (0-20, default: 5)
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)

Inpaint

Fill or replace masked areas with prompt-guided content.

Best for: Replacing objects, filling gaps, adding elements

Parameters:

image - Input image (required)
prompt - What to generate in masked area (required)
mask - Mask image where white = inpaint (optional)
negative_prompt - What NOT to generate
grow_mask - Pixels to expand mask (0-100, default: 5)
style_preset - Style preset (photographic, anime, cinematic, etc.)
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)

Outpaint

Extend image boundaries in any direction.

Best for: Expanding compositions, adding context

Parameters:

image - Input image (required)
left, right, up, down - Pixels to extend (0-2000 each)
creativity - How creative the outpainting (0-1, default: 0.5)
prompt - What to generate in extended areas
style_preset - Style preset
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)

Search and Replace

Automatically detect and replace objects using text prompts (no manual masking).

Best for: Object replacement without manual mask creation

Parameters:

image - Input image (required)
prompt - What to replace with (required)
search_prompt - What to find/replace (required)
negative_prompt - What NOT to generate
grow_mask - Pixels to expand auto-detected mask (0-20, default: 3)
style_preset - Style preset
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)

Search and Recolor

Automatically detect and recolor objects using text prompts (no manual masking).

Best for: Color changes without manual mask creation

Parameters:

image - Input image (required)
prompt - Desired color/appearance (required)
select_prompt - What to find/recolor (required)
negative_prompt - What NOT to generate
grow_mask - Pixels to expand auto-detected mask (0-20, default: 3)
style_preset - Style preset
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)

Remove Background

Automatically segment and remove background, returning transparent image.

Best for: Product photos, portraits, creating cutouts

Parameters:

image - Input image (required)
output_format - Output format (png or webp only - no jpeg due to transparency)

Note: Maximum 4,194,304 pixels (stricter than other operations)

Replace Background and Relight

Replace background with AI-generated imagery and adjust lighting (asynchronous).

Best for: Studio-quality background replacement, lighting adjustments

Parameters:

subject_image - Input image with subject to keep (required)
background_prompt - Description of desired background (required if no reference)
background_reference - Reference image for background style
foreground_prompt - Description of subject (prevents background bleeding)
negative_prompt - What NOT to generate
preserve_original_subject - Subject overlay strength (0-1, default: 0.6)
original_background_depth - Background depth matching (0-1, default: 0.5)
keep_original_background - Keep original background, change lighting only
light_source_direction - Light direction (left, right, above, below)
light_reference - Reference image for lighting
light_source_strength - Light intensity (0-1, requires direction or reference)
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)

Note: This is the only edit operation that runs asynchronously with polling.

Style Presets (for applicable operations)

Available presets: enhance, anime, photographic, digital-art, comic-book, fantasy-art, line-art, analog-film, neon-punk, isometric, low-poly, origami, modeling-compound, cinematic, 3d-model, pixel-art, tile-texture

Edit Credits

Erase: 5 credits
Inpaint: 5 credits
Outpaint: 4 credits
Search & Replace: 5 credits
Search & Recolor: 5 credits
Remove Background: 5 credits
Replace BG & Relight: 8 credits

Control Operations

4 control operations for guided image generation with structure, style, and sketch inputs.

Control: Sketch

Convert rough sketches into refined images with precise control over the generation process.

Best for: Creating detailed images from simple sketches or line art

Parameters:

image - Input sketch image (required)
prompt - What to generate from the sketch (required)
control_strength - Influence of sketch on generation (0-1, default: 0.7)
negative_prompt - What NOT to generate
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)
style_preset - Style preset (photographic, anime, cinematic, etc.)

Control: Structure

Generate images while preserving the structure and composition of an input image.

Best for: Transforming images while maintaining layout and composition

Parameters:

image - Input structure reference image (required)
prompt - What to generate (required)
control_strength - Influence of structure on generation (0-1, default: 0.7)
negative_prompt - What NOT to generate
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)
style_preset - Style preset

Control: Style

Generate content guided by the style of a reference image.

Best for: Creating images that match the artistic style of a reference

Parameters:

image - Style reference image (required)
prompt - What to generate with that style (required)
fidelity - How closely output resembles input style (0-1, default: 0.5)
negative_prompt - What NOT to generate
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)
aspect_ratio - Image proportions (1:1, 16:9, 21:9, 2:3, 3:2, 4:5, 5:4, 9:16, 9:21)

Control: Style Transfer

Transfer the artistic style from one image to another image.

Best for: Applying artistic styles to existing photos or images

Parameters:

init_image - Image to apply style to (required)
style_image - Style reference image (required)
prompt - Optional guidance for the transfer
negative_prompt - What NOT to generate
style_strength - Intensity of style transfer (0-1)
composition_fidelity - How much to preserve original composition (0-1)
change_strength - How much to modify the original (0.1-1)
seed - Random seed (0 to 4,294,967,294)
output_format - Output format (jpeg, png, webp)

Control Credits

Sketch: 5 credits
Structure: 5 credits
Style: 5 credits
Style Transfer: 8 credits

Authentication Setup

1. Get Your API Key

Visit https://platform.stability.ai/account/keys
Create an account or sign in (if not already signed in)
Generate your API key
Copy your API key

2. Configure Your API Key

You can provide your API key in multiple ways (listed in priority order):

Option 1: CLI Flag (Highest Priority)

sai generate ultra --api-key "your-api-key" --prompt "test"

Option 2: Environment Variable

export STABILITY_API_KEY="your-api-key"
sai generate ultra --prompt "test"

Option 3: Local .env File

echo "STABILITY_API_KEY=your-api-key" > .env
sai generate ultra --prompt "test"

Option 4: Global Configuration

mkdir -p ~/.stability
echo "STABILITY_API_KEY=your-api-key" > ~/.stability/.env
sai generate ultra --prompt "test"

Installation

Global Installation (Recommended)

# Install globally from npm
npm install -g stability-ai-api

# Verify installation
sai --version

Local Development

# Clone or navigate to the repository
cd stability-ai-api

# Install dependencies
npm install

# Run tests
npm test  # Run 283 tests

TypeScript Support

This package is written in TypeScript and includes full type definitions. All API methods, parameters, and responses are fully typed.

Exported Types

import {
  StabilityAPI,
  // Parameter types
  UltraParams,
  CoreParams,
  SD3Params,
  UpscaleFastParams,
  UpscaleConservativeParams,
  UpscaleCreativeParams,
  // Edit parameter types
  EditEraseParams,
  EditInpaintParams,
  EditOutpaintParams,
  EditSearchReplaceParams,
  EditSearchRecolorParams,
  EditRemoveBackgroundParams,
  EditReplaceBackgroundParams,
  // Control parameter types
  ControlSketchParams,
  ControlStructureParams,
  ControlStyleParams,
  ControlStyleTransferParams,
  // Response types
  ImageResult,
  TaskResult
} from 'stability-ai-api';

// Types are automatically inferred
const api = new StabilityAPI();
const result = await api.generateUltra({
  prompt: 'a cat',  // TypeScript will validate all parameters
  aspect_ratio: '16:9'
});

Type-Safe Parameters

All generation methods have strict parameter typing:

// TypeScript will catch invalid parameters at compile time
const result = await api.generateUltra({
  prompt: 'a landscape',
  aspect_ratio: '16:9',    // '1:1' | '16:9' | '21:9' | '2:3' | '3:2' | '4:5' | '5:4' | '9:16' | '9:21'
  seed: 42,                // optional number (0-4294967294)
  output_format: 'png'     // 'jpeg' | 'png' | 'webp'
});

// Edit operations are also fully typed
const edited = await api.searchAndReplace(
  './image.jpg',
  'golden retriever',      // prompt
  'cat',                   // search_prompt
  {
    negative_prompt: 'blurry',
    grow_mask: 5,
    output_format: 'png'
  }
);

Building from Source

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Output is in dist/
ls dist/
# api.js, api.d.ts, cli.js, cli.d.ts, config.js, config.d.ts, utils.js, utils.d.ts, types/

Programmatic Usage

You can use the Stability AI API directly in your Node.js applications.

Basic Setup

// If installed via npm
import { StabilityAPI } from 'stability-ai-api';

// If running from source
import { StabilityAPI } from './src/api.js';

// Initialize with API key (reads from env vars by default)
const api = new StabilityAPI();

// Or explicitly provide API key
const api = new StabilityAPI({ apiKey: 'your-api-key-here' });

Generation Methods

Stable Image Ultra - Text-to-Image

import { StabilityAPI } from 'stability-ai-api';

const api = new StabilityAPI();

const result = await api.generateUltra({
  prompt: 'a serene mountain landscape at sunset',
  aspect_ratio: '16:9',
  seed: 42,
  output_format: 'png'
});

// result.image is a Buffer containing the PNG data
console.log('Generated image, seed:', result.seed);
console.log('Finish reason:', result.finish_reason);

Stable Image Ultra - Image-to-Image

const result = await api.generateUltra({
  prompt: 'transform into oil painting style',
  image: './photo.jpg',  // Local file path
  strength: 0.6,         // 0.0 = identical to input, 1.0 = completely new
  aspect_ratio: '1:1',
  output_format: 'png'
});

Stable Image Core with Style Presets

const result = await api.generateCore({
  prompt: 'cyberpunk city at night',
  aspect_ratio: '21:9',
  style_preset: 'cinematic',  // photographic, anime, cinematic, etc.
  seed: 12345,
  output_format: 'png'
});

Stable Diffusion 3.5

const result = await api.generateSD3({
  prompt: 'fantasy castle on a floating island',
  model: 'sd3.5-large-turbo',  // sd3.5-large, sd3.5-medium, sd3.5-large-turbo
  aspect_ratio: '16:9',
  negative_prompt: 'blurry, low quality',
  seed: 999,
  output_format: 'webp'
});

Upscaling Methods

Fast Upscale (4x, ~1 second)

const result = await api.upscaleFast(
  './low_res.jpg',  // Image path
  'png'             // Output format (optional)
);

// Synchronous - returns immediately with upscaled image
console.log('Upscaled image size:', result.image.length);

Note: Input image must be ≤1MP (1,048,576 pixels). For larger images, use Conservative Upscale.

Conservative Upscale (20-40x to 4MP)

const result = await api.upscaleConservative('./photo.jpg', {
  prompt: 'enhance details and sharpness',
  negative_prompt: 'blurry, artifacts',
  seed: 42,
  output_format: 'png'
});

// Synchronous - minimal alteration to original

Creative Upscale (20-40x with reimagining)

const result = await api.upscaleCreative('./sketch.jpg', {
  prompt: 'photorealistic rendering with vibrant colors',
  creativity: 0.35,  // 0.1 = conservative, 0.5 = very creative
  seed: 777,
  output_format: 'png'
});

// Asynchronous - automatically polls for result
// The method waits until upscaling completes
console.log('Creative upscale finished:', result.finish_reason);

Note: Input image must be ≤1MP (1,048,576 pixels). For larger images, use Conservative Upscale.

Control Methods

Control: Sketch

const result = await api.controlSketch('./sketch.png', 'castle on a hill', {
  control_strength: 0.7,
  negative_prompt: 'blurry, low quality',
  seed: 42,
  output_format: 'png'
});

Control: Structure

const result = await api.controlStructure('./statue.jpg', 'garden shrub sculpture', {
  control_strength: 0.8,
  style_preset: 'photographic',
  output_format: 'png'
});

Control: Style

const result = await api.controlStyle('./art-reference.png', 'portrait of a chicken', {
  fidelity: 0.5,
  aspect_ratio: '1:1',
  output_format: 'png'
});

Control: Style Transfer

const result = await api.controlStyleTransfer('./photo.png', './artwork.jpg', {
  prompt: 'enhance the artistic style',
  style_strength: 0.7,
  composition_fidelity: 0.5,
  change_strength: 0.3,
  output_format: 'png'
});

Utility Methods

Check Account Credits

const balance = await api.getBalance();
console.log('Credits remaining:', balance.credits);

Get Result for Async Operations

// For Creative Upscale or if you want to poll manually
const taskId = 'abc123-task-id';

// Poll once
const status = await api.getResult(taskId);

// Or wait for completion with auto-polling
const result = await api.waitForResult(taskId, {
  timeout: 300,      // Max 5 minutes
  pollInterval: 2,   // Check every 2 seconds
  maxRetries: 3,     // Retry on transient errors
  showSpinner: true  // Show animated progress spinner
});

Complete Example: Batch Generation

import { StabilityAPI } from 'stability-ai-api';
import { writeToFile } from 'stability-ai-api/utils';
import path from 'path';

const api = new StabilityAPI();

const prompts = [
  'a red sports car on a mountain road',
  'a blue vintage car in the city',
  'a green electric car at a charging station'
];

for (const prompt of prompts) {
  console.log(`Generating: ${prompt}`);

  const result = await api.generateCore({
    prompt,
    aspect_ratio: '16:9',
    style_preset: 'photographic',
    output_format: 'png'
  });

  // Save to file
  const filename = `${Date.now()}_${prompt.slice(0, 30)}.png`;
  await writeToFile(result.image, path.join('./outputs', filename));

  console.log(`✓ Saved: ${filename}`);
  console.log(`  Seed: ${result.seed}`);
}

Complete Example: Image Processing Pipeline

import { StabilityAPI } from 'stability-ai-api';
import { writeToFile } from 'stability-ai-api/utils';

const api = new StabilityAPI();

// Step 1: Generate base image
console.log('Generating base image...');
const generated = await api.generateUltra({
  prompt: 'a beautiful landscape painting',
  aspect_ratio: '16:9'
});

await writeToFile(generated.image, './step1_generated.png');

// Step 2: Transform with image-to-image
console.log('Transforming style...');
const transformed = await api.generateUltra({
  prompt: 'same scene but in watercolor style',
  image: './step1_generated.png',
  strength: 0.7
});

await writeToFile(transformed.image, './step2_transformed.png');

// Step 3: Upscale to high resolution
console.log('Upscaling to high resolution...');
const upscaled = await api.upscaleCreative('./step2_transformed.png', {
  prompt: 'enhance details, vibrant colors, high quality',
  creativity: 0.3
});

await writeToFile(upscaled.image, './step3_final_4k.png');
console.log('✓ Pipeline complete!');

Complete Example: Edit Operations

import { StabilityAPI } from 'stability-ai-api';
import { writeToFile } from 'stability-ai-api/utils';

const api = new StabilityAPI();

// Erase an object using a mask
const erased = await api.erase('./photo.jpg', {
  mask: './mask.png',      // White = areas to erase
  grow_mask: 5,            // Expand mask by 5 pixels
  output_format: 'png'
});
await writeToFile(erased.image, './erased.png');

// Inpaint: fill masked area with new content
const inpainted = await api.inpaint('./scene.jpg', 'a golden retriever', {
  mask: './dog_mask.png',  // White = area to fill
  negative_prompt: 'blurry, distorted',
  output_format: 'png'
});
await writeToFile(inpainted.image, './inpainted.png');

// Outpaint: extend image boundaries
const outpainted = await api.outpaint('./landscape.jpg', {
  left: 200,               // Extend 200px left
  right: 200,              // Extend 200px right
  creativity: 0.5,         // Balance between original and generated
  prompt: 'continue the mountain scenery'
});
await writeToFile(outpainted.image, './outpainted.png');

// Search and Replace: swap objects by description
const replaced = await api.searchAndReplace('./pet.jpg', 'a tabby cat', 'dog', {
  output_format: 'png'
});
await writeToFile(replaced.image, './cat_instead.png');

// Remove Background: extract subject
const noBg = await api.removeBackground('./portrait.jpg', {
  output_format: 'png'     // PNG preserves transparency
});
await writeToFile(noBg.image, './subject_only.png');

Error Handling

import { StabilityAPI } from 'stability-ai-api';

const api = new StabilityAPI();

try {
  const result = await api.generateUltra({
    prompt: 'test image',
    aspect_ratio: '16:9'
  });

  console.log('Success!');
} catch (error) {
  if (error.message.includes('API key')) {
    console.error('Authentication failed - check your API key');
  } else if (error.message.includes('credits')) {
    console.error('Insufficient credits');
  } else if (error.message.includes('moderation')) {
    console.error('Content rejected by moderation filters');
  } else {
    console.error('Generation failed:', error.message);
  }
}

Retry Behavior

The API includes automatic retry logic for transient errors:

Setting	Default	Description
Max Retries	3	Number of retry attempts before failing
Backoff	Exponential	1s → 2s → 4s between retries
Retry On	`502`, `503`, `504`, network errors	Transient/temporary failures
No Retry	`400`, `401`, `402`, `422`, `429`	Permanent errors (bad request, auth, rate limit)

// Configure retry behavior for async operations
const result = await api.waitForResult(taskId, {
  maxRetries: 5,       // Override default retry count
  pollInterval: 3,     // Seconds between polls
  timeout: 600         // Max wait time in seconds
});

// Disable retries by catching and not retrying
try {
  const result = await api.generateUltra({ prompt: 'test' });
} catch (error) {
  // Handle without retry
  console.error('Failed:', error.message);
}

CLI Usage

Show Help

sai --help

Show Examples

sai --examples

Generation Commands

Stable Image Ultra:

sai generate ultra \
  --prompt "a serene mountain landscape at sunset" \
  --aspect-ratio "16:9" \
  --output-format png

Stable Image Core with Style:

sai generate core \
  --prompt "cyberpunk city at night" \
  --aspect-ratio "21:9" \
  --style-preset cinematic

Stable Diffusion 3.5:

sai generate sd3 \
  --prompt "fantasy castle on floating island" \
  --model sd3.5-large-turbo \
  --aspect-ratio "16:9"

Upscale Commands

Fast Upscale:

sai upscale fast \
  --image ./photo.jpg \
  --output-format png

Conservative Upscale:

sai upscale conservative \
  --image ./photo.jpg \
  --prompt "enhance details and sharpness"

Creative Upscale:

sai upscale creative \
  --image ./sketch.jpg \
  --prompt "photorealistic rendering" \
  --creativity 0.35

Batch Processing

Process multiple prompts in a single command:

sai generate core \
  --prompt "a red sports car" \
  --prompt "a blue vintage car" \
  --prompt "a green electric car" \
  --aspect-ratio "16:9"

Edit Commands

Erase Objects:

sai edit erase \
  --image ./photo.jpg \
  --mask ./mask.png \
  --grow-mask 5

Inpaint:

sai edit inpaint \
  --image ./photo.jpg \
  --mask ./mask.png \
  --prompt "blue sky with clouds" \
  --style-preset photographic

Outpaint:

sai edit outpaint \
  --image ./landscape.jpg \
  --left 200 --right 200 \
  --prompt "continuation of landscape" \
  --creativity 0.5

Search and Replace:

sai edit search-replace \
  --image ./pet.jpg \
  --search "cat" \
  --prompt "golden retriever"

Search and Recolor:

sai edit search-recolor \
  --image ./car.jpg \
  --select "car" \
  --prompt "bright red metallic paint"

Remove Background:

sai edit remove-bg \
  --image ./portrait.jpg \
  --output-format png

Replace Background and Relight:

sai edit replace-bg \
  --image ./portrait.jpg \
  --background-prompt "sunset beach with palm trees" \
  --light-direction right

Show Edit Examples:

sai edit examples

Control Commands

Sketch to Image:

sai control sketch \
  --image ./sketch.png \
  --prompt "castle on a hill, fantasy style" \
  --control-strength 0.7

Structure Preservation:

sai control structure \
  --image ./statue.jpg \
  --prompt "garden shrub sculpture" \
  --control-strength 0.8

Style Reference:

sai control style \
  --image ./art-reference.png \
  --prompt "portrait of a chicken" \
  --fidelity 0.5

Style Transfer:

sai control style-transfer \
  --init-image ./photo.png \
  --style-image ./artwork.jpg \
  --style-strength 0.7

Show Control Examples:

sai control examples

Examples

Basic Image Generation

# Simple generation with Ultra model
sai generate ultra --prompt "a cat wearing a wizard hat"

# With custom aspect ratio
sai generate ultra \
  --prompt "mountain landscape" \
  --aspect-ratio "21:9"

# With seed for reproducibility
sai generate core \
  --prompt "abstract art" \
  --seed 42

Image-to-Image with Ultra

sai generate ultra \
  --prompt "transform into oil painting style" \
  --image ./photo.jpg \
  --strength 0.6

Style Presets with Core

sai generate core \
  --prompt "portrait of a person" \
  --style-preset photographic

Upscaling Workflow

# Fast 4x upscale (input must be ≤1MP)
sai upscale fast --image ./low_res.jpg

# Conservative 40x upscale with prompt (accepts larger images)
sai upscale conservative \
  --image ./photo.jpg \
  --prompt "enhance facial details"

# Creative upscale with high creativity (input must be ≤1MP)
sai upscale creative \
  --image ./sketch.jpg \
  --prompt "vibrant colors, enhanced details" \
  --creativity 0.5

Note: Fast and Creative upscalers require input ≤1MP (1,048,576 pixels). Conservative accepts larger images.

Advanced Options

# Custom output directory
sai generate ultra \
  --prompt "logo design" \
  --output-dir ./my-generations

# Debug logging
sai generate core \
  --prompt "test image" \
  --log-level debug

# Negative prompts
sai generate sd3 \
  --prompt "beautiful landscape" \
  --negative-prompt "people, cars, buildings"

Data Organization

Generated images and metadata are saved in organized directories:

datasets/
└── stability/
    ├── stable-image-ultra/
    │   ├── 2025-11-17_01-20-50-180_mountain_landscape.png
    │   └── 2025-11-17_01-20-50-180_mountain_landscape_metadata.json
    ├── stable-image-core/
    ├── sd3-large/
    ├── upscale-fast/
    ├── upscale-conservative/
    └── upscale-creative/

Metadata includes:

Model used
Generation timestamp
All parameters (prompt, aspect_ratio, seed, etc.)
Result information (finish_reason, seed)
File paths

Security Features

API Key Protection

API keys are redacted in all logs (shows only last 4 characters: xxx...abc1234)
Never logged in full, even in DEBUG mode
Prevents accidental exposure in log aggregation systems

Error Message Sanitization

In production (NODE_ENV=production), returns generic error messages
Prevents information disclosure about internal systems
Development mode shows detailed errors for debugging

HTTPS Enforcement

Base URLs must use HTTPS protocol
Constructor throws error if HTTP URL is provided
Prevents man-in-the-middle attacks

SSRF Protection

All image URLs validated before processing
Blocks localhost (127.0.0.1, ::1, localhost)
Blocks private IP ranges (10.x, 192.168.x, 172.16-31.x, 169.254.x)
Blocks cloud metadata endpoints (169.254.169.254, metadata.google.internal)
IPv4-Mapped IPv6 Bypass Prevention: Detects and blocks [::ffff:127.0.0.1], etc.
DNS Rebinding Prevention: Performs DNS resolution to block domains that resolve to internal/private IPs (prevents TOCTOU attacks via wildcard DNS services like nip.io)
Only allows HTTPS URLs for remote images

DoS Prevention

Request timeout: 30 seconds for API calls
File size limit: 50MB maximum for image processing
Redirect limit: Maximum 5 redirects
Prevents resource exhaustion attacks

Parameter Validation

Pre-flight validation using validateModelParams()
Validates all parameters against model constraints
Saves API credits by catching errors early

Image File Validation

Magic byte checking for PNG, JPEG, WebP formats
File size validation
Format/extension validation
Prevents processing of malicious files

Testing

The service includes comprehensive testing:

# Run all tests (283 tests)
npm test

# Watch mode for development
npm run test:watch

# Interactive UI
npm run test:ui

# Coverage report
npm run test:coverage

Test Coverage:

API authentication and key validation
All generation methods (ultra, core, sd3)
All upscale methods (fast, conservative, creative)
Synchronous and asynchronous response handling
Parameter validation with model-specific constraints
Security features (HTTPS enforcement, API key redaction, error sanitization, SSRF protection)
Utility functions (Buffer handling, form data building, image validation)
Error handling and production mode sanitization

Troubleshooting

Common Issues

Authentication Failed:

# Verify your API key is set
echo $STABILITY_API_KEY

# Or use CLI flag
sai generate ultra --api-key "your-key" --prompt "test"

Invalid Parameters:

Check that aspect_ratio is from valid set (1:1, 16:9, 21:9, 2:3, 3:2, 4:5, 5:4, 9:16, 9:21)
Ensure seed is between 0 and 4,294,967,294
Verify strength (image-to-image) is between 0.0 and 1.0
Check creativity (Creative Upscale) is between 0.1 and 0.5

Rate Limit Exceeded:

The service automatically retries on transient errors
Check your API usage limits at Stability AI dashboard
Wait a few moments before retrying

Image File Not Found:

# Verify file exists
ls -lh ./photo.jpg

# Use absolute path if needed
sai upscale fast --image /full/path/to/photo.jpg

Debug Mode:

# Enable debug logging for detailed information
sai generate ultra --prompt "test" --log-level debug

Response Types

Synchronous (Ultra, Core, SD3, Fast/Conservative Upscale):

Returns HTTP 200 with image Buffer immediately
No polling required
CLI spinner shows during request

Asynchronous (Creative Upscale only):

Returns HTTP 202 with task ID
Automatically polls for result
CLI spinner shows time elapsed and estimated remaining time

API Response Patterns

The Stability AI API has unique response characteristics:

Synchronous responses: Return HTTP 200 with raw image Buffer immediately
Asynchronous responses: Return HTTP 202 with task ID, requires polling
Multipart/form-data: All requests use form-data (not JSON)
Buffer handling: Images returned as binary Buffers, not base64

Related Packages

This package is part of the img-gen ecosystem. Check out these other AI generation services:

bfl-api - Black Forest Labs API wrapper for FLUX and Kontext models
ideogram-api - Ideogram API wrapper for image generation, editing, remixing, and manipulation
google-genai-api - Google Generative AI (Imagen) wrapper
openai-api - OpenAI API wrapper for DALL-E and GPT Image generation

Disclaimer: This project is an independent community wrapper and is not affiliated with Stability AI.

License

MIT

Contributing

Contributions welcome! Please ensure all tests pass before submitting PRs:

npm test  # All 283 tests must pass

Thankee-sai.

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
.github/workflows		.github/workflows
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
.npmignore		.npmignore
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.js		vitest.config.js

License

aself101/stability-ai-api

Folders and files

Latest commit

History

Repository files navigation

Stability AI Image Generation Service

Quick Start

CLI Usage

Demo

Programmatic Usage

Table of Contents

Overview

Endpoint Summary

Models

Stable Image Ultra

Stable Image Core

Stable Diffusion 3.5

Upscale Fast

Upscale Conservative

Upscale Creative

Edit Operations

Erase

Inpaint

Outpaint

Search and Replace

Search and Recolor

Remove Background

Replace Background and Relight

Style Presets (for applicable operations)

Edit Credits

Control Operations

Control: Sketch

Control: Structure

Control: Style

Control: Style Transfer

Control Credits

Authentication Setup

1. Get Your API Key

2. Configure Your API Key

Option 1: CLI Flag (Highest Priority)

Option 2: Environment Variable

Option 3: Local .env File

Option 4: Global Configuration

Installation

Global Installation (Recommended)

Local Development

TypeScript Support

Exported Types

Type-Safe Parameters

Building from Source

Programmatic Usage

Basic Setup

Generation Methods

Stable Image Ultra - Text-to-Image

Stable Image Ultra - Image-to-Image

Stable Image Core with Style Presets

Stable Diffusion 3.5

Upscaling Methods

Fast Upscale (4x, ~1 second)

Conservative Upscale (20-40x to 4MP)

Creative Upscale (20-40x with reimagining)

Control Methods

Control: Sketch

Control: Structure

Control: Style

Control: Style Transfer

Utility Methods

Check Account Credits

Get Result for Async Operations

Complete Example: Batch Generation

Complete Example: Image Processing Pipeline

Complete Example: Edit Operations

Error Handling

Retry Behavior

CLI Usage

Show Help

Show Examples

Generation Commands

Upscale Commands

Packages