Last updated February 09, 2026

The Stability AI Stable Image Ultra (stability-image-ultra) model allows you to generate high-quality, detailed images from descriptive text prompts. This guide details how to access the v1-images-generations API using JavaScript.

Prerequisites

1. Attach an inference addon to an app of yours:

   # If you don't have an app yet, you can create one with:
   heroku create $APP_NAME # specify the name you want for your app (or skip this step to use an existing app you have)
   
   # Create and attach one of our chat models to your app, $APP_NAME:
   heroku addons:create heroku-inference:standard -a $APP_NAME --as INFERENCE
   

2. Install the necessary axios package:

   npm install axios
   

JavaScript Example Code

const axios = require('axios');
const fs = require('fs');
const { exec } = require('child_process');

// Assert that environment variables are set
const DIFFUSION_URL = process.env.DIFFUSION_URL;
const DIFFUSION_KEY = process.env.DIFFUSION_KEY;

if (!DIFFUSION_URL || !DIFFUSION_KEY) {
    console.error("Missing required environment variables.");
    console.log("Set them up using the following commands:");
    console.log("export DIFFUSION_URL=$(heroku config:get -a $APP_NAME DIFFUSION_URL)");
    console.log("export DIFFUSION_KEY=$(heroku config:get -a $APP_NAME DIFFUSION_KEY)");
    process.exit(1);
}

async function parseImageOutput(response, payload, filename = null) {
    if (response.status === 200) {
        if (payload.response_format === "base64") {
            filename = filename || `${payload.prompt.slice(0, 20).replace(/ /g, "_").toLowerCase()}.png`;
            fs.writeFileSync(filename, response.data.data[0].b64_json, 'base64');
            console.log(`Image saved as ${filename}`);

            // Automatically open the image after saving
            openImage(filename);
        } else {
            console.log("Download the image from:", response.data.data[0].url);
        }
    } else {
        console.log(`Request failed: ${response.status}, ${response.statusText}`);
    }
}

function openImage(filename) {
    const platform = process.platform;
    let command;

    if (platform === 'darwin') { // macOS
        command = `open ${filename}`;
    } else if (platform === 'win32') { // Windows
        command = `start ${filename}`;
    } else if (platform === 'linux') { // Linux
        command = `xdg-open ${filename}`;
    }

    if (command) {
        exec(command, (error) => {
            if (error) {
                console.error(`Failed to open image: ${error.message}`);
            } else {
                console.log(`Opened image: ${filename}`);
            }
        });
    } else {
        console.log("Automatic image opening is not supported on this platform.");
    }
}

async function generateImage(payload, filename = null) {
    try {
        const response = await axios.post(`${DIFFUSION_URL}/v1/images/generations`, payload, {
            headers: {
                'Authorization': `Bearer ${DIFFUSION_KEY}`,
                'Content-Type': 'application/json'
            }
        });
        await parseImageOutput(response, payload, filename);
    } catch (error) {
        console.error("Error generating image:", error.message);
    }
}

// Example payload
const payload = {
    model: "stable-image-ultra",
    prompt: "A surreal landscape with glowing mushrooms under a night sky.",
    aspect_ratio: "16:9",
    output_format: "png",
    seed: 123,
    negative_prompt: "crowded, noisy, chaotic"
};

// Generate image
generateImage(payload);