Stability.ai REST API
API docs by Redocly

Stability.ai REST API (v1)

Download OpenAPI specification:Download

Terms of Service

Welcome to the Stability.ai REST API!

Your DreamStudio API key will be required for authentication: How to find your API key

API operations use the following versioning scheme:

  • /v* interface is stable and ready for production workloads
  • /v*beta*: interface is stable, preparing for production release
  • /v*alpha*: under development and the interface is subject to change

NOTE: The v1alpha and v1beta endpoints from the developer preview are still available, but they will disabled on May 1st, 2023. Please migrate to the v1 endpoints as soon as possible.

If you have feedback or encounter any issues with the API, please reach out:

v1/user

Manage your Stability.ai account, and view account/organization balances

account

Get information about the account associated with the provided API key

Authorizations:
STABILITY_API_KEY

Responses

Request samples 

import os
import requests

api_host = os.getenv('API_HOST', 'https://api.stability.ai')
url = f"{api_host}/v1/user/account"

api_key = os.getenv("STABILITY_API_KEY")
if api_key is None:
    raise Exception("Missing Stability API key.")

response = requests.get(url, headers={
    "Authorization": f"Bearer {api_key}"
})

if response.status_code != 200:
    raise Exception("Non-200 response: " + str(response.text))

# Do something with the payload...
payload = response.json()

Response samples

Content type
application/json
{
  • "email": "[email protected]",
  • "id": "user-1234",
  • "organizations": [
    ],
  • "profile_picture": "https://api.stability.ai/example.png"
}

balance

Get the credit balance of the account/organization associated with the API key

Authorizations:
STABILITY_API_KEY
header Parameters
Organization
string
Example: org-123456

Allows for requests to be scoped to an organization other than the user's default. If not provided, the user's default organization will be used.

Responses

Request samples 

import os
import requests

api_host = os.getenv('API_HOST', 'https://api.stability.ai')
url = f"{api_host}/v1/user/balance"

api_key = os.getenv("STABILITY_API_KEY")
if api_key is None:
    raise Exception("Missing Stability API key.")

response = requests.get(url, headers={
    "Authorization": f"Bearer {api_key}"
})

if response.status_code != 200:
    raise Exception("Non-200 response: " + str(response.text))

# Do something with the payload...
payload = response.json()

Response samples

Content type
application/json
{
  • "credits": 0.6336833840314097
}

v1/engines

Enumerate available engines

list

List all engines available to your organization/user

Authorizations:
STABILITY_API_KEY
header Parameters
Organization
string
Example: org-123456

Allows for requests to be scoped to an organization other than the user's default. If not provided, the user's default organization will be used.

Responses

Request samples 

import os
import requests

api_host = os.getenv('API_HOST', 'https://api.stability.ai')
url = f"{api_host}/v1/engines/list"

api_key = os.getenv("STABILITY_API_KEY")
if api_key is None:
    raise Exception("Missing Stability API key.")

response = requests.get(url, headers={
    "Authorization": f"Bearer {api_key}"
})

if response.status_code != 200:
    raise Exception("Non-200 response: " + str(response.text))

# Do something with the payload...
payload = response.json()

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

v1/generation

Generate images from text, existing images, or both

text-to-image

Generate a new image from a text prompt

Authorizations:
STABILITY_API_KEY
path Parameters
engine_id
required
string
Example: stable-diffusion-v1-5
header Parameters
Accept
string
Default: application/json
Enum: "application/json" "image/png"

The format of the response. Leave blank for JSON, or set to 'image/png' for a PNG image.

Organization
string
Example: org-123456

Allows for requests to be scoped to an organization other than the user's default. If not provided, the user's default organization will be used.

Request Body schema: application/json
height
integer (DiffuseImageHeight) multiple of 64 >= 128
Default: 512

Height of the image in pixels. Must be in increments of 64 and pass the following validation:

  • For 768 engines: 589,824 ≤ height * width ≤ 1,048,576
  • All other engines: 262,144 ≤ height * width ≤ 1,048,576
width
integer (DiffuseImageWidth) multiple of 64 >= 128
Default: 512

Width of the image in pixels. Must be in increments of 64 and pass the following validation:

  • For 768 engines: 589,824 ≤ height * width ≤ 1,048,576
  • All other engines: 262,144 ≤ height * width ≤ 1,048,576
required
Array of objects (TextPrompts) non-empty

An array of text prompts to use for generation.

Given a text prompt with the text A lighthouse on a cliff and a weight of 0.5, it would be represented as:

"text_prompts": [
  {
    "text": "A lighthouse on a cliff",
    "weight": 0.5
  }
]
cfg_scale
number (CfgScale) [ 0 .. 35 ]
Default: 7

How strictly the diffusion process adheres to the prompt text (higher values keep your image closer to your prompt)

clip_guidance_preset
string (ClipGuidancePreset)
Default: "NONE"
Enum: "FAST_BLUE" "FAST_GREEN" "NONE" "SIMPLE" "SLOW" "SLOWER" "SLOWEST"
sampler
string (Sampler)
Enum: "DDIM" "DDPM" "K_DPMPP_2M" "K_DPMPP_2S_ANCESTRAL" "K_DPM_2" "K_DPM_2_ANCESTRAL" "K_EULER" "K_EULER_ANCESTRAL" "K_HEUN" "K_LMS"

