Pular para o conteúdo
Floopy Docs

Integração

Visão Geral

O Floopy é compatível com o SDK da OpenAI. Para começar a rotear requisições pelo gateway, altere sua baseURL para https://api.floopy.ai/v1 e use sua API key do Floopy. Nenhum SDK ou biblioteca adicional é necessário.

Início Rápido

import { OpenAI } from "openai";


const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
});


const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Explain quantum computing in one sentence." }],
});


console.log(response.choices[0].message.content);

Rastreamento de Sessão

Acompanhe conversas ao longo de múltiplas requisições passando um ID de sessão no header floopy-session-id. Você também pode definir floopy-session-name e floopy-session-path para contexto mais rico. Esses headers agrupam requisições relacionadas nos logs do dashboard, facilitando o acompanhamento de um fluxo completo de conversa.

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-session-id": "session_abc123",
      "floopy-session-name": "Onboarding Chat",
      "floopy-session-path": "/app/onboarding",
    },
  },
);

Rastreamento de Projeto

Segmente requisições por projeto enviando o header floopy-project-id. Isso marca a requisição com um projeto específico para rastreamento de custos por projeto, dashboards e analytics. Se sua chave de API está travada em um projeto, esse header é opcional — o projeto travado é usado automaticamente.

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-project-id": "a1b2c3d4-5678-9abc-def0-123456789abc",
    },
  },
);

Veja o guia de Projetos para detalhes sobre a cadeia de fallback, chaves de API por projeto e modelo de ambientes.

Rastreamento de Usuário

Use o header floopy-user-id (ou o campo user da OpenAI) para associar requisições a um usuário final específico. Isso aparece nos logs do dashboard e ajuda com analytics por usuário e detecção de abuso.

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-user-id": "user_12345",
    },
  },
);

Propriedades Personalizadas

Anexe metadados arbitrários às requisições usando headers individuais floopy-property-*. Cada header segue o padrão floopy-property-<nome>: <valor>. Você pode adicionar quantas propriedades precisar.

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-property-environment": "production",
      "floopy-property-feature": "chat-widget",
      "floopy-property-version": "2.1.0",
      "floopy-property-usertier": "premium",
    },
  },
);

Essas propriedades são pesquisáveis e filtráveis nos logs do dashboard.

Alternando entre Providers

Como o Floopy traduz todas as requisições em um formato unificado, você pode alternar entre providers mudando o nome do modelo. Nenhuma outra alteração de código é necessária:

// Use OpenAI
const a = await client.chat.completions.create({
  model: "gpt-4o",
  messages,
});


// Use Anthropic
const b = await client.chat.completions.create({
  model: "claude-3-5-sonnet-20241022",
  messages,
});


// Use Google Gemini
const c = await client.chat.completions.create({
  model: "gemini-2.5-pro",
  messages,
});

Certifique-se de que o provider correspondente está configurado em Settings > Providers. Consulte o guia de Providers para instruções de configuração.

Model Override

Use o header floopy-model-override para substituir o modelo especificado no corpo da requisição. Isso permite que você altere qual modelo processa a requisição sem modificar o código da sua aplicação.

import { OpenAI } from "openai";


const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
});


// Request body says gpt-4o, but the gateway will use claude-3-5-sonnet-20241022
const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-model-override": "claude-3-5-sonnet-20241022",
    },
  },
);


console.log(response.choices[0].message.content);

Routing Rule Override

Use o header floopy-routing-rule para substituir a configuração de routing padrão de uma requisição. Isso direciona a requisição para uma routing rule específica que você configurou no dashboard.

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-routing-rule": "low-latency-us-east",
    },
  },
);

Headers de Resposta

O gateway inclui headers informativos em cada resposta. Eles indicam qual provider e modelo processou a requisição, e se um fallback foi utilizado.

HeaderDescrição
Floopy-ProviderO provider que processou a requisição (ex.: openai, anthropic, google)
Floopy-ModelO modelo que foi utilizado (ex.: gpt-4o, claude-3-5-sonnet-20241022)
Floopy-Fallback-Used"true" se o provider primário falhou e um provider de fallback processou a requisição
const res = await fetch("https://api.floopy.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.FLOOPY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  }),
});


console.log("Provider:", res.headers.get("Floopy-Provider"));
console.log("Model:", res.headers.get("Floopy-Model"));
console.log("Fallback Used:", res.headers.get("Floopy-Fallback-Used"));


const data = await res.json();
console.log(data.choices[0].message.content);

Streaming

O Floopy suporta respostas em streaming. Use o parâmetro stream como faria normalmente:

const stream = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Write a short poem." }],
  stream: true,
});


for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}