API reference

The Stability AI REST API generates and edits images, audio, and 3D models. Every endpoint in this reference has an interactive playground: add your API key and send a real request from the page.

Base URL

All requests go to:

https://api.stability.ai

Current endpoints live under /v2beta, for example POST /v2beta/stable-image/generate/core.

Authentication

Authenticate every request with your API key in the Authorization header, using the Bearer scheme:

curl https://api.stability.ai/v2beta/stable-image/generate/core \
  -H "Authorization: Bearer $STABILITY_API_KEY" \
  -H "Accept: image/*" \
  -F prompt="A lighthouse on a cliff at sunrise" \
  -o lighthouse.png

Create and manage keys on the API keys page. Requests with a missing or invalid key return 401.

Keep your API key secret. Don’t share it or commit it to a repository. If a key leaks, create a new one and delete the old one.

Requests

Generation and editing endpoints accept multipart/form-data. Send text parameters as form fields and images or audio as file fields.

Responses

Use the Accept header to choose how you receive generated media:

`Accept` value	Response
`image/` or `audio/`	Raw bytes of the file
`application/json`	JSON with the file base64-encoded, plus metadata such as `seed` and `finish_reason`

Image endpoints also return the seed and finish reason in the seed and finish-reason response headers. A finish reason of CONTENT_FILTERED means the output violated the content moderation policy and was blurred.

Async generations

Some services take longer to run, such as Stable Audio 3.0, Creative Upscale, and Replace Background and Relight. These endpoints return an id immediately instead of the result:

{ "id": "a6dc6c6e20acda010fe14d71f180658f2896ed9b4ec25aa99a6ff06c796987c4" }

Poll the matching results endpoint with that id until it returns the result:

Service	Results endpoint
Stable Audio 3.0	Fetch audio result
Image and 3D services	Fetch async generation result

Both endpoints report progress the same way:

202 means the generation is still in progress.
200 returns the finished result.

Fetch results with the same API key you used to start the generation. Results are stored for 24 hours.

Errors

Errors return a JSON body with a machine-readable name and a list of human-readable errors:

{
  "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "name": "bad_request",
  "errors": ["prompt: is required"]
}

Status	Meaning
`400`	One or more parameters are invalid. Check `errors` for details.
`401`	The API key is missing or invalid.
`402`	Your account doesn’t have enough credits.
`403`	The request was flagged by content moderation.
`413`	The request body is too large.
`422`	The request was well-formed but couldn’t be processed, for example because an input image or language isn’t supported.
`429`	You exceeded the rate limit.
`500`	Something went wrong on our side. Retry the request, and contact support if it keeps failing.

Include the error id when you contact support. It helps us find the failed request.

Rate limits

You can make up to 150 requests in any 10-second window. If you exceed the limit, the API returns 429 and blocks your requests for 60 seconds. If you need a higher limit, contact support.

Credits

Each successful request consumes credits. The cost depends on the service. See Pricing for per-service costs.

Overview

Audio

Stable Image

3D

Legacy

Base URL

Authentication

Requests

Responses

Async generations

Errors

Rate limits

Credits

​Base URL

​Authentication

​Requests

​Responses

​Async generations

​Errors

​Rate limits

​Credits

Base URL

Authentication

Requests

Responses

Async generations

Errors

Rate limits

Credits