Introdução

A Kafox é um gateway de IA compatível com a API da OpenAI: uma chave, um endpoint e vários modelos. Troque a base URL e a chave no seu SDK, mantenha o mesmo corpo de requisição, e o saldo em reais é debitado a cada resposta.

Fluxo de uma requisição

Início rápido

1. Gere uma chave

   Em API Keys, crie uma chave kafox_live_.... O segredo aparece uma única vez, então guarde-o antes de fechar o painel.

2. Aponte a base URL

   Use https://api.kafox.dev/v1 no lugar de https://api.openai.com/v1. Nada mais muda.

3. Envie a chamada

   Um POST /chat/completions com model e messages devolve a resposta e debita os tokens. O modelo kafox-free do exemplo é gratuito e funciona até com saldo zerado.

Autenticação

Toda chamada leva a chave no header Authorization. É a chave que identifica qual conta paga a requisição.

Authorization: Bearer kafox_live_xxxxxxxx
Content-Type: application/json

O header X-Api-Key: kafox_live_xxxxxxxx também é aceito, para clientes que não deixam personalizar o Authorization.

• Chave ausente, inválida ou revogada responde 401. Veja Erros.
• Sem saldo responde 402 antes de chamar o modelo, e nada é debitado. Modelos gratuitos passam mesmo assim.
• Uma chave por projeto deixa o histórico separado e permite revogar sem trocar a senha. Cada conta pode ter até 10 chaves ativas.
• Nunca coloque a chave em código de navegador ou de app distribuído. Chame a Kafox a partir do seu servidor e, se uma chave vazar, revogue em API Keys.
• O segredo só aparece uma vez. Do nosso lado guardamos apenas o hash dele.

API Tester

Rode uma chamada real sem sair do navegador. A chave fica só na memória desta aba: não é salva nem registrada em log.

curl

// preencha a chave e clique em Executar

Chat completions

Mesmo corpo e mesma resposta da OpenAI. Aceita streaming por SSE, chamada de ferramentas e imagens nos modelos com visão.

Os demais campos do formato da OpenAI são repassados ao modelo. Nem todo modelo aceita todos eles: um campo não suportado pode ser ignorado ou devolver 400.

{
  "id": "chatcmpl-7e39862f-9c53-49ce-bbc3-fcaf38c5f913",
  "object": "chat.completion",
  "created": 1793593191,
  "model": "deepseek-ai/DeepSeek-V4.1-Flash",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Olá! Como posso ajudar?" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 18, "completion_tokens": 9, "total_tokens": 27 }
}

Headers da resposta

Streaming

Com "stream": true a resposta chega como eventos SSE (data: {...}, um por linha em branco) e termina com data: [DONE]. Peça stream_options.include_usage para receber o consumo no último evento.

data: {"object":"chat.completion.chunk","model":"...","choices":[{"index":0,"delta":{"role":"assistant","content":"Olá"}}]}

data: {"object":"chat.completion.chunk","model":"...","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":"stop"}]}

data: {"object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":21,"completion_tokens":9,"total_tokens":30}}

data: [DONE]

• Modelos com raciocínio mandam o pensamento em delta.reasoning_content (ou message.reasoning_content sem streaming) antes do content. Esses tokens contam no consumo. Com um max_tokens baixo demais o modelo pode gastar tudo pensando e devolver content nulo com finish_reason: "length".
• Erro no meio do stream: se o modelo falhar depois de começar, chega um evento {"error":{"message":"...","type":"api_error","code":"upstream_error"}} em vez de um status HTTP, porque o 200 já foi enviado.

Ferramentas (tool calling)

tools e tool_choice seguem o formato da OpenAI. O modelo devolve tool_calls; execute a função e responda com uma mensagem role: "tool" e o tool_call_id correspondente. Nem todo modelo aceita ferramentas.

• Fallback: se uma rota falhar, a próxima assume em silêncio. A resposta continua vindo da mesma chave, no mesmo formato.
• Cache: prompts repetidos podem ser respondidos pelo cache do gateway (exact, ou semantic quando a pergunta é parecida o bastante). O header X-PyFlow-Cache diz o que aconteceu.

Models

Lista os ids de modelo que a sua chave pode usar. Peça sempre com o id exato: deepseek-ai/DeepSeek-V4.1-Flash, e não só deepseek.

