Vai al contenuto principale
L’API AI di Kazzle ti offre un endpoint autenticato per chiamare qualsiasi modello supportato. Paghi una sola volta, in crediti, rispetto al tuo spazio — nessun account separato per OpenAI, Anthropic, Cloudflare Workers AI o altri provider a cui inoltriamo le richieste. 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. Crea una chiave API Kazzle per l’app, salvala nel vault, configurala come KAZZLE_API_KEY su un componente process, e chiama https://api.kazzle.app/ai/* dal codice lato server. Non chiedere agli utenti le chiavi del provider a meno che non vogliano esplicitamente usare il loro account provider.

​
Funzionalità

EndpointModalitàInput standardizzatoOutput standardizzato
POST /ai/chat/completionsChat (testo, streaming)messages[] compatibile con OpenAIchoices[] compatibile con OpenAI o stream SSE
POST /ai/responsesResponses APICompatibile con OpenAI ResponsesCompatibile con OpenAI Responses
POST /ai/images/generationsImmagine{ model, prompt, size?, output_format? }{ images: [{ url? | b64?, mimeType }] }
POST /ai/audio/speechSintesi vocale{ model, text, voice?, format? }stream di byte audio/*
POST /ai/audio/transcriptionsTrascrizione vocalemultipart/form-data con file + model{ text }
POST /ai/video/generationsVideo (asincrono){ model, prompt, ... }{ id, status, pollUrl }
GET /ai/responses/{id}Poll asincronoid rispostarisultato in formato provider
POST /ai/gatewayPassthrough grezzoQualsiasi payload Workers AI / nativo del providerRisposta upstream grezza
GET /ai/modelsCatalogo—{ models: [{ id, modality, pricing, ... }] }
GET /ai/models è la fonte di verità per quali id di modello funzionano su quale endpoint. Leggilo per primo se stai sviluppando 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.
FaseCosa è successo
openAbbiamo creato un evento di fatturazione legato alla tua richiesta, ma non abbiamo ancora chiamato upstream.
recordedIl provider upstream ha risposto. Abbiamo un id log da Cloudflare AI Gateway. Il costo non è ancora noto.
pricedCloudflare ha segnalato il costo finale. Abbiamo applicato il nostro markup e scritto l’addebito di crediti. Terminale.
failedLa chiamata upstream è fallita, oppure non abbiamo potuto ottenere un costo dopo 20 tentativi. Il cliente non viene addebitato. Terminale.
syncedL’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 gli export di utilizzo in seguito.

​
Fatturazione e markup

Addebitiamo cloudflare_cost_usd × (1 + markup). Il markup è pubblicato in Impostazioni → Fatturazione → Tariffe. Le chiamate che Cloudflare ha prezzato a $0 (tier gratuito 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 importo rispetto al tuo saldo fino al completamento della chiamata, quindi saldiamo il costo effettivo.

​
Errori

StatoSignificato
401Chiave API kzl_ mancante o non valida.
402Crediti insufficienti per la riserva. Ricarica in Impostazioni → Fatturazione.
4xx da upstreamInoltrato così com’è. Il corpo contiene l’errore del provider. Il cliente non viene addebitato.
5xx da upstreamInoltrato 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 markup che applichiamo