Which sampler to use for the diffusion process. If this value is omitted we'll automatically select an appropriate sampler for you.

samples
integer (Samples) [ 1 .. 10 ]
Default: 1

Number of images to generate

seed
integer (Seed) [ 0 .. 4294967295 ]
Default: 0

Random noise seed (omit this option or use 0 for a random seed)

steps
integer (Steps) [ 10 .. 150 ]
Default: 50

Number of diffusion steps to run

Responses

Request samples

Content type
application/json
{
  • "cfg_scale": 7,
  • "clip_guidance_preset": "FAST_BLUE",
  • "height": 512,
  • "width": 512,
  • "sampler": "K_DPM_2_ANCESTRAL",
  • "samples": 1,
  • "steps": 75,
  • "text_prompts": [
    ]
}

Response samples

Content type
[
  • [
    ]
]

image-to-image

Modify an image based on a text prompt

Authorizations:
STABILITY_API_KEY
path Parameters
engine_id
required
string
Example: stable-diffusion-v1-5
header Parameters
Accept
string
Default: application/json
Enum: "application/json" "image/png"

The format of the response. Leave blank for JSON, or set to 'image/png' for a PNG image.

Organization
string
Example: org-123456

Allows for requests to be scoped to an organization other than the user's default. If not provided, the user's default organization will be used.

Request Body schema: multipart/form-data
required
Array of objects (TextPrompts) non-empty

An array of text prompts to use for generation.

Due to how arrays are represented in multipart/form-data requests, prompts must adhear to the format text_prompts[index][text|weight], where index is some integer used to tie the text and weight together. While index does not have to be sequential, duplicate entries will override previous entries, so it is recommended to use sequential indices.

Given a text prompt with the text A lighthouse on a cliff and a weight of 0.5, it would be represented as:

text_prompts[0][text]: "A lighthouse on a cliff"
text_prompts[0][weight]: 0.5

To add another prompt to that request simply provide the values under a new index:

text_prompts[0][text]: "A lighthouse on a cliff"
text_prompts[0][weight]: 0.5
text_prompts[1][text]: "land, ground, dirt, grass"
text_prompts[1][weight]: -0.9
init_image
required
string <binary> (InitImage)

Image used to initialize the diffusion process, in lieu of random noise.

init_image_mode
string (InitImageMode)
Default: "IMAGE_STRENGTH"

Whether to use image_strength or step_schedule_* to control how much influence the init_image has on the result.

image_strength
number <float> (InitImageStrength) [ 0 .. 1 ]
Default: 0.35

How much influence the init_image has on the diffusion process. Values close to 1 will yield images very similar to the init_image while values close to 0 will yield images wildly different than the init_image. The behavior of this is meant to mirror DreamStudio's "Image Strength" slider.

This parameter is just an alternate way to set step_schedule_start, which is done via the calculation 1 - image_strength. For example, passing in an Image Strength of 35% (0.35) would result in a step_schedule_start of 0.65.

cfg_scale
number (CfgScale) [ 0 .. 35 ]
Default: 7

How strictly the diffusion process adheres to the prompt text (higher values keep your image closer to your prompt)

clip_guidance_preset
string (ClipGuidancePreset)
Default: "NONE"
Enum: "FAST_BLUE" "FAST_GREEN" "NONE" "SIMPLE" "SLOW" "SLOWER" "SLOWEST"
sampler
string (Sampler)
Enum: "DDIM" "DDPM" "K_DPMPP_2M" "K_DPMPP_2S_ANCESTRAL" "K_DPM_2" "K_DPM_2_ANCESTRAL" "K_EULER" "K_EULER_ANCESTRAL" "K_HEUN" "K_LMS"

Which sampler to use for the diffusion process. If this value is omitted we'll automatically select an appropriate sampler for you.

samples
integer (Samples) [ 1 .. 10 ]
Default: 1

Number of images to generate

seed
integer (Seed) [ 0 .. 4294967295 ]
Default: 0

Random noise seed (omit this option or use 0 for a random seed)

steps
integer (Steps) [ 10 .. 150 ]
Default: 50

Number of diffusion steps to run

Responses

Request samples

Content type
multipart/form-data
Example

Request using 35% image_strength

{
  "image_strength": 0.35,
  "init_image_mode": "IMAGE_STRENGTH",
  "init_image": "<image binary>",
  "text_prompts[0][text]": "A dog space commander",
  "text_prompts[0][weight]": 1,
  "cfg_scale": 7,
  "clip_guidance_preset": "FAST_BLUE",
  "sampler": "K_DPM_2_ANCESTRAL",
  "samples": 3,
  "steps": 20
}

Response samples

Content type
[
  • [
    ]
]

image-to-image/upscale

Create a higher resolution version of an input image.

This operation outputs an image with a maximum pixel count of 4,194,304. This is equivalent to dimensions such as 2048x2048 and 4096x1024.

