# Kafox

> Kafox é um gateway de IA compatível com a API da OpenAI: uma chave, um
> endpoint e vários modelos (DeepSeek, Kimi, GLM, Qwen, Nemotron, GPT,
> Claude e Gemini). Tem painel de saldo, chaves, consumo e uma CLI de
> terminal com agente que lê e edita arquivos.

Atualizado em: 2026-10-28
Site: https://kafox.dev
Documentação: https://kafox.dev/docs
API compatível com OpenAI: https://api.kafox.dev/v1
API da plataforma (contas, saldo, chaves): https://backend.kafox.dev/api
Preços em JSON: https://kafox.dev/api/public/pricing

## O que é

- Gateway OpenAI-compatible com roteamento, fallback entre provedores, cache
  exato e semântico, streaming SSE e tool calling.
- Cobrança por uso, em reais, descontada de um saldo pré-pago recarregado por
  PIX.
- CLI (`kafox`) com TUI, agente de código, MCP, subagentes e temas.

Qualquer SDK oficial da OpenAI funciona: basta trocar `base_url` e a chave.

## Autenticação

Toda chamada ao gateway usa uma API key no header:

```
Authorization: Bearer kafox_live_xxxxxxxxxxxxxxxx
```

- As chaves são criadas no painel (https://kafox.dev/dashboard → Chaves) ou
  com `kafox key`.
- A chave só aparece em texto puro uma vez; o servidor guarda apenas o
  SHA-256 dela.
- Uma chave pertence a uma conta: revogar uma não afeta as outras.

## Modelos e preços

Preço em reais por 1 milhão de tokens, com desconto em cache. Valores de
referência (a fonte de verdade é `/api/public/pricing`):

| Modelo | Entrada (R$/1M) | Cache (R$/1M) | Saída (R$/1M) |
| --- | --- | --- | --- |
| deepseek-ai/DeepSeek-V4.1-Flash-1017 | 1,08 | 0,0216 | 4,32 |
| deepseek-ai/DeepSeek-V4.1-Flash | 1,08 | 0,0216 | 4,32 |
| moonshotai/Kimi-K3 | 27,00 | 2,70 | 135,00 |
| zai-org/GLM-5.3-Flash | 1,08 | 0,216 | 3,60 |
| Qwen/Qwen3.8-27B-FP8 | 0,90 | 0,18 | 18,00 |
| nvidia/NVIDIA-Nemotron-3.5-Super-VL-120B-A12B-NVFP4 | 0,63 | 0,216 | 3,33 |

O modelo é escolhido no campo `model` do corpo, com o id exato da tabela.
Listar os modelos disponíveis para a sua chave:

```bash
curl https://api.kafox.dev/v1/models \
  -H "Authorization: Bearer $KAFOX_API_KEY"
```

## Free tier (1 milhão de tokens por dia)

Toda conta tem 1.000.000 de tokens grátis por dia nos modelos marcados como
**free**, sem precisar de saldo. A cota é uma só: soma todos os modelos grátis
que a conta usar no dia (não é 1M por modelo) e renova à meia-noite UTC.

- `POST https://backend.kafox.dev/api/chat` com `"model": "free"` deixa o
  serviço escolher: ele rotaciona entre os modelos grátis disponíveis e pula
  para o próximo provedor quando um está limitado ou fora do ar.
- Também dá para pedir um modelo específico pelo nome que aparece em
  `/api/public/pricing`, com o sufixo ` (free)` — por exemplo
  `"model": "openai/gpt-oss-120b (free)"`.
- A resposta vem com o header `x-kafox-tier: free`; nada é descontado do saldo.
- Ao passar do 1M no dia a resposta é `429` com `code: "free_limit"`.
- A CLI usa essa rota: `/model` lista os modelos grátis junto com os pagos.

```bash
curl https://backend.kafox.dev/api/chat \
  -H "Content-Type: application/json" \
  -H "Cookie: pf_session=..." \
  -d '{
    "api_key": "kafox_live_xxxxxxxxxxxxxxxx",
    "model": "free",
    "messages": [{"role": "user", "content": "oi"}]
  }'
```

## Chat completions

`POST https://api.kafox.dev/v1/chat/completions`

```bash
curl https://api.kafox.dev/v1/chat/completions \
  -H "Authorization: Bearer $KAFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4.1-Flash-1017",
    "messages": [
      {"role": "system", "content": "Responda em português."},
      {"role": "user", "content": "Explique o que é um gateway de IA."}
    ],
    "temperature": 0.7
  }'
```

Resposta no formato da OpenAI:

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "deepseek-ai/DeepSeek-V4.1-Flash-1017",
  "choices": [
    { "index": 0, "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" }
  ],
  "usage": { "prompt_tokens": 128, "completion_tokens": 310, "total_tokens": 438 }
}
```

### Streaming

Envie `"stream": true` e leia SSE (`data: {...}` por linha, terminando com
`data: [DONE]`). O último frame traz `usage` quando você manda
`"stream_options": {"include_usage": true}`.

### Ferramentas (tool calling)

`tools` e `tool_choice` seguem o formato da OpenAI. O modelo pode devolver
`tool_calls`; devolva o resultado com `role: "tool"` e `tool_call_id`.

### Cache

Respostas idênticas (ou semanticamente iguais, acima do limiar) podem vir do
cache, sem custo de tokens. O header `x-kafox-cache` diz `miss`, `exact` ou
`semantic`, e `x-kafox-provider` diz qual provedor respondeu.

## SDKs

A API é compatível com a OpenAI, então use o SDK oficial mudando a base URL.

Node.js:

```js
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.KAFOX_API_KEY,
  baseURL: "https://api.kafox.dev/v1",
});

