> ## 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 Reference](/api-reference) — повні схеми запиту/відповіді для кожного endpoint
* [API ключі](/platform/api-keys) — створення та використання ключів `kzl_`
* [Виставлення рахунку](/platform/billing) — кредити, плани та надбавка, яку ми застосовуємо