By default, the input image will be upscaled by a factor of 2. For additional control over the output dimensions, a width or height parameter may be specified.

Authorizations:
STABILITY_API_KEY
path Parameters
engine_id
required
string
Examples:
  • esrgan-v1-x2plus - ESRGAN X2+
header Parameters
Accept
string
Default: application/json
Enum: "application/json" "image/png"

The format of the response. Leave blank for JSON, or set to 'image/png' for a PNG image.

Organization
string
Example: org-123456

Allows for requests to be scoped to an organization other than the user's default. If not provided, the user's default organization will be used.

Request Body schema: multipart/form-data
image
required
string <binary> (InputImage)
width
integer (UpscaleImageWidth) >= 512

Desired width of the output image. Only one of width or height may be specified.

height
integer (UpscaleImageHeight) >= 512

Desired height of the output image. Only one of width or height may be specified.

Responses

Request samples

Content type
multipart/form-data
Example

Upscale input image by 2x

{
  "image": "<image binary>"
}

Response samples

Content type
[
  • [
    ]
]

image-to-image/masking

Selectively modify portions of an image using a mask

Authorizations:
STABILITY_API_KEY
path Parameters
engine_id
required
string
Example: stable-inpainting-512-v2-0
header Parameters
Accept
string
Default: application/json
Enum: "application/json" "image/png"

The format of the response. Leave blank for JSON, or set to 'image/png' for a PNG image.

Organization
string
Example: org-123456

Allows for requests to be scoped to an organization other than the user's default. If not provided, the user's default organization will be used.

Request Body schema: multipart/form-data
required
Array of objects (TextPrompts) non-empty

An array of text prompts to use for generation.

Due to how arrays are represented in multipart/form-data requests, prompts must adhear to the format text_prompts[index][text|weight], where index is some integer used to tie the text and weight together. While index does not have to be sequential, duplicate entries will override previous entries, so it is recommended to use sequential indices.

Given a text prompt with the text A lighthouse on a cliff and a weight of 0.5, it would be represented as:

text_prompts[0][text]: "A lighthouse on a cliff"
text_prompts[0][weight]: 0.5

To add another prompt to that request simply provide the values under a new index:

text_prompts[0][text]: "A lighthouse on a cliff"
text_prompts[0][weight]: 0.5
text_prompts[1][text]: "land, ground, dirt, grass"
text_prompts[1][weight]: -0.9
init_image
required
string <binary> (InitImage)

Image used to initialize the diffusion process, in lieu of random noise.

mask_source
required
string (MaskSource)

For any given pixel, the mask determines the strength of generation on a linear scale. This parameter determines where to source the mask from:

  • MASK_IMAGE_WHITE will use the white pixels of the mask_image as the mask, where white pixels are completely replaced and black pixels are unchanged
  • MASK_IMAGE_BLACK will use the black pixels of the mask_image as the mask, where black pixels are completely replaced and white pixels are unchanged
  • INIT_IMAGE_ALPHA will use the alpha channel of the init_image as the mask, where fully transparent pixels are completely replaced and fully opaque pixels are unchanged
mask_image
required
string <binary> (MaskImage)

Optional grayscale mask that allows for influence over which pixels are eligible for diffusion and at what strength. Must be the same dimensions as the init_image. Use the mask_source option to specify whether the white or black pixels should be inpainted.

cfg_scale
number (CfgScale) [ 0 .. 35 ]
Default: 7

How strictly the diffusion process adheres to the prompt text (higher values keep your image closer to your prompt)

clip_guidance_preset
string (ClipGuidancePreset)
Default: "NONE"
Enum: "FAST_BLUE" "FAST_GREEN" "NONE" "SIMPLE" "SLOW" "SLOWER" "SLOWEST"
sampler
string (Sampler)
Enum: "DDIM" "DDPM" "K_DPMPP_2M" "K_DPMPP_2S_ANCESTRAL" "K_DPM_2" "K_DPM_2_ANCESTRAL" "K_EULER" "K_EULER_ANCESTRAL" "K_HEUN" "K_LMS"

Which sampler to use for the diffusion process. If this value is omitted we'll automatically select an appropriate sampler for you.

samples
integer (Samples) [ 1 .. 10 ]
Default: 1

Number of images to generate

seed
integer (Seed) [ 0 .. 4294967295 ]
Default: 0

Random noise seed (omit this option or use 0 for a random seed)

steps
integer (Steps) [ 10 .. 150 ]
Default: 50

Number of diffusion steps to run

Responses

Request samples

Content type
multipart/form-data
Example
{
  "mask_source": "MASK_IMAGE_BLACK",
  "init_image": "<image binary>",
  "mask_image": "<image binary>",
  "text_prompts[0][text]": "A dog space commander",
  "text_prompts[0][weight]": 1,
  "cfg_scale": 7,
  "clip_guidance_preset": "FAST_BLUE",
  "sampler": "K_DPM_2_ANCESTRAL",
  "samples": 3,
  "steps": 20
}

Response samples

Content type
[
  • [
    ]
]