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

> Chiamate AI universali — chat, immagini, sintesi vocale, trascrizione, video — fatturate rispetto al tuo Space.

L'AI API di Kazzle ti offre un unico endpoint autenticato per chiamare qualsiasi modello che supportiamo. Paghi una sola volta, in crediti, rispetto al tuo Space — nessun account separato per OpenAI, Anthropic, Cloudflare Workers AI o chiunque altro instradassimo.

Tutti gli endpoint si trovano sotto `/ai/*` su `https://api.kazzle.app` e accettano una chiave API `kzl_` nell'header `Authorization`. Vedi [Chiavi API](/platform/api-keys) per sapere come crearne una.

Le app Kazzle generate dovrebbero usare questa API — vedi [AI nelle app](/apps/ai-api) per collegare la chiave a un componente. Non chiedere agli utenti le chiavi del provider a meno che non vogliano esplicitamente usare il loro account provider.

## Funzionalità

| Endpoint                        | Modalità                | Input standardizzato                              | Output standardizzato                           |
| ------------------------------- | ----------------------- | ------------------------------------------------- | ----------------------------------------------- |
| `POST /ai/chat/completions`     | Chat (testo, streaming) | `messages[]` compatibile con OpenAI               | `choices[]` compatibile con OpenAI o stream SSE |
| `POST /ai/responses`            | Responses API           | Compatibile con OpenAI Responses                  | Compatibile con OpenAI Responses                |
| `POST /ai/images/generations`   | Immagine                | `{ model, prompt, size?, output_format? }`        | `{ images: [{ url? \| b64?, mimeType }] }`      |
| `POST /ai/audio/speech`         | Sintesi vocale          | `{ model, text, voice?, format? }`                | flusso di byte `audio/*`                        |
| `POST /ai/audio/transcriptions` | Riconoscimento vocale   | `multipart/form-data` con `file` + `model`        | `{ text }`                                      |
| `POST /ai/video/generations`    | Video (asincrono)       | `{ model, prompt, ... }`                          | `{ id, status, pollUrl }`                       |
| `GET  /ai/responses/{id}`       | Poll asincrono          | id risposta                                       | risultato in formato provider                   |
| `POST /ai/gateway`              | Passthrough grezzo      | Qualsiasi payload nativo di Workers AI / provider | Risposta upstream grezza                        |
| `GET  /ai/models`               | Catalogo                | —                                                 | `{ models: [{ id, modality, pricing, ... }] }`  |

`GET /ai/models` è la fonte di verità per sapere quali id di modello funzionano su quale endpoint. Leggilo per primo se stai costruendo rispetto all'API.

## Come funziona una chiamata

Ogni chiamata fatturabile passa attraverso cinque fasi. Non vedi la maggior parte di queste — sono tracciate lato server in modo che possiamo rimborsare le chiamate fallite e segnalare l'utilizzo esatto.

| Fase       | Cosa è successo                                                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `open`     | Abbiamo creato un evento di fatturazione legato alla tua richiesta, ma non abbiamo ancora chiamato upstream.                                   |
| `recorded` | Il provider upstream ha risposto. Abbiamo un id log da Cloudflare AI Gateway. Il costo non è ancora noto.                                      |
| `priced`   | Cloudflare ha segnalato il costo finale. Abbiamo applicato il nostro markup e scritto l'addebito di credito. Terminale.                        |
| `failed`   | La chiamata upstream è fallita, oppure non abbiamo potuto ottenere un costo dopo 20 tentativi. Il cliente **non** viene addebitato. Terminale. |
| `synced`   | L'evento priced è stato consegnato al nostro sistema di misurazione.                                                                           |

Ogni risposta riuscita include `x-kazzle-ai-billing-event-id: airesp_...` — conservalo se vuoi correlare la richiesta con le esportazioni di utilizzo in seguito.

## Fatturazione e markup

Addebitiamo `cloudflare_cost_usd × (1 + markup)`. Il markup è pubblicato in [Impostazioni → Fatturazione → Prezzi](/platform/billing#pricing). Le chiamate che Cloudflare ha prezzato a \$0 (livello gratuito di Workers AI, promozioni) raggiungono la fase `priced` con costo zero e non vengono mai fatturate.

Riserva: hai bisogno di almeno **\$0,50** equivalenti in crediti per effettuare una chiamata. Trattieniamo questo rispetto al tuo saldo fino al completamento della chiamata, quindi regoliamo il costo effettivo.

## Errori

| Stato             | Significato                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `401`             | Chiave API `kzl_` mancante o non valida.                                                        |
| `402`             | Crediti insufficienti per la riserva. Ricarica in **Impostazioni → Fatturazione**.              |
| `4xx` da upstream | Inoltrato così com'è. Il corpo contiene l'errore del provider. Il cliente non viene addebitato. |
| `5xx` da upstream | Inoltrato così com'è. Il cliente non viene addebitato.                                          |

## Esempio — generazione di immagini

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

## Esempio — sintesi vocale

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

## Vedi anche

* [Riferimento API](/api-reference) — schemi completi di richiesta/risposta per ogni endpoint
* [Chiavi API](/platform/api-keys) — creazione e utilizzo di chiavi `kzl_`
* [Fatturazione](/platform/billing) — crediti, piani e il markup che applichiamo