AI API

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 per sapere come crearne una. Le app Kazzle generate dovrebbero usare questa API — vedi AI nelle app 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. 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

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"
  }'

{
  "images": [
    { "url": "https://...", "mimeType": "image/png" }
  ]
}

Esempio — sintesi vocale

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 — schemi completi di richiesta/risposta per ogni endpoint
Chiavi API — creazione e utilizzo di chiavi kzl_
Fatturazione — crediti, piani e il markup che applichiamo

Informazioni su Kazzle

Lavoro

Navigazione

Codice

App

Sicurezza

Piattaforma

Funzionalità

Come funziona una chiamata

Fatturazione e markup

Errori

Esempio — generazione di immagini

Esempio — sintesi vocale

Vedi anche

​Funzionalità

​Come funziona una chiamata

​Fatturazione e markup

​Errori

​Esempio — generazione di immagini

​Esempio — sintesi vocale

​Vedi anche

Funzionalità

Come funziona una chiamata

Fatturazione e markup

Errori

Esempio — generazione di immagini

Esempio — sintesi vocale

Vedi anche