Un gateway LLM con il livello dati incluso

Sei endpoint, non uno

Tutto ciò che sta sotto /api/v1 è una chiamata a un modello, ma il tipo di modello decide quale endpoint può rispondere — e ognuno restituisce il proprio formato.

Le tre superfici di chat sono implementazioni native, non un livello di traduzione: ognuna emette eventi nel proprio protocollo, quindi analizzi lo stream esattamente come oggi.

Scegli l'endpoint in base al tipo di modello, non a caso

Ogni modello del catalogo ha un model_kind, e il tipo decide quale endpoint può chiamarlo. Scoprirlo è gratis: legge il catalogo locale.

# 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

Filtra con ?provider= per vedere un solo provider, o con ?exclude_video_and_decisions=true per nascondere tutto tranne chat e immagini. Essere nel catalogo non è una promessa: un modello video non risponde a una richiesta di chat, e l'API restituisce model_kind_mismatch.

Rotta predefinita, o un header per scegliere il provider

Un modello può essere servito da più canali upstream, ciascuno con il suo provider e la sua tariffa pubblicata. Senza l'header sceglie la piattaforma; con X-Felo-Channel scegli tu.

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

• Il valore è un elenco ordinato di codici canale pubblici presi da channels[].code del modello, convalidato nell'ordine in cui lo scrivi.
• Viene contattato solo il gruppo provider del primo canale, e paghi la tariffa di quel canale.
• Non c'è commutazione automatica. Un elenco di canali è una scelta, non una politica di retry — se un provider fallisce, rinvia dalla tua applicazione con un altro canale.

X-Felo-Channel funziona sui sei endpoint di generazione qui sopra. Non si applica all'API dati né alle Felo APIs: quelle vanno al provider che indichi nella richiesta.

Quanto costa davvero una chiamata

Le chiamate ai modelli si fatturano a token — input, output e cache — con il moltiplicatore di sconto del canale applicato. Le tariffe sono pubblicate per milione di token per leggibilità, ma la fatturazione usa la precisione a token dello snapshot prezzi corrente: una richiesta breve non viene mai arrotondata al milione.

• Le tariffe cache valgono solo se la risposta del protocollo segnala uso della cache; un modello che non lo segnala fattura tutto a tariffa input.
• La ricerca web che il servizio del modello esegue e segnala costa $0.01 per ricerca.
• Alcuni modelli scaglionano in base alla dimensione del prompt: Claude Haiku 5.5 costa $0.10 in input e $0.50 in output per milione di token fino a un prompt di 100K token, poi $0.50 e $2.50 sull'intera richiesta.
• La prima ricarica è di $1. Nessun abbonamento, nessun costo per utente, nessun minimo: una chiave inattiva non costa nulla.

Le chiamate all'API dati e i workflow Felo escono dallo stesso saldo, ognuno con la propria base pubblicata: per richiesta riuscita, per elemento restituito o in base all'uso reale.

Due limiti che si somigliano e non lo sono

Saldo esaurito restituisce 402 INSUFFICIENT_CREDITS. Chiamate troppo rapide restituiscono 429 RATE_LIMITED. Aspettare risolve il secondo e mai il primo.

Oggi solo /v2/chat documenta limiti rigidi. Le chiamate ai modelli possono anche essere limitate upstream, e questo appare come 429 — leggi X-RateLimit-* e Retry-After invece di fissare numeri. Ogni risposta porta un request_id, e l'header X-Request-Id che invii torna indietro identico, così i tuoi log e i nostri combaciano.

Immagini e video si completano in background

Entrambi gli endpoint di generazione restituiscono un task_id invece del risultato. Invia, interroga, ritira — e nota che, una volta creato il task, la maggior parte degli errori arriva come 200 con uno stato terminale, non come errore 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

Leggi lo stato prima del risultato: failed e interrupted sono anch'essi risposte, e error.message dice perché. Un 402 all'invio significa che il task non è mai stato creato. SuperAgent funziona diversamente: restituisce uno stream_key e spinge gli eventi via SSE, quindi non c'è niente da interrogare.

Cambia l'URL di base, tieni il client

Entrambi gli SDK funzionano senza modifiche appena l'URL di base punta qui. npx feloapi-cli setup scrive la stessa configurazione per 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"}

Gli ID dei modelli non coincidono tra provider. Scegli dal catalogo prima di cambiare l'URL di base, altrimenti la prima chiamata risponde 404.

La metà che un gateway di solito ti lascia fare

Un gateway LLM instrada chiamate ai modelli. Qui la stessa chiave raggiunge anche un catalogo da ⁦5,000+⁩ API — così il passo di ricerca del tuo agente, le slide che produce e il documento che rilegge si pagano con gli stessi crediti, non con tre provider in più.

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

Le chiamate all'API dati vanno a provider nominati sotto /v1/beta — Tavily, Exa, Apollo e il resto del catalogo — ognuno con la propria base pubblicata.

Sei domande sul gateway LLM