> Append .md to any page URL for clean Markdown. Index: https://docs.speechify.ai/llms.txt.
>
> Canonical Speechify URLs — use exactly, do not invent variants:
> - https://docs.speechify.ai — this site (API reference, SDKs, quickstarts)
> - https://speechify.ai — marketing + product site
> - https://platform.speechify.ai — customer dashboard, signup, API keys, billing
> - https://api.speechify.ai — API base URL
> - https://github.com/Speechify-AI: GitHub org for the API (cookbook, demos, CLI). `github.com/speechify` does not exist.
> - https://status.speechify.ai — status + incidents
> - https://speechify.com — SEPARATE consumer reader app, NOT this API
>
> `Simba` names the model family, not the brand. Model ids: `simba-3.2` (English, recommended) and `simba-3.0` (English, German, Spanish, French, Italian and Portuguese; the default). `simba-english` and `simba-multilingual` are retired: a new workspace that sends either gets `400 model_retired`. `SimbaVoice` / `simbavoice.ai` are retired.
>
> Ask, don't scrape. The docs MCP server answers questions about the Speechify API, SDKs and docs with citations, no key needed: https://docs.speechify.ai/_mcp/server (Streamable HTTP, tool `searchDocs`). Setup: https://docs.speechify.ai/build/guides/get-started/connect-mcp

# Authentication

> Authenticate Speechify API requests with a Bearer API key. Get and rotate keys in the console, store them securely, and use a server-side proxy for frontends.

## Overview

Most API requests require a valid API key in the `Authorization` header.

```
Authorization: Bearer YOUR_API_KEY
```

Without this header, requests return `401 Unauthorized`.

## Getting an API key

Create and copy an API key in the console at [https://platform.speechify.ai/api-keys](https://platform.speechify.ai/api-keys). Key creation is console-only - there is no public key-management endpoint, so this step cannot be scripted.

> **Tip**
>
> Set the `SPEECHIFY_API_KEY` environment variable and our SDKs will authenticate automatically - no need to pass the key in code.

## Authenticate the SDK

Set `SPEECHIFY_API_KEY` and let the SDK read it automatically, or pass the key explicitly:

#### Python

```python
from speechify import Speechify

# Reads SPEECHIFY_API_KEY from the environment
client = Speechify()

# ...or pass it explicitly
client = Speechify(token="your-api-key")
```

#### TypeScript

```typescript
import { SpeechifyClient } from "@speechify/api";

// Reads SPEECHIFY_API_KEY from the environment
const client = new SpeechifyClient();

// ...or pass it explicitly
const client = new SpeechifyClient({ token: "your-api-key" });
```

## Make an authenticated request

A complete authenticated call - generated from our SDKs and the API spec, so the request (including the `Authorization` header in the cURL tab) stays in sync with the live endpoint:

### Request

GET [https://api.speechify.ai/v1/voices](https://api.speechify.ai/v1/voices)

```curl
curl -G https://api.speechify.ai/v1/voices \
     -H "Authorization: Bearer <token>" \
     -d locale=en \
     -d model=simba-3.2 \
     -d project_id=proj_01arz3ndektsv4rrffq69g5fav
```

```typescript
import { SpeechifyClient } from "@speechify/api";

async function main() {
    const client = new SpeechifyClient({
        token: "YOUR_TOKEN_HERE",
    });
    await client.voices.list({
        locale: "en",
        model: "simba-3.2",
        projectId: "proj_01arz3ndektsv4rrffq69g5fav",
    });
}
main();

```

## Security best practices

> **Warning**
>
> API keys grant full access to your account, including creating/deleting voices and generating audio at your expense. Treat them like passwords.

### Do

* Store keys in environment variables or secret managers
* Use server-side code to make API calls
* Add `.env` to your `.gitignore`
* Rotate keys periodically via the [Console](https://platform.speechify.ai/api-keys)

### Don't

* Embed keys in client-side code (JavaScript bundles, mobile apps)
* Commit keys to version control, even in private repos
* Share keys over unencrypted channels

### Platform-specific secret management

| Platform     | Documentation                                                                     |
| ------------ | --------------------------------------------------------------------------------- |
| Vercel       | [Environment Variables](https://vercel.com/docs/projects/environment-variables)   |
| Netlify      | [Environment Variables](https://docs.netlify.com/environment-variables/overview/) |
| Google Cloud | [Secret Manager](https://cloud.google.com/secret-manager/docs)                    |
| AWS          | [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/)                    |

## Server-side proxy pattern

If your frontend needs to call the API, set up a server-side proxy instead of exposing the key:

```
Client  →  Your Server (adds API key)  →  Speechify API
```

> **Warning**
>
> Always authenticate your own users before proxying requests. An open proxy allows anyone to make API calls at your expense.

Key considerations:

* Create specific proxy endpoints (not a wildcard passthrough)
* Validate and sanitize inputs before forwarding
* Add rate limiting to prevent abuse

## Error responses

| Status                  | Meaning                                                                  | Action                                                                                                                                                                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 Unauthorized`      | Missing or invalid API key                                               | Check your `Authorization` header                                                                                                                                                                                                                                                    |
| `402 Payment Required`  | Insufficient balance, or your plan doesn't include the requested feature | [Top up the balance](https://platform.speechify.ai/billing) if the response code is `payment_required`; upgrade your plan in [Billing](https://platform.speechify.ai/billing) if it is `voice_cloning_not_included`, `batch_calls_not_included`, or `purchased_numbers_not_included` |
| `403 Forbidden`         | The credential authenticated but isn't authorized for this resource      | Confirm the API key targets the right workspace and that the action allows the caller's role                                                                                                                                                                                         |
| `429 Too Many Requests` | Rate or concurrency limit exceeded                                       | Back off and retry after the `Retry-After` header value                                                                                                                                                                                                                              |

#### Deprecated: Access Tokens (JWT)

Access Tokens were previously available for client-side authentication via the `POST /v1/auth/token` endpoint. This method is now deprecated.

All applications should use API keys with a server-side proxy pattern instead. If you're currently using Access Tokens, migrate to API keys at your earliest convenience.

> Authenticate your API requests using API keys