Documentação para desenvolvedores

Formato OpenAI: chat completions via SSE

POST /v1/chat/completions com "stream": true. A resposta é um text/event-stream de linhas data:, cada uma contendo um bloco JSON.

curl https://api.fluxioapi.com/v1/chat/completions --no-buffer \
  -H "Authorization: Bearer fio_your_key_here" -H "Content-Type: application/json" \
  -d '{"model":"gpt-6.1-sol","stream":true,"messages":[{"role":"user","content":"Hello from the river bank"}]}'

Cada bloco traz o próximo trecho de texto em choices[0].delta.content; o último bloco antes de [DONE] contém as contagens de tokens:

data: {"choices":[{"index":0,"delta":{"content":"Rivers"}}]}
data: {"choices":[{"index":0,"delta":{"content":" bend"}}]}
data: {"choices":[],"usage":{"prompt_tokens":14,"completion_tokens":2,"prompt_tokens_details":{"cached_tokens":0}}}
data: [DONE]

O Fluxio sempre solicita esse último bloco de dados de uso, mesmo quando sua requisição omite include_usage ou o define como false.

A Responses API (/v1/responses) transmite eventos tipados como response.output_text.delta e informa o uso em response.completed.

Formato Anthropic: eventos de Messages

POST /v1/messages com "stream": true e um cabeçalho anthropic-version (o Fluxio adiciona 2023-06-01 quando ele não está presente). Os eventos chegam nesta ordem:

event: message_start
data: {"type":"message_start","message":{"usage":{"input_tokens":25,"cache_read_input_tokens":0,"output_tokens":1}}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Current"}}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":31}}
event: message_stop

As contagens de entrada e cache vêm de message_start; a contagem final de saída vem de message_delta.

Os modelos Claude são disponibilizados apenas para os clientes oficiais Claude Code e Claude Desktop, na versão 2.1.285 ou mais recente — esta é uma regra do provedor upstream. GPT, Gemini e as outras famílias funcionam em qualquer cliente ou SDK no formato da OpenAI.

Formato Gemini: streamGenerateContent nativo

Os modelos Gemini transmitem pela própria rota. Adicione alt=sse para receber eventos enviados pelo servidor; sem isso, a resposta é um array JSON entregue em partes.

curl "https://api.fluxioapi.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse" --no-buffer \
  -H "x-goog-api-key: fio_your_key_here" -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Name one river that crosses three countries"}]}]}'

Cada bloco inclui um total acumulado em usageMetadata; o último determina a cobrança, e os tokens de raciocínio contam como saída.

Os modelos Gemini usam apenas seu protocolo nativo. Para streaming, chame :streamGenerateContent?alt=sse; /v1/chat/completions recusa IDs do Gemini.

O que é contado e como

• Cada solicitação é cobrada com base nos tokens informados pelo upstream: entrada, saída, gravações no cache e leituras do cache, cada um com sua própria tarifa.
• Se o upstream não informar o uso, a chamada será cobrada como 2.000 tokens de entrada mais 2.000 tokens de saída e marcada como estimada.
• Encerrar um streaming antes da hora ainda cobra os tokens produzidos até aquele momento.
• As chamadas de contagem de tokens (count_tokens e countTokens) são gratuitas.
• HTTP 402 significa que o saldo ou o plano mensal associado à chave está esgotado — recarregue para continuar.

Configuração do cliente

Claude Code · Claude Desktop

Defina a URL base como o próprio host da API (sem /v1), use sua chave como token de autenticação e depois execute claude.

export ANTHROPIC_BASE_URL=https://api.fluxioapi.com
export ANTHROPIC_AUTH_TOKEN=fio_your_key_here
claude

Codex · OpenAI SDK

Clientes no formato da OpenAI usam o host da API com /v1 como URL base e sua chave como chave de API. As solicitações de chat vão para /v1/chat/completions.

export OPENAI_BASE_URL=https://api.fluxioapi.com/v1
export OPENAI_API_KEY=fio_your_key_here
codex

import os, openai

river = openai.OpenAI(base_url="https://api.fluxioapi.com/v1", api_key=os.environ["FLUXIO_KEY"])
reply = river.chat.completions.create(model="gpt-6.1-sol", stream=True,
    messages=[{"role": "user", "content": "Describe a waterfall in three lines"}])
for piece in reply:
    print(piece.choices[0].delta.content or "", end="", flush=True)

IDs de GPT para começar: gpt-6.1-sol · gpt-6-astra · gpt-5.6-sol

Gemini CLI

O Gemini CLI usa o host da API sem alterações (não adicione /v1beta) e sua chave:

export GOOGLE_GEMINI_BASE_URL=https://api.fluxioapi.com
export GEMINI_API_KEY=fio_your_key_here
gemini

IDs do Gemini: gemini-3.1-pro · gemini-4-argon · gemini-3.8-flash · gemini-2.5-flash