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

# API de IA

> Chamadas universais de IA — chat, imagens, fala, transcrição, vídeo — faturadas contra seu espaço.

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](/platform/api-keys) para saber como criar uma.

Os apps Kazzle gerados também devem usar esta API — veja [IA em apps](/apps/ai-api) 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](/platform/billing#pricing). 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

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

## Exemplo — texto para fala

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

## Veja também

* [Referência de API](/api-reference) — esquemas completos de solicitação/resposta para cada endpoint
* [Chaves de API](/platform/api-keys) — criando e usando chaves `kzl_`
* [Faturamento](/platform/billing) — créditos, planos e a margem que aplicamos