const reply = await client.chat.completions.create({
  model: "deepseek-ai/DeepSeek-V4.1-Flash-1017",
  messages: [{ role: "user", content: "Oi!" }],
});
console.log(reply.choices[0].message.content);
```

Python:

```python
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["KAFOX_API_KEY"],
    base_url="https://api.kafox.dev/v1",
)

reply = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4.1-Flash-1017",
    messages=[{"role": "user", "content": "Oi!"}],
)
print(reply.choices[0].message.content)
```

## CLI

```bash
npm i -g https://kafox.dev/static/downloads/kafox-cli-0.9.5.tgz
kafox login          # abre o navegador e liga a CLI à conta
kafox                # abre o chat no terminal
kafox ask "..." -m deepseek-ai/DeepSeek-V4.1-Flash-1017
kafox agent "corrija os testes" --allow-all
kafox models | balance | pricing | key | history | theme
```

- `kafox login` usa device code: a CLI mostra um código, você aprova em
  https://kafox.dev/cli e a sessão fica salva no disco (~/.kafox).
- `kafox agent` roda o agente sem TUI (ferramentas de arquivo, shell, MCP,
  subagentes). `--json` imprime só o resultado final.
- `kafox resume [codigo]` retoma uma conversa salva.

## Contas, saldo e recarga

- `POST /api/auth/register` cria a conta; o e-mail é verificado por código.
- `GET /api/bootstrap` (com cookie de sessão) devolve usuário, saldo, pacotes
  e preços.
- Recarga por PIX: `POST /api/checkout` com `package_id` (`p5`, `p10`, `p25`,
  `p50`, `p100`) ou `amount` em reais; devolve o código copia-e-cola.
- **Bônus de boas-vindas**: a primeira recarga paga de cada conta (mínimo
  R$ 5,00) credita mais R$ 5,00 de bônus, uma única vez. A partir da segunda
  recarga entra só o valor pago.
- Valores monetários são inteiros em **micro-reais** (1 R$ = 1.000.000).

## Códigos de erro

| HTTP | Código | Significado |
| --- | --- | --- |
| 400 | `invalid_model` | modelo desconhecido (veja `/v1/models`) |
| 400 | `invalid_request` | corpo fora do formato da OpenAI |
| 401 | `invalid_api_key` | chave ausente ou inválida |
| 402 | `no_balance` | saldo esgotado: recarregue no painel |
| 403 | `invalid_api_key` | chave revogada ou de outra conta |
| 429 | `rate_limited` | limite por minuto da chave atingido |
| 502 | `provider_error` | todos os provedores da rota falharam |
| 504 | `timeout` | o provedor demorou demais para responder |

Erros seguem o formato `{"error": {"message": "..."}}` (compatível com a
OpenAI) e também trazem `code` no nível raiz quando aplicável.

## Limites

- Rate limit padrão por chave: 60 requisições/minuto e 2.000/hora (ajustável
  por chave no painel).
- Tamanho de corpo: 32 MB em `/api/chat`, 128 KB nas demais rotas da API.
- Timeout de stream: 30 minutos; cancelar fecha a conexão e para a cobrança.

## Notas para modelos de linguagem

- Sempre use o id completo do modelo (`deepseek-ai/DeepSeek-V4.1-Flash-1017`,
  não `deepseek`).
- A base URL é `https://api.kafox.dev/v1`; o caminho é `/chat/completions`.
- Não invente preços: consulte `/api/public/pricing` ou a tabela acima.
- A plataforma é separada do gateway: contas e saldo ficam em
  `https://backend.kafox.dev/api`, chamadas de modelo em
  `https://api.kafox.dev/v1`.
- Suporte: suporte@kafox.dev