> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stability.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Base URL, authentication, request and response formats, async results, errors, and rate limits for the Stability AI REST API.

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:

```text theme={null}
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:

```bash theme={null}
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](https://platform.stability.ai/dashboard/api-keys) page. Requests with a missing or invalid key return `401`.

<Warning>
  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.
</Warning>

## 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:

```json theme={null}
{ "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](/api-reference/audio-results/fetch-audio-result) |
| Image and 3D services | [Fetch async generation result](/api-reference/results/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`:

```json theme={null}
{
  "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](https://kb.stability.ai/knowledge-base/kb-tickets/new) if it keeps failing. |

Include the error `id` when you [contact support](https://kb.stability.ai/knowledge-base/kb-tickets/new). 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](https://kb.stability.ai/knowledge-base/kb-tickets/new).

## Credits

Each successful request consumes credits. The cost depends on the service. See [Pricing](/pricing) for per-service costs.