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

# Audio and email

> Transcribe audio, generate speech, and send tenant-scoped email.

Use these endpoints when you need speech input, speech output, or transactional email from the gateway.

## WebSocket `/v1/listen`

Use this endpoint for live streaming speech-to-text.

**Auth:** required (`Authorization: Bearer bos_live_sk_...`)

Proxy to Deepgram's live streaming STT. Connect to the gateway with your Basics API key; the gateway handles the upstream connection and keeps provider credentials server-side.

**URL:** `wss://api.basicsos.com/v1/listen?model=nova-2&diarize=true&...`

Use the same query params as [Deepgram's Listen API](https://developers.deepgram.com/docs/listen).

* **Client → gateway:** send binary audio frames
* **Gateway → client:** receive Deepgram JSON transcript results
* When either side closes the connection, the other is closed as well

## POST `/v1/audio/transcriptions`

Convert speech to text.

**Auth:** required

This endpoint supports two input modes, so you can work with browser uploads or direct JSON payloads.

### Multipart form-data

Recommended for browser uploads.

| Field | Required | Notes |
| - | - | - |
| `file` | Yes | Audio file from a browser upload or local file |
| `model` | No | Defaults to `basics-stt` |

```ts theme={null}
const form = new FormData();
form.append("file", file);
form.append("model", "basics-stt");

const res = await fetch(`${BASE_URL}/v1/audio/transcriptions`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
  body: form
});
```

### JSON with base64 audio

```json theme={null}
{
  "model": "basics-stt",
  "audio": "<base64-audio>",
  "mime_type": "audio/wav"
}
```

### JSON fields

| Field | Type | Required | Notes |
| - | - | - | - |
| `model` | string | No | Defaults to `basics-stt` |
| `audio` | string | Yes | Base64-encoded audio |
| `mime_type` | string | No | Defaults to `audio/wav` |

### Response

Returns provider-specific transcription JSON from Deepgram.

## POST `/v1/audio/speech`

Convert text to speech.

**Auth:** required

### Request body

```json theme={null}
{
  "model": "basics-tts",
  "input": "Hello from Basics.",
  "voice": "default",
  "encoding": "mp3"
}
```

### Response

Returns a binary audio body.

Common response headers:

* `Content-Type`: provider audio type such as `audio/mpeg`
* `x-request-id`: internal request ID

```ts theme={null}
const res = await fetch(`${BASE_URL}/v1/audio/speech`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "basics-tts",
    input: "Hello from Basics."
  })
});

const blob = await res.blob();
const url = URL.createObjectURL(blob);
```

## POST `/v1/email/send`

Send a simple tenant-scoped text email through Basics.

**Auth:** required. BYOK is not supported.

### Request body

```json theme={null}
{
  "to": "user@example.com",
  "subject": "Welcome to Basics",
  "content": "Thanks for signing up!"
}
```

### Request fields

| Field | Type | Required | Notes |
| - | - | - | - |
| `to` | email string | Yes | Recipient address |
| `subject` | string | Yes | Tenant company may be appended |
| `content` | string | Yes | Plain text body |

### Success response

```json theme={null}
{
  "id": "email_123456",
  "ok": true
}
```

### Common errors

* `503` with `code: "service_unavailable"` when email is not configured
* `422` with `code: "invalid_payload"` for validation errors
* `4xx` or `5xx` with `code: "email_send_failed"` if the Resend call fails


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.