{
  "object": "list",
  "data": [
    { "id": "deepseek-ai/DeepSeek-V4.1-Flash", "object": "model", "created": 1793593191, "owned_by": "kafox" },
    { "id": "kafox-free", "object": "model", "created": 1793593191, "owned_by": "kafox" },
    { "id": "openai/gpt-oss-120b (free)", "object": "model", "created": 1793593191, "owned_by": "kafox" }
  ]
}

• kafox-free é um modelo virtual: escolhe sozinho um modelo gratuito disponível e troca de rota se um estiver limitado.
• Ids terminados em (free) são modelos gratuitos específicos. Use o nome inteiro, com o sufixo.
• Os aliases fast e smart são aceitos no campo model, mas não aparecem na lista.
• Os preços não vêm nesta resposta: estão em GET https://kafox.dev/api/public/pricing, público e sem chave. Os valores são inteiros em micro-reais por milhão de tokens (input_micros_per_1m, cached_micros_per_1m, output_micros_per_1m); 1 R$ = 1.000.000.

Erros

Os erros chegam como JSON no formato da OpenAI. O code é o próprio status HTTP, e o type diz de onde veio o erro.

{
  "error": {
    "message": "chave de API invalida",
    "type": "http_error",
    "code": 401
  }
}

• Tente de novo (com espera crescente) só em 429, 500, 502 e 503. Os erros 400, 401, 402 e 404 não se resolvem sozinhos.
• As mensagens de erro nunca citam o provedor de origem.

Limites

Cada chave tem um limite de requisições por minuto e por hora, e cada conta tem uma cota diária de tokens gratuitos.

• Os valores de requisições são o padrão para chaves sem limite próprio. Uma chave pode ter limites personalizados.
• Os limites contam requisições, não tokens, e usam janelas deslizantes: o Retry-After diz quantos segundos faltam até abrir uma vaga.
• A cota gratuita é uma só por conta (criar mais chaves não aumenta): soma todos os modelos gratuitos usados no dia, não é por modelo. Ela renova à meia-noite UTC.

Saldo e cobrança

O saldo é pré-pago, em reais, e é debitado a cada resposta conforme os tokens usados. Créditos não expiram.

• Como o custo é calculado: tokens de entrada × preço de entrada + tokens de saída × preço de saída, por milhão de tokens. A parte do prompt que o provedor serviu do cache dele é cobrada pela taxa de cache, bem menor. Os preços de cada modelo estão em Modelos e preços.
• Recarga por PIX em Créditos, a partir de R$ 5. Os pacotes são R$ 5, 10, 25, 50 e 100, e você também pode escolher um valor livre.
• Bônus de boas-vindas: a primeira recarga paga de cada conta, de pelo menos R$ 5, ganha mais R$ 5 de bônus, uma única vez.
• Saldo zerado: as chamadas a modelos pagos respondem 402 antes de chamar o modelo, e nada é cobrado. Os modelos gratuitos seguem funcionando dentro da cota diária.
• Onde ver o saldo: no painel, ou no terminal com kafox balance.

Modelos e preços

Valores em reais por 1 milhão de tokens. O painel usa esta mesma tabela para calcular o custo de cada chamada.

Free tier: modelos marcados como free não descontam saldo. Cada conta tem 5 milhões de tokens grátis por dia somando todos os modelos grátis (não é por modelo), com renovação à meia-noite UTC. Use "model": "kafox-free" para a Kafox escolher um modelo grátis e trocar de rota quando um estiver limitado.

A mesma tabela em JSON, para scripts: GET https://kafox.dev/api/public/pricing.

CLI no terminal

A Kafox também vive no terminal. A CLI é uma TUI completa: streaming, raciocínio, edição de arquivos com diff, ferramentas de shell, MCP e subagentes, tudo na sua conta e cobrado como tokens.

Instalação

npm install -g https://kafox.dev/static/downloads/kafox-cli-latest.tgz

Requer Node.js 22.5 ou superior. O mesmo comando atualiza para a versão mais nova, e kafox --version mostra a que está instalada. As versões ficam em /static/downloads/, uma por arquivo (kafox-cli-<versão>.tgz).

Primeiros passos

1. Entre na conta

   kafox login mostra um código curto e um link. Confirme no navegador e a sessão fica gravada em ~/.kafox/.

2. Abra a TUI

   Só kafox já abre a interface na pasta atual, que passa a ser o projeto. Escolha o modelo com /model.

