---
title: Quickstart
description: Make your first Arabic speech request.
---

Generate Arabic speech from text using the `/v1/audio/speech` endpoint. This guide walks through authentication, selecting a voice, sending a synthesis request, saving the audio, and handling supported errors.

Set these variables once before running the examples:

```bash
export SAWTAK_API_BASE_URL="https://api.sawtakarabi.ai/v1"
export SAWTAK_API_KEY="<API_KEY>"
```

## 1. Create an API Key

Requests require a Bearer token passed in the `Authorization` header.

- For speech synthesis, your API key must include the `tts` scope.
- To query the voice catalog, your API key must include the `voices` scope.

Pass the key using the `SAWTAK_API_KEY` environment variable:

```bash
-H "Authorization: Bearer $SAWTAK_API_KEY"
```

## 2. Choose a Voice

Query the voice catalog using `GET $SAWTAK_API_BASE_URL/voices`:

```bash
curl --fail --show-error "$SAWTAK_API_BASE_URL/voices" \
  -H "Authorization: Bearer $SAWTAK_API_KEY"
```

The response returns a list envelope (`object: "list"`) containing voice objects in `data`. Each voice item includes an `id`, `name`, `status`, and `labels` (such as `dialect` and `gender`).

To use a specific voice, pass its `id` in the `voice` field of your synthesis request. If you omit the `voice` field, the endpoint uses the default voice.

## 3. Issue a Speech Request

Send a `POST` request to `$SAWTAK_API_BASE_URL/audio/speech` with the model, text input, and desired response format:

```bash
curl --fail --show-error "$SAWTAK_API_BASE_URL/audio/speech" \
  -H "Authorization: Bearer $SAWTAK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "arabic-tts-1",
    "input": "مرحبا بك",
    "response_format": "wav"
  }' \
  --output speech.wav
```

To target a specific voice from the catalog, add the `voice` property with that voice's `id`.

## 4. Play or Save the Audio

The speech endpoint streams audio bytes directly into the file specified by `--output`:

- **WAV (`response_format: "wav"`)**: The gateway prepends a standard RIFF/WAV header (`audio/wav`) to the stream. You can play it immediately with command-line tools:
  ```bash
  afplay speech.wav
  ```
  or on Linux:
  ```bash
  aplay speech.wav
  ```
- **PCM (`response_format: "pcm"`)**: The gateway streams raw 16-bit PCM audio (`audio/pcm`). Save it to `speech.pcm` when integrating with streaming decoders or pipelines that consume headerless PCM.

## 5. Supported Failure Responses

Error responses follow the OpenAI-compatible error envelope containing `message`, `type`, `code`, `param`, and `request_id`.

### Unknown Voice (`400 Bad Request`)

Supplying a voice ID that does not exist returns an `invalid_request_error` with the `bad_voice` code:

```json
{
  "error": {
    "message": "Unknown voice 'unknown-voice-id'. `voice` must be one of your voice ids from /v1/voices; omit it for the default voice.",
    "type": "invalid_request_error",
    "code": "bad_voice",
    "param": null,
    "request_id": null
  }
}
```

### Insufficient Scope (`403 Forbidden`)

Using an API key that lacks the required `tts` scope returns a `permission_error`:

```json
{
  "error": {
    "message": "Insufficient scope",
    "type": "permission_error",
    "code": "insufficient_scope",
    "param": null,
    "request_id": null
  }
}
```

### Authentication Failure (`401 Unauthorized`)

Omitting the authorization token or supplying an invalid key returns an `authentication_error`:

```json
{
  "error": {
    "message": "Authentication failed",
    "type": "authentication_error",
    "code": "auth_failed",
    "param": null,
    "request_id": null
  }
}
```