API de IA

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. Os apps Kazzle gerados também devem usar esta API — veja IA em apps para conectar a chave em um componente. Não peça aos usuários chaves de provedor a menos que eles explicitamente queiram usar sua própria conta de provedor.

Capacidades

Endpoint	Modalidade	Entrada padronizada	Saída padronizada
`POST /ai/chat/completions`	Chat (texto, streaming)	`messages[]` compatível com OpenAI	`choices[]` compatível com OpenAI ou stream SSE
`POST /ai/responses`	API de Respostas	Compatível com Respostas OpenAI	Compatível com Respostas OpenAI
`POST /ai/images/generations`	Imagem	`{ model, prompt, size?, output_format? }`	`{ images: [{ url? \| b64?, mimeType }] }`
`POST /ai/audio/speech`	Síntese de fala	`{ model, text, voice?, format? }`	stream de bytes `audio/*`
`POST /ai/audio/transcriptions`	Transcrição de fala	`multipart/form-data` com `file` + `model`	`{ text }`
`POST /ai/video/generations`	Vídeo (assíncrono)	`{ model, prompt, ... }`	`{ id, status, pollUrl }`
`GET /ai/responses/{id}`	Polling assíncrono	id de resposta	resultado formatado pelo provedor
`POST /ai/gateway`	Passagem bruta	Qualquer payload nativo de Workers AI / provedor	Resposta bruta upstream
`GET /ai/models`	Catá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 construindo contra a API.

Como uma chamada funciona

Toda chamada faturável passa por cinco fases. Você não vê a maioria delas — são rastreadas no servidor para que possamos reembolsar chamadas falhadas e relatar o uso exato.

Fase	O que aconteceu
`open`	Criamos um evento de faturamento vinculado à sua solicitação, mas ainda não chamamos upstream.
`recorded`	O provedor upstream retornou. Temos um id de log do Cloudflare AI Gateway. O custo ainda não é conhecido.
`priced`	Cloudflare reportou o custo final. Aplicamos nossa margem e registramos o débito de crédito. Terminal.
`failed`	A chamada upstream falhou, ou não conseguimos obter um custo após 20 tentativas. O cliente não é cobrado. Terminal.
`synced`	O 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 (camada gratuita 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

Status	Significado
`401`	Chave de API `kzl_` ausente ou inválida.
`402`	Créditos insuficientes para a reserva. Recarregue em Configurações → Faturamento.
`4xx` de upstream	Encaminhado como está. O corpo contém o erro do provedor. O cliente não é faturado.
`5xx` de upstream	Encaminhado como está. O 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 — texto para 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

Referência de API — esquemas completos de solicitação/resposta para cada endpoint
Chaves de API — criando e usando chaves kzl_
Faturamento — créditos, planos e a margem que aplicamos

Sobre Kazzle

Trabalho

Navegação

Código

Apps

Segurança

Plataforma

Capacidades

Como uma chamada funciona

Faturamento e margem

Erros

Exemplo — geração de imagem

Exemplo — texto para fala

Veja também

​Capacidades

​Como uma chamada funciona

​Faturamento e margem

​Erros

​Exemplo — geração de imagem

​Exemplo — texto para fala

​Veja também

Capacidades

Como uma chamada funciona

Faturamento e margem

Erros

Exemplo — geração de imagem

Exemplo — texto para fala

Veja também