# Overview

> What the API does — speech, transcription, voices, images, video, skyboxes, templates and agents — and where to start.

One HTTP API for speech, conversation and generative media. You call it from your own server with an API key, and your users' apps talk to your agents with a short-lived key you mint for them.

```bash title="curl"
curl https://api.lumavox.ai/v1/tts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from the API."}' \
  --output hello.wav
```

New here? The [quickstart](https://docs.lumavox.ai/quickstart.md) takes you from a key to your first audio file and your first image.

## What you can do

Every capability answers in one of three shapes:

- **In the response**: the result is the response body (or a stream of it).
- **Queued**: the request answers `202` with a `gen_…` id straight away, and you poll until it finishes. See [queued jobs](https://docs.lumavox.ai/jobs.md).
- **WebSocket**: an agent's conversation, spoken and written as it is generated.

| Capability | Endpoints | Shape |
|---|---|---|
| [Text to speech](https://docs.lumavox.ai/speech/text-to-speech.md) | `POST /v1/tts` | audio in the response, or streamed as it is generated |
| [Stored audio](https://docs.lumavox.ai/speech/stored-audio.md) | `POST /v1/audio` | queued — mp3, opus or wav, kept in your library |
| [Transcription](https://docs.lumavox.ai/speech/transcription.md) | `POST /v1/stt`, `POST /v1/transcriptions` | text in the response for short audio; queued for long recordings |
| [Voices](https://docs.lumavox.ai/speech/voices.md) | `/v1/voices` | list the voices you may use; upload or design your own |
| [Images](https://docs.lumavox.ai/media/images.md) | `POST /v1/images` | queued |
| [Video](https://docs.lumavox.ai/media/videos.md) | `POST /v1/videos` | queued |
| [Skyboxes](https://docs.lumavox.ai/media/skyboxes.md) | `POST /v1/skybox` | queued — a 360° environment |
| [Templates](https://docs.lumavox.ai/media/templates.md) | `POST /v1/templates/{template_id}/generate` | queued — a generation someone already designed |
| [Agents](https://docs.lumavox.ai/agents.md) | `/v1/agents`, `/v1/knowledge` | authored over HTTP |
| [Conversations](https://docs.lumavox.ai/agents/conversations.md) | `POST /v1/agent/sessions`, then [the WebSocket](https://docs.lumavox.ai/agents/websocket.md) | streamed text and speech |
| [Library](https://docs.lumavox.ai/library/assets.md) | `/v1/assets`, `/v1/generations` | everything you generated or uploaded |
| [Credits and usage](https://docs.lumavox.ai/usage.md) | `GET /v1/plan`, `GET /v1/usage` | your balance and what you spent |

## Three kinds of credential

| Credential | Who holds it | What it reaches |
|---|---|---|
| **API key** | your server | every endpoint its scopes allow — never the conversation routes |
| **Ephemeral key** | one end user's browser or app | that end user's conversations with your agents, up to a credit limit, until it expires |
| **Console sign-in** | the people on your team | the console at https://app.lumavox.ai, where you create keys, agents and voices |

API keys are created in the console and stay on your server. Ephemeral keys are minted by your server, one end user at a time. Read [authentication](https://docs.lumavox.ai/authentication.md) before you ship.

## How these docs are built

- **Every page is also plain Markdown**: add `.md` to any page's address.
- **For AI agents**: start at [`/llms.txt`](https://docs.lumavox.ai/llms.txt), the index of every page with a line on each, or read [docs for AI agents](https://docs.lumavox.ai/ai.md).
- **The full contract** is the OpenAPI document at `https://api.lumavox.ai/openapi.json`, rendered in the [API reference](https://docs.lumavox.ai/reference.md). From TypeScript, the [SDKs](https://docs.lumavox.ai/sdks/server.md) are typed from it; from any other language, generate a client from it.

## Where to go next

- [Quickstart](https://docs.lumavox.ai/quickstart.md) — your first request in a few minutes.
- [Authentication](https://docs.lumavox.ai/authentication.md) — keys, scopes and ephemeral keys.
- [Conventions](https://docs.lumavox.ai/conventions.md) — how every endpoint writes times, credits and lists.
- [Errors and limits](https://docs.lumavox.ai/errors.md) — what each status code means and what to do about it.
- [Queued jobs](https://docs.lumavox.ai/jobs.md) — how `202` and polling work, and when you are charged.
- [Agents](https://docs.lumavox.ai/agents.md) — characters that hold a spoken conversation.