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.

Embeddings

Endpoint de embeddings compatível com a API da OpenAI. Encaminha para o provider configurado para o modelo solicitado. Atualmente roteia através de providers OpenAI-compatíveis (OpenAI, Mistral, Together, Groq, DeepInfra, Nebius, Fireworks, Cohere, Azure, etc.). Anthropic não expõe API de embeddings; Bedrock, Gemini e Vertex são reservados para evolução futura.

Endpoint

POST /v1/embeddings

Autenticação

Mesmo Bearer token do chat completions:

Authorization: Bearer <FLOOPY_API_KEY>

Corpo da Requisição

{
  "model": "text-embedding-3-small",
  "input": "The quick brown fox jumps over the lazy dog"
}

input pode ser uma única string ou um array de strings para gerar embeddings em lote:

{
  "model": "text-embedding-3-small",
  "input": ["primeiro texto", "segundo texto", "terceiro texto"]
}

Campos

Campo	Tipo	Obrigatório	Descrição
`model`	string	Sim	ID do modelo de embedding (ex.: `text-embedding-3-small`, `text-embedding-3-large`)
`input`	string ou string[]	Sim	Texto(s) a vetorizar
`dimensions`	integer	Não	Tamanho do vetor de saída quando o modelo suporta (ex.: OpenAI `text-embedding-3-*`)
`encoding_format`	string	Não	`float` (padrão) ou `base64`
`user`	string	Não	Identificador livre do chamador — repassado ao provider para analytics

Corpo da Resposta

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.0123, -0.0456, 0.0789, "..."],
      "index": 0
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 9,
    "total_tokens": 9
  }
}

Para inputs em lote, data contém uma entrada por input na ordem da requisição.

Exemplos de Código

curl

curl https://api.floopy.ai/v1/embeddings \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"text-embedding-3-small","input":"hello"}'

Python (SDK OpenAI)

from openai import OpenAI
client = OpenAI(api_key=os.environ["FLOOPY_API_KEY"], base_url="https://api.floopy.ai/v1")
resp = client.embeddings.create(model="text-embedding-3-small", input="hello")
print(resp.data[0].embedding[:5])

JavaScript (SDK OpenAI)

import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.FLOOPY_API_KEY, baseURL: "https://api.floopy.ai/v1" });
const resp = await client.embeddings.create({ model: "text-embedding-3-small", input: "hello" });
console.log(resp.data[0].embedding.slice(0, 5));

Formato de Resposta de Erro

Envelope de erro compatível com OpenAI. Quando nenhum provider configurado para a organização suporta o modelo de embedding solicitado, o gateway retorna 400 com:

{
  "error": {
    "message": "The model `claude-3-5-sonnet` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}

Outros modos de falha (auth, rate limit, 5xx do provider) reusam o mesmo formato de erro de /v1/chat/completions.

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