Referência da API

Endpoint OpenAI-compatible para inferência.

Todas as chamadas usam `Authorization: Bearer bc_live_...`, retornam `x-request-id` quando disponíveis e são auditadas por projeto, chave, modelo, provider, latência, tokens, status, erro e custo em BRL.

GET/v1/models
Lista os aliases de modelos disponíveis para a sua chave, com metadados de provider, capacidades e disponibilidade quando configurados.
GET/v1/balance
Retorna o saldo atual da conta vinculada à chave em micros de BRL e em representação decimal.
GET/v1/usage
Retorna custos, tokens, latência e requests recentes da chave. Use `days` entre 1 e 90 para filtrar o período.
POST/v1/chat/completions
Aceita o formato de chat completions da OpenAI, incluindo `model`, `messages`, `stream`, temperatura e campos compatíveis conforme capacidade do modelo.
Autenticação
Use a chave completa apenas no header. Não use o prefixo exibido no dashboard como segredo.
Authorization: Bearer bc_live_...
Cache de prompt
O provider reutiliza o prefixo processado e gera uma resposta nova. Não é cache da resposta.

Prompts elegíveis têm pelo menos 1.024 tokens e exigem correspondência exata do prefixo. Coloque instruções, exemplos, tools e schemas estáveis no início; dados variáveis no final.

{
  "model": "gpt-5.6-luna",
  "prompt_cache_key": "contratos:v1",
  "prompt_cache_options": {"mode":"implicit","ttl":"30m"},
  "messages": [{"role":"user","content":"..."}]
}

Modelos anteriores usam `prompt_cache_retention` quando disponível. Opções incompatíveis retornam `400 unsupported_prompt_cache_options`. Sem `prompt_cache_key`, o Banana mantém o comportamento automático do provider.

Leituras aparecem em `usage.prompt_tokens_details.cached_tokens`; escritas, quando aplicável, em `cache_write_tokens`. O preço em BRL usa a tarifa oficial de cache em USD × 5 × 0,6.

O cache pertence ao provider e segue a retenção e capacidade do modelo. O Banana não consegue limpar manualmente o KV cache de imediato: altere o prefixo ou a cache key e aguarde a expiração. Retenção estendida, Zero Data Retention e residência regional dependem do contrato e da elegibilidade do provider; usar cache não implica ZDR.

Saldo programático
Consulte o saldo atual usando a mesma chave Bearer da API.
curl https://chatbanana.com/v1/balance \
  -H "Authorization: Bearer $OPENAI_API_KEY"

A resposta informa currency, balance_micros_brl e balance_brl. Valores financeiros usam micros de BRL para evitar perda de precisão.

Streaming
Defina `stream: true` para receber chunks SSE no formato compatível com clientes OpenAI.
{
  "model": "gpt-5.4",
  "messages": [{"role":"user","content":"Resuma este contrato."}],
  "stream": true
}
Erros
Erros seguem o envelope OpenAI-shaped para facilitar compatibilidade com SDKs.
{
  "error": {
    "message": "Model not found.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}
Uso, créditos e custo em BRL
A API valida saldo disponível antes da chamada e cobra o custo medido após a resposta.

Falhas de autenticação e validação não geram débito. Requisições bem-sucedidas registram tokens, latência, modelo, provider, status e custo em BRL.

O tamanho do prompt não bloqueia nem reserva parte do saldo. Contas sem saldo retornam `insufficient_quota` antes de encaminhar a chamada ao provider.