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

> Universelle AI-Aufrufe — Chat, Bilder, Sprache, Transkription, Video — abgerechnet gegen deinen Space.

Die Kazzle AI API gibt dir einen authentifizierten Endpunkt, um jedes von uns unterstützte Modell aufzurufen. Du zahlst einmal in Credits gegen deinen Space — keine separaten Konten für OpenAI, Anthropic, Cloudflare Workers AI oder andere Anbieter, zu denen wir weiterleiten.

Alle Endpunkte befinden sich unter `/ai/*` auf `https://api.kazzle.app` und akzeptieren einen `kzl_` API-Schlüssel im `Authorization`-Header. Siehe [API-Schlüssel](/platform/api-keys), um zu erfahren, wie du einen erstellst.

Generierte Kazzle-Apps sollten diese API ebenfalls verwenden — siehe [AI in Apps](/apps/ai-api), um den Schlüssel in eine Komponente zu integrieren. Frag Nutzer nicht nach Provider-Schlüsseln, es sei denn, sie möchten explizit ihr eigenes Provider-Konto verwenden.

## Funktionen

| Endpunkt                        | Modalität              | Standardisierte Eingabe                        | Standardisierte Ausgabe                        |
| ------------------------------- | ---------------------- | ---------------------------------------------- | ---------------------------------------------- |
| `POST /ai/chat/completions`     | Chat (Text, Streaming) | OpenAI-kompatible `messages[]`                 | OpenAI-kompatible `choices[]` oder SSE-Stream  |
| `POST /ai/responses`            | Responses API          | OpenAI Responses-kompatibel                    | OpenAI Responses-kompatibel                    |
| `POST /ai/images/generations`   | Bild                   | `{ model, prompt, size?, output_format? }`     | `{ images: [{ url? \| b64?, mimeType }] }`     |
| `POST /ai/audio/speech`         | Text-zu-Sprache        | `{ model, text, voice?, format? }`             | `audio/*` Byte-Stream                          |
| `POST /ai/audio/transcriptions` | Sprache-zu-Text        | `multipart/form-data` mit `file` + `model`     | `{ text }`                                     |
| `POST /ai/video/generations`    | Video (asynchron)      | `{ model, prompt, ... }`                       | `{ id, status, pollUrl }`                      |
| `GET  /ai/responses/{id}`       | Asynchrones Abrufen    | Response-ID                                    | Provider-formatiertes Ergebnis                 |
| `POST /ai/gateway`              | Direktes Durchleiten   | Beliebige Workers AI / Provider-native Payload | Rohe Upstream-Antwort                          |
| `GET  /ai/models`               | Katalog                | —                                              | `{ models: [{ id, modality, pricing, ... }] }` |

`GET /ai/models` ist die Quelle der Wahrheit, welche Modell-IDs auf welchen Endpunkt funktionieren. Lies sie zuerst, wenn du gegen die API entwickelst.

## Wie ein Aufruf funktioniert

Jeder abrechenbare Aufruf durchläuft fünf Phasen. Du siehst die meisten davon nicht — sie werden serverseitig nachverfolgt, damit wir fehlgeschlagene Aufrufe erstatten und die genaue Nutzung melden können.

| Phase      | Was ist passiert                                                                                                                                 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `open`     | Wir haben ein Abrechnungsereignis erstellt, das an deine Anfrage gebunden ist, haben aber noch nicht den Upstream aufgerufen.                    |
| `recorded` | Der Upstream-Provider hat geantwortet. Wir haben eine Log-ID vom Cloudflare AI Gateway. Die Kosten sind noch nicht bekannt.                      |
| `priced`   | Cloudflare hat die endgültigen Kosten gemeldet. Wir haben unseren Aufschlag angewendet und die Kreditbelastung geschrieben. Terminal.            |
| `failed`   | Der Upstream-Aufruf ist fehlgeschlagen, oder wir konnten nach 20 Wiederholungen keine Kosten ermitteln. Kunde wird **nicht** belastet. Terminal. |
| `synced`   | Das Priced-Ereignis wurde an unser Messsystem übermittelt.                                                                                       |

Jede erfolgreiche Antwort enthält `x-kazzle-ai-billing-event-id: airesp_...` — behalte sie, wenn du die Anfrage später mit Nutzungsexporten korrelieren möchtest.

## Abrechnung & Aufschlag

Wir berechnen `cloudflare_cost_usd × (1 + markup)`. Der Aufschlag wird in [Einstellungen → Abrechnung → Preisgestaltung](/platform/billing#pricing) veröffentlicht. Aufrufe, die Cloudflare mit \$0 bepreist hat (kostenloser Workers AI-Tarif, Aktionen), erreichen die `priced`-Phase mit Nullkosten und werden nie abgerechnet.

Reserve: Du benötigst mindestens **\$0,50** Äquivalent in Credits, um einen Aufruf zu tätigen. Wir halten dies gegen deinen Kontostand, bis der Aufruf abgeschlossen ist, und begleichen dann die tatsächlichen Kosten.

## Fehler

| Status             | Bedeutung                                                                                       |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| `401`              | Fehlender oder ungültiger `kzl_` API-Schlüssel.                                                 |
| `402`              | Unzureichende Credits für die Reserve. Aufladen in **Einstellungen → Abrechnung**.              |
| `4xx` von Upstream | Weitergeleitet wie vorhanden. Body enthält den Fehler des Providers. Kunde wird nicht belastet. |
| `5xx` von Upstream | Weitergeleitet wie vorhanden. Kunde wird nicht belastet.                                        |

## Beispiel — Bildgenerierung

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

## Beispiel — Text zu Sprache

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

## Siehe auch

* [API-Referenz](/api-reference) — vollständige Request/Response-Schemas für jeden Endpunkt
* [API-Schlüssel](/platform/api-keys) — Erstellen und Verwenden von `kzl_` Schlüsseln
* [Abrechnung](/platform/billing) — Credits, Tarife und der Aufschlag, den wir anwenden