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

# AI API

> Универсальные вызовы AI — чат, изображения, речь, транскрипция, видео — оплачиваются из кредитов вашего пространства.

Kazzle AI API предоставляет один аутентифицированный endpoint для вызова любой поддерживаемой модели. Вы платите один раз кредитами из своего пространства — без отдельных аккаунтов OpenAI, Anthropic, Cloudflare Workers AI или других провайдеров, к которым мы маршрутизируем запросы.

Все endpoints находятся под `/ai/*` на `https://api.kazzle.app` и принимают API-ключ `kzl_` в заголовке `Authorization`. Инструкции по созданию ключа см. в разделе [API-ключи](/platform/api-keys).

Созданные приложения Kazzle должны использовать этот API — см. [AI в приложениях](/apps/ai-api) для подключения ключа к компоненту. Не просите пользователей предоставлять ключи провайдеров, если они явно не хотят использовать свой аккаунт провайдера.

## Возможности

| Endpoint                        | Модальность                     | Стандартизированный ввод                       | Стандартизированный вывод                      |
| ------------------------------- | ------------------------------- | ---------------------------------------------- | ---------------------------------------------- |
| `POST /ai/chat/completions`     | Чат (текст, потоковая передача) | Совместимый с OpenAI `messages[]`              | Совместимый с OpenAI `choices[]` или SSE-поток |
| `POST /ai/responses`            | Responses API                   | Совместимый с OpenAI Responses                 | Совместимый с OpenAI Responses                 |
| `POST /ai/images/generations`   | Изображение                     | `{ model, prompt, size?, output_format? }`     | `{ images: [{ url? \| b64?, mimeType }] }`     |
| `POST /ai/audio/speech`         | Синтез речи                     | `{ model, text, voice?, format? }`             | `audio/*` поток байтов                         |
| `POST /ai/audio/transcriptions` | Распознавание речи              | `multipart/form-data` с `file` + `model`       | `{ text }`                                     |
| `POST /ai/video/generations`    | Видео (асинхронно)              | `{ model, prompt, ... }`                       | `{ id, status, pollUrl }`                      |
| `GET  /ai/responses/{id}`       | Асинхронный опрос               | id ответа                                      | результат в формате провайдера                 |
| `POST /ai/gateway`              | Прямой проход                   | Любой Workers AI / нативный payload провайдера | Прямой ответ от upstream                       |
| `GET  /ai/models`               | Каталог                         | —                                              | `{ models: [{ id, modality, pricing, ... }] }` |

`GET /ai/models` — источник истины для определения, какие id моделей работают на каком endpoint. Прочитайте его в первую очередь, если разрабатываете против API.

## Как работает вызов

Каждый оплачиваемый вызов проходит пять фаз. Вы не видите большинство из них — они отслеживаются на сервере, чтобы мы могли возвращать средства за неудачные вызовы и сообщать точное использование.

| Фаза       | Что произошло                                                                                                                              |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `open`     | Мы создали событие биллинга, привязанное к вашему запросу, но еще не вызвали upstream.                                                     |
| `recorded` | Upstream-провайдер ответил. У нас есть id логирования от Cloudflare AI Gateway. Стоимость еще не известна.                                 |
| `priced`   | Cloudflare сообщил финальную стоимость. Мы применили наш коэффициент и записали списание кредитов. Финальное состояние.                    |
| `failed`   | Upstream-вызов не удался, или мы не смогли получить стоимость после 20 повторных попыток. Клиент **не** оплачивается. Финальное состояние. |
| `synced`   | Событие с установленной ценой доставлено в нашу систему учета.                                                                             |

Каждый успешный ответ включает `x-kazzle-ai-billing-event-id: airesp_...` — сохраните его, если хотите позже сопоставить запрос с экспортом использования.

## Биллинг и коэффициент

Мы взимаем `cloudflare_cost_usd × (1 + markup)`. Коэффициент опубликован в [Параметры → Биллинг → Тарифы](/platform/billing#pricing). Вызовы, оцененные Cloudflare в \$0 (бесплатный уровень Workers AI, промо), достигают фазы `priced` с нулевой стоимостью и никогда не оплачиваются.

Резерв: вам нужно иметь как минимум **\$0.50** эквивалента в кредитах для выполнения вызова. Мы удерживаем это против вашего баланса до завершения вызова, затем рассчитываем фактическую стоимость.

## Ошибки

| Статус            | Значение                                                                          |
| ----------------- | --------------------------------------------------------------------------------- |
| `401`             | Отсутствует или неверный API-ключ `kzl_`.                                         |
| `402`             | Недостаточно кредитов для резерва. Пополните в **Параметры → Биллинг**.           |
| `4xx` от upstream | Перенаправлено как есть. Тело содержит ошибку провайдера. Клиент не оплачивается. |
| `5xx` от upstream | Перенаправлено как есть. Клиент не оплачивается.                                  |

## Пример — генерация изображения

```bash theme={"theme":"material-theme-darker"}
curl https://api.kazzle.app/ai/images/generations \
  -H "Authorization: Bearer kzl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-1",
    "prompt": "a single red dot on white",
    "size": "1024x1024"
  }'
```

```json theme={"theme":"material-theme-darker"}
{
  "images": [
    { "url": "https://...", "mimeType": "image/png" }
  ]
}
```

## Пример — синтез речи

```bash theme={"theme":"material-theme-darker"}
curl https://api.kazzle.app/ai/audio/speech \
  -H "Authorization: Bearer kzl_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/tts-1","text":"hello world","voice":"alloy","format":"mp3"}' \
  --output speech.mp3
```

## См. также

* [Справочник API](/api-reference) — полные схемы запросов/ответов для каждого endpoint
* [API-ключи](/platform/api-keys) — создание и использование ключей `kzl_`
* [Биллинг](/platform/billing) — кредиты, планы и коэффициент, который мы применяем