> ## 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

> Uniwersalne wywołania AI — czat, obrazy, mowa, transkrypcja, wideo — rozliczane względem Twojej przestrzeni.

Kazzle AI API daje Ci jeden uwierzytelniony endpoint do wywołania dowolnego modelu, który obsługujemy. Płacisz raz, w kredytach, względem Twojej przestrzeni — bez oddzielnych kont dla OpenAI, Anthropic, Cloudflare Workers AI ani nikogo innego, do którego nas kierujemy.

Wszystkie endpointy znajdują się pod `/ai/*` na `https://api.kazzle.app` i akceptują klucz API `kzl_` w nagłówku `Authorization`. Aby dowiedzieć się, jak go utworzyć, zobacz [Klucze API](/platform/api-keys).

Wygenerowane aplikacje Kazzle powinny również używać tego API — zobacz [AI w aplikacjach](/apps/ai-api), aby podłączyć klucz do komponentu. Nie pytaj użytkowników o klucze dostawcy, chyba że wyraźnie chcą używać własnego konta dostawcy.

## Możliwości

| Endpoint                        | Modalność                 | Standardowe wejście                           | Standardowe wyjście                                |
| ------------------------------- | ------------------------- | --------------------------------------------- | -------------------------------------------------- |
| `POST /ai/chat/completions`     | Czat (tekst, streaming)   | Kompatybilne z OpenAI `messages[]`            | Kompatybilne z OpenAI `choices[]` lub strumień SSE |
| `POST /ai/responses`            | Responses API             | Kompatybilne z OpenAI Responses               | Kompatybilne z OpenAI Responses                    |
| `POST /ai/images/generations`   | Obraz                     | `{ model, prompt, size?, output_format? }`    | `{ images: [{ url? \| b64?, mimeType }] }`         |
| `POST /ai/audio/speech`         | Synteza mowy              | `{ model, text, voice?, format? }`            | strumień bajtów `audio/*`                          |
| `POST /ai/audio/transcriptions` | Transkrypcja mowy         | `multipart/form-data` z `file` + `model`      | `{ text }`                                         |
| `POST /ai/video/generations`    | Wideo (asynchroniczne)    | `{ model, prompt, ... }`                      | `{ id, status, pollUrl }`                          |
| `GET  /ai/responses/{id}`       | Asynchroniczne pobieranie | id odpowiedzi                                 | wynik w kształcie dostawcy                         |
| `POST /ai/gateway`              | Bezpośrednie przekazanie  | Dowolny Workers AI / natywny payload dostawcy | Surowa odpowiedź upstream                          |
| `GET  /ai/models`               | Katalog                   | —                                             | `{ models: [{ id, modality, pricing, ... }] }`     |

`GET /ai/models` jest źródłem prawdy dla tego, które identyfikatory modeli działają na którym endpoincie. Przeczytaj go najpierw, jeśli budujesz względem API.

## Jak działa wywołanie

Każde rozliczane wywołanie przechodzi przez pięć faz. Większości z nich nie widzisz — są śledzone po stronie serwera, abyśmy mogli zwrócić pieniądze za nieudane wywołania i zgłosić dokładne użycie.

| Faza       | Co się stało                                                                                                                 |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `open`     | Utworzyliśmy zdarzenie rozliczeniowe powiązane z Twoim żądaniem, ale jeszcze nie wywołaliśmy upstream.                       |
| `recorded` | Dostawca upstream zwrócił wynik. Mamy identyfikator dziennika z Cloudflare AI Gateway. Koszt nie jest jeszcze znany.         |
| `priced`   | Cloudflare zgłosił ostateczny koszt. Zastosowaliśmy nasz narzut i zapisaliśmy opłatę kredytową. Terminal.                    |
| `failed`   | Wywołanie upstream nie powiodło się lub nie mogliśmy uzyskać kosztu po 20 próbach. Klient **nie** jest rozliczany. Terminal. |
| `synced`   | Zdarzenie wycenione zostało dostarczone do naszego systemu pomiaru.                                                          |

Każda pomyślna odpowiedź zawiera `x-kazzle-ai-billing-event-id: airesp_...` — zachowaj ją, jeśli chcesz później skorelować żądanie z eksportami użycia.

## Rozliczenia i narzut

Pobieramy `cloudflare_cost_usd × (1 + markup)`. Narzut jest publikowany w [Ustawienia → Rozliczenia → Ceny](/platform/billing#pricing). Wywołania, które Cloudflare wycenił na \$0 (bezpłatna warstwa Workers AI, promocje) osiągają fazę `priced` z zerowym kosztem i nigdy nie są rozliczane.

Rezerwa: musisz mieć co najmniej **\$0.50** równowartości w kredytach, aby wykonać wywołanie. Zatrzymujemy to względem Twojego salda, aż wywołanie się zakończy, a następnie rozliczamy rzeczywisty koszt.

## Błędy

| Status           | Znaczenie                                                                      |
| ---------------- | ------------------------------------------------------------------------------ |
| `401`            | Brakujący lub nieprawidłowy klucz API `kzl_`.                                  |
| `402`            | Niewystarczające kredyty na rezerwę. Doładuj w **Ustawienia → Rozliczenia**.   |
| `4xx` z upstream | Przekazane bez zmian. Treść zawiera błąd dostawcy. Klient nie jest rozliczany. |
| `5xx` z upstream | Przekazane bez zmian. Klient nie jest rozliczany.                              |

## Przykład — generowanie obrazu

```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" }
  ]
}
```

## Przykład — synteza mowy

```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
```

## Zobacz też

* [Dokumentacja API](/api-reference) — pełne schematy żądań/odpowiedzi dla każdego endpointu
* [Klucze API](/platform/api-keys) — tworzenie i używanie kluczy `kzl_`
* [Rozliczenia](/platform/billing) — kredyty, plany i narzut, który stosujemy