3. Ou rode sem interface

   kafox agent "revise src/ e aponte bugs" roda sem TUI, bom para CI, script e auditoria automática.

Comandos do terminal

kafox                       abre a TUI
kafox login | logout        entra ou sai da conta
kafox whoami | status       conta, saldo e gateway
kafox models                modelos e preços por 1M de tokens
kafox balance | pricing     saldo e pacotes de recarga
kafox key                   cria uma API key
kafox ask "pergunta" [-m modelo]
kafox agent "objetivo" [-y] [--max-steps N] [--json]
kafox -p "prompt" [-y] [--output-format json]   modo sem tela (scripts e CI)
kafox history [n]           conversas salvas
kafox resume [codigo]       retoma uma conversa
kafox continue | -c         volta à conversa mais recente
kafox theme | background    tema e imagem de fundo
kafox provider              provedores alternativos (chaves externas)
kafox mobile                usa a CLI pelo celular via QR Code
kafox update [--check]      atualiza a CLI (confere o SHA-256 antes de instalar)
kafox doctor                diagnostica login, API, modelo, git, sandbox, MCP e versão
kafox --allow-all | -y      abre já aprovando todas as ferramentas
kafox --version | --help

Comandos dentro da TUI

Digite / para abrir o menu (setas navegam, Tab completa, Enter executa).

Atalhos

• Enter enfileira a mensagem enquanto a IA trabalha; Esc duas vezes interrompe o passo em andamento.
• Ctrl+V ou Alt+V colam uma imagem copiada (print) como anexo, com preview lado a lado e um botão para remover cada uma. Se o terminal consumir o Ctrl+V, use /paste.
• Ctrl+Y copia a última resposta; PgUp/PgDn e a roda do mouse rolam a conversa.
• F2 alterna a roda do mouse. Para selecionar texto com a roda ligada, segure Shift (Option no macOS) e arraste.

Modo sem tela (scripts e CI)

Com -p (ou --print) a CLI roda uma única tarefa, sem abrir a interface, e devolve o resultado. Serve para scripts, automações e pipelines. A partir da versão 0.12.

kafox -p "resuma o README"                          imprime só a resposta final
echo "explique este erro" | kafox -p                prompt pelo stdin
git diff | kafox -p "revise esta mudança"           argumento + stdin juntos
kafox -p "rode os testes" -y --output-format json   um objeto JSON no fim
kafox -p "analise o projeto" --plan                 só leitura

No formato json o objeto tem result, model, session_id, is_error, usage, cost_brl, duration_ms, turns e tool_calls (e error quando falha). Nos formatos JSON o stdout tem só JSON; avisos e erros vão para o stderr.

Exemplo de passo de CI (GitHub Actions) que revisa um pull request:

- name: Revisão com Kafox
  env:
    KAFOX_HOME: ${{ runner.temp }}/kafox
    KAFOX_TOKEN: ${{ secrets.KAFOX_TOKEN }}
  run: |
    npm i -g https://kafox.dev/static/downloads/kafox-cli-latest.tgz
    mkdir -p "$KAFOX_HOME" && echo "$KAFOX_TOKEN" > "$KAFOX_HOME/token.json"
    git diff origin/main...HEAD | kafox -p "revise esta mudança e liste problemas" --plan --max-custo 1 > revisao.md

Em CI não há como abrir o navegador para o login: faça kafox login uma vez numa máquina sua e guarde o conteúdo de ~/.kafox/token.json como um segredo do pipeline (KAFOX_TOKEN no exemplo). A sessão expira; renove o segredo quando precisar. Servidores MCP definidos na pasta do projeto não sobem no modo sem tela, porque não há quem aprove.

Recursos da versão 0.11

Disponíveis a partir da CLI 0.11. Confira a sua com kafox --version e atualize com kafox update.

