Stability.ai REST API
API docs by Redocly

Stability.ai REST API (v1)

Download OpenAPI specification:Download

Terms of Service

Welcome to the official Stability AI REST API!

Authentication

You will need your Stability API key in order to make requests to this API. Make sure you never share your API key with anyone, and you never commit it to a public repository. Include this key in the Authorization header of your requests.

Rate limiting

This API is rate-limited to 150 requests every 10 seconds. If you exceed this limit, you will receive a 429 response. If you find this limit too restrictive, please reach out to us via email at platform@stability.ai.

Support

Check our Status Page to view the current health of our REST/gRPC APIs.

If you run into issues, please reach out to us:

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": "example@stability.ai",
  • "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.

Stability-Client-ID
string
Example: my-great-plugin

Used to identify the source of requests, such as the client application or sub-organization. Optional, but recommended for organizational clarity.

Stability-Client-Version
string
Example: 1.2.1

Used to identify the version of the application or service making the requests. Optional, but recommended for organizational clarity.

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.

Stability-Client-ID
string
Example: my-great-plugin

Used to identify the source of requests, such as the client application or sub-organization. Optional, but recommended for organizational clarity.

Stability-Client-Version
string
Example: 1.2.1

Used to identify the version of the application or service making the requests. Optional, but recommended for organizational clarity.

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-6
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.

Stability-Client-ID
string
Example: my-great-plugin

Used to identify the source of requests, such as the client application or sub-organization. Optional, but recommended for organizational clarity.

Stability-Client-Version
string
Example: 1.2.1

Used to identify the version of the application or service making the requests. Optional, but recommended for organizational clarity.

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

Height of the image to generate, in pixels, in an increment divible by 64.

Engine-specific dimension validation:

  • SDXL Beta: must be between 128x128 and 512x896 (or 896x512); only one dimension can be greater than 512.
  • SDXL v0.9: must be one of 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640, 640x1536, 768x1344, 832x1216, or 896x1152
  • SDXL v1.0: same as SDXL v0.9
  • SD v1.6: must be between 320x320 and 1536x1536
width
integer (DiffuseImageWidth) multiple of 64 >= 128
Default: 512

Width of the image to generate, in pixels, in an increment divible by 64.

Engine-specific dimension validation:

  • SDXL Beta: must be between 128x128 and 512x896 (or 896x512); only one dimension can be greater than 512.
  • SDXL v0.9: must be one of 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640, 640x1536, 768x1344, 832x1216, or 896x1152
  • SDXL v1.0: same as SDXL v0.9
  • SD v1.6: must be between 320x320 and 1536x1536
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 .. 50 ]
Default: 30

Number of diffusion steps to run.

style_preset
string (StylePreset)
Enum: "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"

Pass in a style preset to guide the image model towards a particular style. This list of style presets is subject to change.

extras
object (Extras)

Extra parameters passed to the engine. These parameters are used for in-development or experimental features and may change without warning, so please use with caution.

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": 30,
  • "text_prompts": [
    ]
}

Response samples

Content type
{
  • "artifacts": [
    ]
}

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-6
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.

Stability-Client-ID
string
Example: my-great-plugin

Used to identify the source of requests, such as the client application or sub-organization. Optional, but recommended for organizational clarity.

Stability-Client-Version
string
Example: 1.2.1

Used to identify the version of the application or service making the requests. Optional, but recommended for organizational clarity.

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 adhere 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 .. 50 ]
Default: 30

Number of diffusion steps to run.

style_preset
string (StylePreset)
Enum: "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"

Pass in a style preset to guide the image model towards a particular style. This list of style presets is subject to change.

extras
object (Extras)

Extra parameters passed to the engine. These parameters are used for in-development or experimental features and may change without warning, so please use with caution.

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": 30
}

Response samples

Content type
{
  • "artifacts": [
    ]
}

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.

For upscaler engines that are ESRGAN-based, refer to the RealESRGANUpscaleRequestBody body option below. For upscaler engines that are Stable Diffusion Latent Upscaler-based, refer to the LatentUpscalerUpscaleRequestBody body option below.

For more details on the upscaler engines, refer to the documentation on the Platform site.

Authorizations:
STABILITY_API_KEY
path Parameters
engine_id
required
string
Examples:
  • esrgan-v1-x2plus - ESRGAN x2 Upscaler
  • stable-diffusion-x4-latent-upscaler - Stable Diffusion x4 Latent Upscaler
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.

Stability-Client-ID
string
Example: my-great-plugin

Used to identify the source of requests, such as the client application or sub-organization. Optional, but recommended for organizational clarity.

Stability-Client-Version
string
Example: 1.2.1

Used to identify the version of the application or service making the requests. Optional, but recommended for organizational clarity.

Request Body schema: multipart/form-data
One of
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 using ESRGAN.

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

Response samples

Content type
{
  • "artifacts": [
    ]
}

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-diffusion-v1-6
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.

Stability-Client-ID
string
Example: my-great-plugin

Used to identify the source of requests, such as the client application or sub-organization. Optional, but recommended for organizational clarity.

Stability-Client-Version
string
Example: 1.2.1

Used to identify the version of the application or service making the requests. Optional, but recommended for organizational clarity.

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 adhere 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 .. 50 ]
Default: 30

Number of diffusion steps to run.

style_preset
string (StylePreset)
Enum: "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"

Pass in a style preset to guide the image model towards a particular style. This list of style presets is subject to change.

extras
object (Extras)

Extra parameters passed to the engine. These parameters are used for in-development or experimental features and may change without warning, so please use with caution.

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": 30
}

Response samples

Content type
{
  • "artifacts": [
    ]
}