API Reference

O gateway Floopy expõe uma API compatível com OpenAI. Aponte qualquer SDK da OpenAI para o gateway alterando a baseURL, e seu código existente funciona sem modificações.

Endpoint

POST https://api.floopy.ai/v1/chat/completions

Autenticação

Inclua sua API key do Floopy no header Authorization:

Authorization: Bearer <your-floopy-api-key>

Corpo da Requisição

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Hello!" }
  ],
  "temperature": 0.7,
  "max_tokens": 1000,
  "stream": false,
  "inputs": { "name": "Alice" }
}

Campos

Campo	Tipo	Obrigatório	Descrição
`model`	string	Sim	ID do modelo (ex.: `"gpt-4o"`). Separado por vírgulas para fallback: `"gpt-4o,claude-sonnet-4-6"`
`messages`	array	Sim	Array de objetos de mensagem com `role` (`"system"`, `"user"`, `"assistant"`) e `content` (string)
`temperature`	number	Não	0.0-2.0. Controla a aleatoriedade. Padrão: padrão do modelo
`max_tokens`	integer	Não	Máximo de tokens na resposta
`top_p`	number	Não	0.0-1.0. Limite de nucleus sampling
`frequency_penalty`	number	Não	-2.0 a 2.0. Reduz repetição de tokens
`presence_penalty`	number	Não	-2.0 a 2.0. Incentiva novos tópicos
`stop`	array	Não	Strings que interrompem a geração quando encontradas
`reasoning_effort`	string	Não	`"low"`, `"medium"`, `"high"`. Apenas para modelos o1/o3
`response_format`	object	Não	Modo JSON: `{"type": "json_object"}`
`stream`	boolean	Não	Habilita streaming SSE. Padrão: `false`
`inputs`	object	Não	Pares chave-valor para substituição de variáveis em templates de prompt. Removido antes do envio ao provider

Corpo da Resposta (sem streaming)

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1717000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello! How can I help?" },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 8,
    "total_tokens": 20
  }
}

Corpo da Resposta (streaming)

Quando stream: true, o gateway retorna Server-Sent Events (SSE). Cada evento contém um chunk:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1717000000,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}

O stream termina com:

data: [DONE]

Headers de Resposta

O gateway adiciona estes headers a toda resposta:

Header	Descrição	Exemplo
`Floopy-Provider`	O provider que atendeu a requisição	`OpenAI`
`Floopy-Model`	O modelo que processou a requisição	`gpt-4o`
`Floopy-Fallback-Used`	Se um provider de fallback foi usado porque o primário estava indisponível	`true`
`Floopy-Reasoning-Tokens`	Número de reasoning tokens usados (modelos DeepSeek)	`150`
`Floopy-Queue-Time`	Tempo que a requisição ficou na fila do provider, em segundos (Groq)	`0.5`
`Floopy-Prompt-Time`	Tempo gasto processando o prompt, em segundos (Groq)	`0.2`
`Floopy-Completion-Time`	Tempo gasto gerando o completion, em segundos (Groq)	`1.3`

Formato de Resposta de Erro

Erros padrão retornam um corpo JSON:

{
  "error": {
    "type": "error",
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Erros de rate limit (429) incluem um header Retry-After com o número de segundos a aguardar.

Erros de limite mensal incluem campos adicionais:

{
  "error": {
    "type": "error",
    "code": "MONTHLY_LIMIT_EXCEEDED",
    "message": "Monthly request limit reached",
    "limit": 100000,
    "used": 100000,
    "reset_at": "2025-02-01T00:00:00Z"
  }
}

Consulte Troubleshooting para uma lista completa de códigos de erro e como resolvê-los.

Feedback de Sessão

Envie feedback no nível de sessão para melhorar a qualidade do roteamento. Autenticado com a mesma API key usada para requisições de chat.

POST https://api.floopy.ai/v1/feedback

Corpo da Requisição

{
  "session_id": "sess_abc123",
  "score": 8,
  "useful": true
}

Campos

Campo	Tipo	Obrigatório	Descrição
`session_id`	string	Sim	O ID da sessão enviado no header `floopy-session-id` durante as requisições de chat
`score`	integer	Sim	Score NPS de 0 a 10. 0-6 = detrator, 7-8 = passivo, 9-10 = promotor
`useful`	boolean	Sim	Se a conversa foi útil para o usuário final

Resposta

Retorna 200 OK com um objeto JSON vazio em caso de sucesso.

{}

Consulte Feedback para detalhes sobre como o feedback impulsiona a otimização de roteamento.

Health Endpoints

Use estes endpoints para monitorar o status do gateway e suas dependências.

Endpoint	Descrição
`GET /health`	Probe de liveness (sempre 200)
`GET /health/ready`	Probe de readiness (verifica Redis, ClickHouse, Qdrant)
`GET /health/redis`	Verificação de conectividade com Redis
`GET /health/clickhouse`	Verificação de conectividade com ClickHouse
`GET /health/qdrant`	Verificação de conectividade com Qdrant
`GET /health/providers`	Estado do circuit breaker por provider