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 caminhoPara quê
POST /v1/chat/completionsConversa, com ou sem streaming, ferramentas, JSON estruturado e imagens.
POST /v1/completionsTexto no formato antigo (prompt).
POST /v1/embeddingsVetores para busca semântica e RAG.
GET /v1/modelsCatálogo com preço em reais (campo pricing_brl). Não precisa de chave.
GET /v1/keySaldo 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 devolve data[].url (formato da OpenAI; aceita size como 1792x1024 ou aspect_ratio, n, resolution, seed e image para editar).
  • POST /v1/videos: responde na hora com o id; consulte GET /v1/videos/ID até status ser succeeded, ou mande callback_url para receber o aviso. Campos: duration, resolution, aspect_ratio, generate_audio, image (primeiro quadro), end_image e mode.
  • POST /v1/predictions e GET /v1/predictions/ID: o mesmo no formato da Replicate, com model, input e webhook.

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" } }.

HTTPtypeQuando
400invalid_request_errorCorpo inválido, modelo no endpoint errado ou parâmetro recusado pelo provedor.
401authentication_errorChave ausente, inválida, revogada ou vencida.
402insufficient_quotaSem saldo para o tamanho máximo da chamada (insufficient_credits) ou teto da chave atingido (key_limit_reached).
403permission_errorModelo fora da lista da chave (model_not_allowed) ou conta bloqueada.
404not_found_errorModelo que não existe no catálogo (model_not_found).
413invalid_request_errorCorpo maior que 25 MB.
429rate_limit_errorLimite de requisições por minuto ou de chamadas simultâneas. Respeite o cabeçalho Retry-After.
502api_errorO provedor falhou e não havia reserva disponível. Tente de novo.
503api_errorServiç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.