Flipters API
Documentação
A Flipters API segue o formato da API da OpenAI. Qualquer biblioteca compatível funciona trocando a URL base para https://api.flipters.com.br/v1 e usando a sua chave do Flipters.
Início rápido
Crie a chave em Minha conta, Flipters API, guarde em uma variável de ambiente e faça a primeira chamada:
curl https://api.flipters.com.br/v1/chat/completions \
-H "Authorization: Bearer $FLIPTERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-5.5",
"messages": [{"role": "user", "content": "Explique RAG em duas frases."}]
}'O id do modelo leva o fabricante na frente. A lista completa, com preço em reais, está em Modelos.
Autenticação
Envie a chave no cabeçalho Authorization: Bearer sk-flp-v1-... (o cabeçalho x-api-key também é aceito). A chave aparece uma vez só, na criação; o Flipters guarda apenas uma impressão dela. Se vazar, revogue no painel e crie outra: a revogação vale em até 15 segundos.
Opcional: mande X-Title: Nome do seu app para separar o uso por aplicativo no seu extrato.
Rotas
| Método e caminho | Para quê |
|---|---|
POST /v1/chat/completions | Conversa, com ou sem streaming, ferramentas, JSON estruturado e imagens. |
POST /v1/completions | Texto no formato antigo (prompt). |
POST /v1/embeddings | Vetores para busca semântica e RAG. |
GET /v1/models | Catálogo com preço em reais (campo pricing_brl). Não precisa de chave. |
GET /v1/key | Saldo da conta, teto e gasto da chave. |
GET /v1/generation?id= | Custo e métricas de uma chamada sua (id do cabeçalho X-Flipters-Request-Id ou o id da resposta). |
Streaming
Com "stream": true a resposta chega em eventos (Server-Sent Events) no mesmo formato da OpenAI, terminando em data: [DONE]. O último evento antes dele traz o uso em tokens. Linhas que começam com dois-pontos são sinais de vida da conexão e devem ser ignoradas (os SDKs já fazem isso).
Sem streaming, respostas que demoram (modelos de raciocínio) podem começar com espaços em branco antes do JSON: é o que mantém a conexão aberta, e qualquer leitor de JSON aceita.
Escolha de provedor e modelo reserva
Cada modelo pode ser servido por mais de um provedor. Por padrão a chamada vai para o provedor disponível com melhor preço e, se ele falhar, para o próximo. Para mudar a preferência, use o campo provider:
curl https://api.flipters.com.br/v1/chat/completions \
-H "Authorization: Bearer $FLIPTERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-sonnet-5.5",
"messages": [{"role": "user", "content": "Oi"}],
"provider": { "sort": "throughput" },
"models": ["openai/gpt-5.6-sol", "google/gemini-3.8-flash"]
}'sort aceita price, throughput ou latency. O campo models lista até 5 modelos reserva, tentados em ordem se o principal estiver fora; a cobrança segue o modelo que respondeu. Também é possível escolher provedores com order, only e ignore dentro de provider.
Imagem, áudio e ferramentas
Modelos que leem imagem recebem partes image_url na mensagem (URL ou base64). Modelos que geram imagem respondem com "modalities": ["image", "text"] e devolvem as imagens em message.images. Chamada de ferramentas (tools), saída em JSON (response_format) e raciocínio (reasoning) funcionam nos modelos que os aceitam; a página de cada modelo lista os parâmetros aceitos.
Gerar imagem e vídeo
Modelos de imagem e vídeo (FLUX, Nano Banana, Ideogram, Recraft, Veo, Kling, Hailuo, Wan, Seedance, Luma Ray) usam rotas próprias. A lista com preço em reais está em Imagem e vídeo e em GET /v1/media/models.
POST /v1/images/generations: espera a imagem ficar pronta e devolvedata[].url(formato da OpenAI; aceitasizecomo 1792x1024 ouaspect_ratio,n,resolution,seedeimagepara editar).POST /v1/videos: responde na hora com oid; consulteGET /v1/videos/IDatéstatussersucceeded, ou mandecallback_urlpara receber o aviso. Campos:duration,resolution,aspect_ratio,generate_audio,image(primeiro quadro),end_imageemode.POST /v1/predictionseGET /v1/predictions/ID: o mesmo no formato da Replicate, commodel,inputewebhook.
O preço é fixo por imagem ou por segundo de vídeo e fica reservado no saldo ao pedir. Só é cobrado o que sair pronto: se a geração falhar, a reserva volta inteira. Os arquivos ficam guardados por 7 dias nos links devolvidos; o texto do pedido é apagado quando a geração termina.
Saldo e cobrança
A conta tem um saldo pré-pago em reais. Antes de cada chamada, o Flipters separa do saldo o custo máximo possível (entrada estimada mais o max_tokens pedido, vezes n). Sem max_tokens, a resposta fica limitada a 8.192 tokens (ou ao máximo do modelo, se for menor) e é esse o valor reservado; para respostas maiores, informe max_tokens. Quando a resposta termina, cobra o custo real e devolve o que sobrou. Diminuir o max_tokens deixa passar chamadas quando o saldo está baixo.
O custo real é o do provedor convertido pelo dólar PTAX de venda do Banco Central do último dia útil, com a taxa do Flipters inclusa. Chamadas recusadas pelo provedor por erro não são cobradas. O extrato e o histórico de chamadas ficam no painel da conta.
curl https://api.flipters.com.br/v1/key -H "Authorization: Bearer $FLIPTERS_API_KEY"Limites
- 600 requisições por minuto por chave (dá para baixar no painel).
- 50 chamadas simultâneas por conta (e 50 gerações de imagem ou vídeo em andamento).
- Cada chamada pode durar até 25 minutos.
- Até 16 respostas por chamada (campo
n). - Corpo de até 25 MB por requisição.
- Teto de gasto opcional por chave, por dia, mês ou total, e lista de modelos permitidos.
As respostas trazem x-ratelimit-limit-requests e x-ratelimit-remaining-requests. Variantes gratuitas de modelos (sufixo :free) não estão disponíveis.
Erros
Os erros seguem o formato da OpenAI: { "error": { "message", "type", "code" } }.
| HTTP | type | Quando |
|---|---|---|
| 400 | invalid_request_error | Corpo inválido, modelo no endpoint errado ou parâmetro recusado pelo provedor. |
| 401 | authentication_error | Chave ausente, inválida, revogada ou vencida. |
| 402 | insufficient_quota | Sem saldo para o tamanho máximo da chamada (insufficient_credits) ou teto da chave atingido (key_limit_reached). |
| 403 | permission_error | Modelo fora da lista da chave (model_not_allowed) ou conta bloqueada. |
| 404 | not_found_error | Modelo que não existe no catálogo (model_not_found). |
| 413 | invalid_request_error | Corpo maior que 25 MB. |
| 429 | rate_limit_error | Limite de requisições por minuto ou de chamadas simultâneas. Respeite o cabeçalho Retry-After. |
| 502 | api_error | O provedor falhou e não havia reserva disponível. Tente de novo. |
| 503 | api_error | Serviço temporariamente indisponível (por exemplo, cotação do dólar fora do ar). |
Erro no meio de um streaming chega como um evento com o campo error.
Privacidade
O Flipters não grava o texto que você envia nem o que o modelo responde. Ficam registrados só os metadados de cada chamada: data, chave, modelo, provedor, tokens, custo, tempo e situação. Os registros de chamada são apagados depois de 400 dias; o extrato de créditos fica guardado.
O processamento acontece nos provedores de cada modelo, em geral fora do Brasil. Para dados sensíveis, use o campo "provider": { "data_collection": "deny" }, que só aceita provedores que não guardam nem usam os dados para treino.
