# Обзор

Что умеет API, адрес, формат и первый запрос за минуту.

API «Голосарь Книги» — это те же действия, что в кабинете, только для вашего сервера: загрузить книгу, узнать цену, озвучить
главы нашими голосами, забрать готовую аудиокнигу или озвучить короткий текст одним запросом. Знаки списываются с вашего
баланса — так же, как при работе в кабинете.

## Адрес и формат

- Все запросы — на `https://golosar-kniga.tech/api/v1`.
- Запросы и ответы — JSON в UTF-8 (кроме загрузки файла и звука `/tts`).
- Время — ISO 8601 в UTC: `2026-10-13T10:31:07+00:00`.
- Идентификаторы — строки UUID.
- Ссылки на файлы (`audio_url`, `download_url`) живут час; повторный запрос даёт свежую.

## Первый запрос

1. Создайте ключ в кабинете: **Аккаунт → API → Новый ключ** (нужен пакет «Студия»).
2. Сохраните его в переменной окружения `GOLOSAR_KEY` (в примерах curl — `KEY`).
3. Спросите, кто вы и сколько знаков на балансе:

```bash
curl "https://golosar-kniga.tech/api/v1/api/me" \
  -H "x-api-key: $KEY"
```

```python
import os, requests

API = "https://golosar-kniga.tech/api/v1"
H = {"x-api-key": os.environ["GOLOSAR_KEY"]}

r = requests.get(f"{API}/api/me", headers=H)
r.raise_for_status()
print(r.json())
```

```javascript
const API = "https://golosar-kniga.tech/api/v1";
const H = { "x-api-key": process.env.GOLOSAR_KEY };

const r = await fetch(`${API}/api/me`, { headers: H });
if (!r.ok) throw new Error(await r.text());
console.log(await r.json());
```

```json Ответ 200
{
  "user": {
    "email": "you@example.com",
    "name": "Иван"
  },
  "balance": 1834512.5,
  "unlimited": false,
  "api_allowed": true,
  "weights": {
    "local": 0.1,
    "own": 1.0,
    "cloud": 3.0
  },
  "key": {
    "name": "мой сервис",
    "prefix": "gk_live_zRgV",
    "scope": "full",
    "char_limit": null,
    "used": 15488.0,
    "left": null,
    "rate_per_minute": 120
  }
}
```

## Как устроено

| Что | Где |
|---|---|
| Книга → главы → строки → кусок звука | [Книги](/developers/books-create), [Главы и строки](/developers/chapter-get) |
| Герои книги и их голоса | [Голоса](/developers/voices), [Голос герою](/developers/character-patch) |
| Долгая работа — задача | [Задачи и файлы](/developers/job-get), [Уведомления](/developers/webhooks) |
| Короткий текст сразу | [Озвучить текст](/developers/tts) |

Полное машинное описание всех запросов (OpenAPI): [/api/openapi.json](/api/openapi.json).