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

# Overview

> Base URL, auth, conventions, and errors for the geko HTTP API.

geko is a plain JSON + `audio/wav` API — call it from any language. Each endpoint has its own page with request/response schemas and a **Try it** playground you can run right here in the docs (the catalog endpoints work without a key).

**Base URL**

```
https://geko--tokay-serve-web.modal.run
```

## Authentication

`POST /v1/tts`, `POST /v1/tts/stream`, and `POST /v1/audio/speech` require a bearer token:

```
Authorization: Bearer sk-tokay-...
```

The `GET` catalog endpoints (`/v1/models`, `/v1/voices`, `/health`) are **open** — no key — so docs, playgrounds, and voice pickers render without one. Create keys in the [console](https://app.geko.sh); see [Authentication](/authentication) for handling them safely.

## Conventions

* **Audio out.** Synthesis returns raw **WAV** — `audio/wav`, 24 kHz, 16-bit PCM, mono. The `X-Tokay-Chars` response header reports the billed character count.
* **JSON in.** Send `Content-Type: application/json`.
* **Streaming.** `POST /v1/tts/stream` returns `application/octet-stream` framed as `wav-frames-v1`: a 4-byte big-endian length, then that many bytes of one complete WAV, repeated. See the [streaming guide](/guides/streaming).
* **OpenAI-compatible.** `POST /v1/audio/speech` accepts OpenAI's request shape — see [OpenAI compatibility](/guides/openai).

## Endpoints

<CardGroup cols={2}>
  <Card title="POST /v1/tts" icon="waveform-lines" href="/api-reference/speech/synthesize-speech">
    Synthesize text → WAV.
  </Card>

  <Card title="POST /v1/tts/stream" icon="bolt" href="/api-reference/speech/stream-speech-sentence-by-sentence">
    Sentence-by-sentence streaming.
  </Card>

  <Card title="POST /v1/audio/speech" icon="plug" href="/api-reference/speech/openai-compatible-speech">
    OpenAI-compatible alias.
  </Card>

  <Card title="GET /v1/voices" icon="list" href="/api-reference/catalog/list-voices">
    The voice catalog (open).
  </Card>
</CardGroup>

## Errors

Errors come back as JSON with a `detail` string and the matching HTTP status:

```json theme={null}
{ "detail": "out of credits — top up in the geko console" }
```

| Status | Meaning                                                            | Retried? |
| ------ | ------------------------------------------------------------------ | -------- |
| `400`  | Bad request — missing `text`, malformed body, or an invalid value. | No       |
| `401`  | Missing or invalid API key.                                        | No       |
| `404`  | Unknown model or voice.                                            | No       |
| `429`  | Out of credits — top up in the console.                            | No       |
| `503`  | Auth backend temporarily unavailable (transient).                  | Yes      |

See [Errors & retries](/sdk/errors) for the SDK's error types and retry behavior.