Compatível com a API da OpenAI

Documentação da API

A Kallavy é um broker de IA: sua aplicação fala com um único endpoint compatível com OpenAI e a gente roteia para os melhores modelos do mundo — com cobrança em BRL via PIX, Nota Fiscal e suporte em português. Já usa o SDK da OpenAI? Troque apenas base_url e api_key. Zero mudança de código.

Introdução

Esta referência cobre os endpoints voltados ao desenvolvedor. Tudo é feito sobre HTTPS, com corpo em JSON, e segue o mesmo contrato da API de Chat Completions da OpenAI. A gestão da conta — chaves, saldo, consumo, governança e Nota Fiscal — fica no painel, não na API.

Privacidade (LGPD): registramos apenas metadados de uso (modelo, tokens, custo). O conteúdo dos seus prompts e respostas nunca é armazenado.

Base URL

Todas as chamadas usam o domínio dedicado do broker:

endpoint

https://api.kallavy.com/v1

Autenticação

Cada requisição precisa do header Authorization com a sua API key no formato Bearer. Gere e gerencie suas chaves no painel → API Keys.

header

Authorization: Bearer sk-...sua-chave

Mantenha sua chave em segredo. Ela dá acesso ao saldo da sua conta. Nunca a exponha no front-end nem em repositórios públicos. Comprometeu? Revogue no painel e gere outra.

Início rápido

Uma chamada completa de chat, em três linguagens:

# pip install openai
from openai import OpenAI

client = OpenAI(
    api_key="sk-...sua-chave",
    base_url="https://api.kallavy.com/v1",
)

resp = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Resuma este contrato em 3 linhas."}],
)
print(resp.choices[0].message.content)

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-...sua-chave",
  baseURL: "https://api.kallavy.com/v1",
});

const resp = await client.chat.completions.create({
  model: "deepseek-chat",
  messages: [{ role: "user", content: "Resuma este contrato em 3 linhas." }],
});
console.log(resp.choices[0].message.content);

curl https://api.kallavy.com/v1/chat/completions \
  -H "Authorization: Bearer sk-...sua-chave" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Resuma este contrato em 3 linhas."}]
  }'

GET /v1/models

Lista os modelos disponíveis para a sua conta. Use esta rota como fonte da verdade — o catálogo muda conforme novos provedores entram e conforme a governança da sua conta. Resposta no mesmo formato da OpenAI.

resposta · 200

{
  "object": "list",
  "data": [
    { "id": "deepseek-chat", "object": "model", "owned_by": "kallavy" },
    { "id": "claude-sonnet", "object": "model", "owned_by": "kallavy" },
    // ...
  ]
}

POST /v1/chat/completions

Gera uma resposta de chat. Aceita os mesmos campos da API da OpenAI; a Kallavy autentica, contabiliza o uso e repassa ao provedor real do modelo escolhido.

Parâmetros do corpo

Campo	Tipo	Descrição
model *	string	ID do modelo (ex.: `deepseek-chat`). Veja /v1/models.
messages *	array	Lista de mensagens `{ "role", "content" }` (`system`, `user`, `assistant`).
stream	boolean	Se `true`, devolve a resposta em tokens via SSE. Padrão `false`.
temperature, max_tokens, top_p…	vários	Demais parâmetros padrão da OpenAI são repassados ao provedor.

* obrigatório

Resposta

resposta · 200

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "deepseek-chat",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 42, "completion_tokens": 88, "total_tokens": 130 }
}

Streaming

Com stream: true, a resposta chega em chunks Server-Sent Events (data: {...}), encerrando com data: [DONE] — idêntico à OpenAI. Os SDKs já tratam isso para você.

for chunk in client.chat.completions.create(
    model="claude-sonnet",
    messages=[{"role": "user", "content": "Escreva um haiku."}],
    stream=True,
):
    print(chunk.choices[0].delta.content or "", end="")

Erros

Erros seguem o padrão HTTP com corpo JSON descritivo.

Código	Significado
401	Chave ausente, inválida ou revogada.
403	Bloqueado pela governança da conta (modelo/provedor não permitido ou teto de gasto atingido).
402	Saldo insuficiente — recarregue via PIX no painel.
429	Rate limit excedido. Aguarde e repita com backoff.
5xx	Falha no provedor de origem. Tente novamente.

Limites & cobrança

O consumo é contabilizado por tokens de entrada e saída, por modelo, e debitado do seu saldo em BRL.
Rate limit por chave (ajustável no seu plano). Ao estourar, a API responde 429.
Sua empresa pode definir governança: permitir/bloquear modelos e provedores e impor tetos de gasto — tudo no painel.
Recargas via PIX com emissão de NF-e. Saldo e histórico ficam no painel.

Suporte

Dúvidas de integração? Fale com a gente em suporte@kallavy.com — atendimento em português, no horário de Brasília.

Pronto para a primeira chamada?

Crie sua conta, pegue uma API key e comece em minutos.

Começar agora →