Saltar para o conteúdo principal
A API de IA do Kazzle oferece um único endpoint autenticado para chamar qualquer modelo que suportamos. Você paga uma vez, em créditos, contra seu espaço — sem contas separadas para OpenAI, Anthropic, Cloudflare Workers AI ou qualquer outro para o qual roteamos. Todos os endpoints ficam em /ai/* em https://api.kazzle.app e aceitam uma chave de API kzl_ no header Authorization. Veja Chaves de API para saber como criar uma. Apps Kazzle gerados também devem usar esta API. Crie uma chave de API Kazzle para o app, armazene-a no vault, configure-a como KAZZLE_API_KEY em um componente de processo e chame https://api.kazzle.app/ai/* a partir desse código do lado do servidor. Não peça chaves de provedor aos usuários a menos que eles explicitamente queiram usar sua própria conta de provedor.

​
Capacidades

EndpointModalidadeEntrada padronizadaSaída padronizada
POST /ai/chat/completionsChat (texto, streaming)messages[] compatível com OpenAIchoices[] compatível com OpenAI ou stream SSE
POST /ai/responsesAPI de RespostasCompatível com Respostas OpenAICompatível com Respostas OpenAI
POST /ai/images/generationsImagem{ model, prompt, size?, output_format? }{ images: [{ url? | b64?, mimeType }] }
POST /ai/audio/speechSíntese de fala{ model, text, voice?, format? }stream de bytes audio/*
POST /ai/audio/transcriptionsTranscrição de falamultipart/form-data com file + model{ text }
POST /ai/video/generationsVídeo (assíncrono){ model, prompt, ... }{ id, status, pollUrl }
GET /ai/responses/{id}Consulta assíncronaid de respostaresultado em formato de provedor
POST /ai/gatewayPassagem brutaQualquer payload nativo de Workers AI / provedorResposta bruta upstream
GET /ai/modelsCatálogo—{ models: [{ id, modality, pricing, ... }] }
GET /ai/models é a fonte de verdade para quais ids de modelo funcionam em qual endpoint. Leia primeiro se estiver desenvolvendo contra a API.

​
Como uma chamada funciona

Cada chamada faturável passa por cinco fases. Você não vê a maioria delas — são rastreadas no servidor para que possamos reembolsar chamadas com falha e relatar o uso exato.
FaseO que aconteceu
openCriamos um evento de faturamento vinculado à sua solicitação, mas ainda não chamamos upstream.
recordedO provedor upstream retornou. Temos um id de log do Cloudflare AI Gateway. O custo ainda não é conhecido.
pricedCloudflare reportou o custo final. Aplicamos nossa margem e registramos o débito de crédito. Terminal.
failedA chamada upstream falhou ou não conseguimos obter um custo após 20 tentativas. Cliente não é cobrado. Terminal.
syncedO evento com preço foi entregue ao nosso sistema de medição.
Toda resposta bem-sucedida inclui x-kazzle-ai-billing-event-id: airesp_... — guarde se quiser correlacionar a solicitação com exportações de uso depois.

​
Faturamento e margem

Cobramos cloudflare_cost_usd × (1 + markup). A margem é publicada em Configurações → Faturamento → Preços. Chamadas que Cloudflare precificou em $0 (tier gratuito de Workers AI, promoções) chegam à fase priced com custo zero e nunca são faturadas. Reserva: você precisa de pelo menos $0,50 equivalente em créditos para fazer uma chamada. Retemos isso contra seu saldo até a chamada terminar, depois liquidamos o custo real.

​
Erros

StatusSignificado
401Chave de API kzl_ ausente ou inválida.
402Créditos insuficientes para a reserva. Recarregue em Configurações → Faturamento.
4xx de upstreamEncaminhado como está. O corpo contém o erro do provedor. Cliente não é faturado.
5xx de upstreamEncaminhado como está. Cliente não é faturado.

​
Exemplo — geração de imagem

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

​
Exemplo — síntese de fala

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

​
Veja também