• Memória do projeto: crie um KAFOX.md (ou AGENTS.md) na raiz com o que a IA precisa saber: como rodar os testes, convenções, cuidados. Um ~/.kafox/KAFOX.md vale para todos os projetos. Os arquivos entram no prompt a cada mensagem (até 12.000 caracteres por arquivo e 24.000 no total) e a interface avisa quando carregou algum. O arquivo de um repositório de terceiros é conteúdo não confiável: leia antes de abrir projetos desconhecidos.
• Checkpoints: antes de cada write_file ou edit_file a CLI guarda o estado anterior do arquivo em ~/.kafox/checkpoints/, fora do projeto. Limite de 300 pontos por projeto; arquivos acima de 5 MB não são guardados.
• Permissões: .kafox/permissions.json (projeto) e ~/.kafox/permissions.json (global) listam allow e deny, com * para qualquer texto. Comando bloqueado nunca roda, nem com --allow-all. Comando permitido só pula a pergunta quando todas as partes dele estão na lista.
• Sandbox: usa bwrap (Linux) ou sandbox-exec (macOS): os comandos só escrevem na pasta do projeto, em /tmp e nos caches. Com a sandbox ligada e indisponível, o comando não roda. No Windows não há equivalente simples, então fica desligada.
• Modelo automático: perguntas curtas vão para o modelo barato (padrão kafox-free); código, bugs, refatoração, vários arquivos, imagens e pedidos longos vão para o forte. Escolher um modelo com /model desliga o automático.
• Custo ao vivo: o rodapé mostra o gasto da conversa e da sessão, e o saldo. Modelo gratuito aparece como grátis.

O que o agente faz

• Lê e edita arquivos (read_file, list_dir, write_file, edit_file), com o diff na conversa. Todo caminho fica travado dentro do diretório do projeto.
• Executa comandos (run_command). Quem escreve, edita ou executa pede aprovação: permitir uma vez, permitir sempre ou negar.
• Comando que não termina (servidor, watcher, loop) vai para segundo plano depois de cerca de 60 s: o agente segue o trabalho e consulta ou encerra o processo depois (process_output, stop_process, list_processes).
• Lança subagentes em paralelo para investigar vários pontos, e chama ferramentas de servidores MCP configurados.
• Se a rede cair, tenta de novo sozinho, aumentando a espera; Esc cancela a espera. Conversas ficam salvas em ~/.kafox/chats/ e voltam com kafox resume.

MCP

Configure em ~/.kafox/mcp.json (ou ./mcp.json no projeto, que vence). As ferramentas entram no agente como mcp__servidor__ferramenta. Servidores de um mcp.json do projeto só sobem depois da sua aprovação: a CLI mostra o comando de cada um e você escolhe aprovar uma vez, aprovar sempre para aquela pasta ou não aprovar (/mcp aprovar mostra a tela de novo). Se o arquivo mudar, ela pergunta de novo. Os servidores da sua configuração pessoal em ~/.kafox sobem sozinhos.

{
  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp@latest"]
    },
    "remoto": {
      "type": "remote",
      "url": "https://exemplo.com/mcp",
      "headers": { "authorization": "Bearer ..." }
    }
  }
}

Configuração

A sessão e as preferências ficam em ~/.kafox/ (ou na pasta apontada por KAFOX_HOME). KAFOX_API_URL troca a API e KAFOX_ALLOW_ALL=1 abre já aprovando as ferramentas. A CLI só responde com saldo, ou com um modelo gratuito.

Perguntas frequentes

Qual SDK devo usar?

Qualquer cliente compatível com a OpenAI: os SDKs oficiais de Python e Node.js, o openai-php, ou HTTP puro. Só mudam a base URL e a chave.

Preciso de saldo para testar?

Não. O kafox-free e os modelos com (free) não usam saldo. A cota é de 5 milhões de tokens por dia por conta, e renova à meia-noite UTC.

Recebi 402. E agora?

O saldo acabou. Recarregue por PIX em Créditos; o valor mínimo é R$ 5. Enquanto isso, os modelos gratuitos continuam respondendo.

Recebi 429. O que significa?

Ou a chave passou do limite de requisições por minuto ou por hora, ou a cota gratuita do dia acabou. Espere o número de segundos do header Retry-After e tente de novo. Veja Limites.

Streaming, ferramentas e imagens funcionam?

Sim. Streaming por SSE, tools e image_url seguem o formato da OpenAI. Ferramentas e imagens dependem do modelo escolhido: um modelo sem visão não aceita imagens.

Por que a resposta veio sem texto?

Em modelos com raciocínio, o pensamento consome o max_tokens. Aumente o limite, ou leia também o campo reasoning_content.

Como falo com o suporte?

Por [email protected], ou pela comunidade no Discord, onde também há tickets de atendimento. Informe o X-Request-Id da chamada que falhou.

Esta documentação está disponível para IAs?

Sim, em texto simples, no formato llm.txt.