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

> Universele AI-aanroepen — chat, afbeeldingen, spraak, transcriptie, video — gefactureerd tegen uw space.

De Kazzle AI API geeft u één geverifieerd eindpunt om elk model dat we ondersteunen aan te roepen. U betaalt eenmaal, in credits, tegen uw space — geen aparte accounts voor OpenAI, Anthropic, Cloudflare Workers AI of iemand anders naar wie we routeren.

Alle eindpunten bevinden zich onder `/ai/*` op `https://api.kazzle.app` en accepteren een `kzl_` API-sleutel in de `Authorization`-header. Zie [API-sleutels](/platform/api-keys) voor instructies over het maken van een sleutel.

Gegenereerde Kazzle-apps moeten deze API ook gebruiken — zie [AI in apps](/apps/ai-api) voor het verbinden van de sleutel met een component. Vraag gebruikers niet om provider-sleutels tenzij zij expliciet hun eigen provider-account willen gebruiken.

## Mogelijkheden

| Eindpunt                        | Modaliteit              | Gestandaardiseerde invoer                  | Gestandaardiseerde uitvoer                     |
| ------------------------------- | ----------------------- | ------------------------------------------ | ---------------------------------------------- |
| `POST /ai/chat/completions`     | Chat (tekst, streaming) | OpenAI-compatibele `messages[]`            | OpenAI-compatibele `choices[]` of SSE-stream   |
| `POST /ai/responses`            | Responses API           | OpenAI Responses-compatibel                | OpenAI Responses-compatibel                    |
| `POST /ai/images/generations`   | Afbeelding              | `{ model, prompt, size?, output_format? }` | `{ images: [{ url? \| b64?, mimeType }] }`     |
| `POST /ai/audio/speech`         | Tekst-naar-spraak       | `{ model, text, voice?, format? }`         | `audio/*` bytestream                           |
| `POST /ai/audio/transcriptions` | Spraak-naar-tekst       | `multipart/form-data` met `file` + `model` | `{ text }`                                     |
| `POST /ai/video/generations`    | Video (asynchroon)      | `{ model, prompt, ... }`                   | `{ id, status, pollUrl }`                      |
| `GET  /ai/responses/{id}`       | Asynchroon polling      | response-id                                | provider-gevormd resultaat                     |
| `POST /ai/gateway`              | Raw passthrough         | Elke Workers AI / provider-native payload  | Raw upstream-respons                           |
| `GET  /ai/models`               | Catalogus               | —                                          | `{ models: [{ id, modality, pricing, ... }] }` |

`GET /ai/models` is de bron van waarheid voor welke model-id's op welk eindpunt werken. Lees dit eerst als u tegen de API bouwt.

## Hoe een aanroep werkt

Elke factureerbare aanroep gaat door vijf fasen. U ziet de meeste hiervan niet — ze worden server-side bijgehouden zodat we mislukte aanroepen kunnen terugbetalen en exact gebruik kunnen rapporteren.

| Fase       | Wat is er gebeurd                                                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `open`     | We hebben een factureringsgebeurtenis gemaakt die aan uw verzoek is gekoppeld, maar hebben nog niet upstream aangeroepen.          |
| `recorded` | De upstream-provider heeft geantwoord. We hebben een log-id van Cloudflare AI Gateway. De kosten zijn nog niet bekend.             |
| `priced`   | Cloudflare heeft de uiteindelijke kosten gerapporteerd. We hebben onze opslag toegepast en de creditcharge geschreven. Definitief. |
| `failed`   | De upstream-aanroep is mislukt, of we konden na 20 pogingen geen kosten ophalen. Klant wordt **niet** gefactureerd. Definitief.    |
| `synced`   | De priced-gebeurtenis is aan ons metersysteem bezorgd.                                                                             |

Elke succesvolle respons bevat `x-kazzle-ai-billing-event-id: airesp_...` — bewaar dit als u het verzoek later met gebruiksexports wilt correleren.

## Facturering & opslag

We berekenen `cloudflare_cost_usd × (1 + markup)`. De opslag wordt gepubliceerd in [Instellingen → Facturering → Prijzen](/platform/billing#pricing). Aanroepen die Cloudflare op \$0 heeft geprijsd (gratis Workers AI-laag, promoties) bereiken de `priced`-fase met nulkosten en worden nooit gefactureerd.

Reserve: u hebt minstens **\$0,50** equivalent in credits nodig om een aanroep te doen. We houden dit tegen uw saldo totdat de aanroep is voltooid, en vereffenen vervolgens de werkelijke kosten.

## Fouten

| Status             | Betekenis                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------- |
| `401`              | Ontbrekende of ongeldige `kzl_` API-sleutel.                                                  |
| `402`              | Onvoldoende credits voor de reserve. Vul bij in **Instellingen → Facturering**.               |
| `4xx` van upstream | Doorgestuurd zoals het is. Body bevat de fout van de provider. Klant wordt niet gefactureerd. |
| `5xx` van upstream | Doorgestuurd zoals het is. Klant wordt niet gefactureerd.                                     |

## Voorbeeld — afbeeldingsgeneratie

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

## Voorbeeld — tekst naar spraak

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

## Zie ook

* [API-referentie](/api-reference) — volledige request/response-schema's voor elk eindpunt
* [API-sleutels](/platform/api-keys) — maken en gebruiken van `kzl_`-sleutels
* [Facturering](/platform/billing) — credits, plannen en de opslag die we toepassen