# Overview

Welcome to the Fluxions API. Our hosted endpoints cover three product surfaces:

- **Transcription** — `akro-v1`, our listening model: speech-to-text, speaker diarization, and non-speech events (breaths, laughter, hesitations) in one call. Production-ready today.
- **Text-to-Speech** — hosted **VUI** for expressive, low-latency TTS over HTTP or WebSocket. Live today — see [Speech](#speech).
- **Realtime Voice** — end-to-end streaming voice conversations over WebSocket or WebRTC, with your own persona and your own tools. See the [Realtime Voice API reference](https://api.fluxions.ai/vui/docs) and the [bring-your-own-tools guide](https://api.fluxions.ai/vui/docs/agent-tools-api).

This page covers the basics that apply across all surfaces: authentication, base URL, and a health check.

## Authentication

All API requests require authentication using an API key. Include your API key in the `Authorization` header:

**Bash (.sh)**
```bash
curl "https://api.fluxions.ai/endpoint" \
  -H "Authorization: YOUR_API_KEY"
```

**Python (.py)**
```python
import requests

headers = {'Authorization': 'YOUR_API_KEY'}
response = requests.get('https://api.fluxions.ai/endpoint', headers=headers)
data = response.json()
```

**JavaScript (.js)**
```javascript
const response = await fetch('https://api.fluxions.ai/endpoint', {
  headers: {'Authorization': 'YOUR_API_KEY'}
});
const data = await response.json();
```

A `Bearer ` prefix is optional — `Authorization: YOUR_API_KEY` and `Authorization: Bearer YOUR_API_KEY` authenticate identically.

## Base URL

```
https://api.fluxions.ai
```

## GET /health — Health Check

Check the API status and version information. *No authentication required.*

### Request

**Bash (.sh)**
```bash
curl "https://api.fluxions.ai/health"
```

**Python (.py)**
```python
import requests

response = requests.get('https://api.fluxions.ai/health')
data = response.json()
print(f"Status: {data['status']}, Model: {data['model']}")
```

**JavaScript (.js)**
```javascript
const response = await fetch('https://api.fluxions.ai/health');
const data = await response.json();
console.log(`Status: ${data.status}, Model: ${data.model}`);
```

### Response

```json
{
  "status": "ok",
  "gateway": "api.fluxions.ai"
}
```

## GET /billing/balance — Account Balance

Check your remaining balance and the rates you are being charged. Cheap and
read-only, so it is safe to poll — use it to top up *before* your traffic starts
failing rather than discovering the problem through a [402](#errors).

### Request

**Bash (.sh)**
```bash
curl "https://api.fluxions.ai/billing/balance" \
  -H "Authorization: YOUR_API_KEY"
```

**Python (.py)**
```python
import requests

r = requests.get(
    'https://api.fluxions.ai/billing/balance',
    headers={'Authorization': 'YOUR_API_KEY'},
)
b = r.json()
if b['gated']:
    raise RuntimeError(f"out of credit (${b['balance_usd']:.2f}) — top up")
```

**JavaScript (.js)**
```javascript
const r = await fetch('https://api.fluxions.ai/billing/balance', {
  headers: {'Authorization': 'YOUR_API_KEY'}
});
const b = await r.json();
if (b.gated) throw new Error(`out of credit ($${b.balance_usd.toFixed(2)})`);
```

### Response

```json
{
  "balance_usd": 44.68,
  "balance_microcents": 4468381000,
  "gated": false,
  "plan": null,
  "rates": {
    "tts_per_mchar_usd": 10.0,
    "transcription_per_hour_usd": 0.20,
    "transcription_minimum_usd": 0.01
  }
}
```

| Field | Description |
|-------|-------------|
| `balance_usd` | Remaining balance in dollars |
| `balance_microcents` | The same balance, exact. Money is stored in microcents (1 cent = 10<sup>6</sup>); use this field if you need to avoid float rounding |
| `gated` | `true` when your next billable request will be refused with a 402. Poll this |
| `plan` | Your subscription plan key, or `null` for pay-as-you-go. Subscribers are governed by their plan allowance rather than the wallet, so they are never `gated` here |
| `rates` | What you are charged. `transcription_minimum_usd` is a per-request floor — see [Transcription](#transcription) |

Balances are live: renders are debited as they happen, so the number here
reflects usage up to the moment you asked.