Um gateway de LLM com a camada de dados acoplada

Seis endpoints, não um

Tudo sob /api/v1 é chamada de modelo, mas o tipo de modelo define qual endpoint pode responder — e cada endpoint devolve um formato próprio.

As três superfícies de chat são implementações nativas, não uma camada de tradução: cada uma transmite eventos no próprio protocolo, então você analisa o stream exatamente como hoje.

Escolha o endpoint pelo tipo de modelo, não por tentativa

Todo modelo do catálogo carrega um model_kind, e o tipo define qual endpoint pode chamá-lo. A descoberta é gratuita: lê o catálogo local.

# discover before you call — free, reads the catalog
GET /api/v1/models   # every kind, with channels and rates
GET /api/v1/models/{model_id}  # one model, in detail
GET /api/v1/videos/models     # video_generation only
GET /api/v1/decisions/models  # decisions only

Filtre com ?provider= para ver um fornecedor só, ou ?exclude_video_and_decisions=true para esconder tudo menos chat e imagem. Estar no catálogo não é promessa: um modelo de vídeo não responde a um pedido de chat, e a API devolve model_kind_mismatch.

Rota padrão ou um cabeçalho para escolher o provedor

Um modelo pode ser servido por vários canais upstream, cada um com seu fornecedor e seu preço publicado. Sem o cabeçalho, a plataforma escolhe um por você; com X-Felo-Channel, quem escolhe é você.

# first channel only — no automatic fallback
X-Felo-Channel: claude-cc
X-Felo-Channel: claude-cc,anthropic  # ordered selection, not a retry list

• O valor é uma lista ordenada de códigos públicos de canal, tirados de channels[].code do modelo, validada na ordem em que você a escreve.
• Só o grupo de provedor do primeiro canal é enviado, e é o preço desse canal que você paga.
• Não existe fallback automático. Uma lista de canais é uma seleção, não uma política de retentativa — se um provedor falhar, reenvie pela sua aplicação com outro canal.

X-Felo-Channel funciona nos seis endpoints de geração acima. Não se aplica à API de dados nem às Felo APIs: essas vão para o fornecedor que você nomeia na requisição.

Quanto uma chamada custa de verdade

Chamadas de modelo são cobradas por token — entrada, saída e cache — com o multiplicador de desconto do canal aplicado. As tarifas aparecem por 1 milhão de tokens para facilitar a leitura, mas a cobrança usa a precisão por token do snapshot de preços atual, então um pedido curto nunca é arredondado para um milhão.

• Tarifas de cache só se aplicam quando a resposta do protocolo reporta uso de cache; um modelo sem esse relatório cobra tudo pela tarifa de entrada.
• Busca na web que o serviço do modelo executa e reporta custa $0.01 por busca.
• Alguns modelos têm faixas por tamanho do prompt: Claude Haiku 5.5 custa $0.10 na entrada e $0.50 na saída por 1 milhão de tokens até um prompt de 100K tokens, e depois $0.50 e $2.50 pelo pedido inteiro.
• A primeira recarga é de $1. Sem assinatura, sem taxa por assento, sem compromisso mínimo — uma chave parada não custa nada.

Chamadas da API de dados e fluxos Felo saem do mesmo saldo, cada um na sua base publicada: por requisição bem-sucedida, por item retornado ou por uso real.

Dois limites que parecem iguais e não são

Falta de crédito devolve 402 INSUFFICIENT_CREDITS. Chamada rápida demais devolve 429 RATE_LIMITED. Esperar resolve o segundo e nunca resolve o primeiro.

Hoje só /v2/chat documenta limites rígidos. Chamadas de modelo também podem ser limitadas upstream, e isso aparece como 429 — leia X-RateLimit-* e Retry-After em vez de fixar números. Toda resposta traz um request_id, e o X-Request-Id que você envia volta ecoado, então os logs batem.

Imagem e vídeo terminam em segundo plano

Os dois endpoints de geração devolvem um task_id em vez do resultado. Envie, consulte, recolha — e note que, depois que a tarefa existe, a maioria das falhas chega como 200 com status terminal, não como erro HTTP.

# submit, then poll the task
POST /api/v1/images/generations       → task_id
GET  /api/v1/images/generations/{id}  → status, result
POST /api/v1/videos/generations       → task_id
GET  /api/v1/videos/generations/{id}  → status, result

Leia o status antes do resultado: failed e interrupted também são respostas, e error.message diz por quê. Um 402 no envio significa que a tarefa nunca foi criada. O SuperAgent é diferente — devolve um stream_key e empurra eventos por SSE, então não há o que consultar.

Troque a URL base, mantenha o cliente

Os dois SDKs funcionam sem alteração assim que a URL base aponta para cá. npx feloapi-cli setup escreve a mesma configuração para Claude Code e Codex.

# OpenAI SDK
base_url = "https://openapi.felo.ai/api/v1"

# Anthropic SDK — one level up; the SDK appends /v1/messages
base_url = "https://openapi.felo.ai/api"

# pin a provider (optional)
default_headers = {"X-Felo-Channel": "claude-cc"}

IDs de modelo não são iguais entre provedores. Escolha no catálogo antes de virar a URL base, ou a primeira chamada responde 404.

A metade que um gateway costuma deixar com você

Um gateway de LLM roteia chamadas de modelo. Aqui a mesma chave também alcança um catálogo de ⁦5,000+⁩ APIs — então a etapa de busca no seu agente, os slides que ele gera e o documento que ele lê de volta são cobrados dos mesmos créditos, não de mais três fornecedores.

• Search
• PPT Task
• SuperAgent
• Web Fetch
• X Search
• Mindmap
• Landing Page Task
• LiveDoc
• YouTube Subtitling

As chamadas da API de dados vão para provedores nomeados sob /v1/beta — Tavily, Exa, Apollo e o resto do catálogo — cada um na sua base publicada.

Seis perguntas sobre gateway de LLM