LLM API

La LLM API espone endpoint per la chiamata diretta dei modelli tramite Felo API Platform. Usala quando vuoi chiamare modelli di linguaggio generici, riutilizzare client compatibili con OpenAI o con Anthropic, oppure collegare framework di agenti a Felo API Platform.

La LLM API comprende attualmente tre superfici di chiamata dei modelli compatibili con la chat:

• POST /api/v1/responses: compatibile con OpenAI Responses
• POST /api/v1/chat/completions: compatibile con OpenAI Chat Completions
• POST /api/v1/messages: compatibile con Anthropic Messages

Decisions API

POST https://openapi.felo.ai/api/v1/decisions

Invia stato e domande tipizzate e mirate a jev-1.13 (accettato anche: typesafe/jev-1.13). Usa /api/v1/decisions, non gli endpoint Chat Completions, Messages o Responses. Lo streaming non è supportato.

Campi della richiesta

• model: jev-1.13
• state: contesto da valutare; una stringa o un valore JSON.
• questions: domande denominate che usano type, instructions e criteria.

import os
import requests

response = requests.post(
    "https://openapi.felo.ai/api/v1/decisions",
    headers={"Authorization": f"Bearer {os.environ['FELO_API_KEY']}"},
    json={
        "model": "jev-1.13",
        "state": "Help! My payouts have been failing for 3 days.",
        "questions": {
            "is_urgent": {
                "type": "noul",
                "instructions": "Does this message convey urgency?",
                "criteria": {"true": "Time-sensitive", "false": "No urgency"},
            },
            "department": {
                "type": "choice",
                "instructions": "Which team should handle this?",
                "criteria": {
                    "billing": "Payments, invoicing, refunds",
                    "technical": "Bugs, outages, integrations",
                    "sales": "Pricing, upgrades, new accounts",
                },
            },
            "frustration": {
                "type": "score",
                "instructions": "How frustrated is the customer?",
                "criteria": ["Calm", "Frustrated", "Very angry"],
            },
        },
    },
    timeout=60,
)
response.raise_for_status()
answers = response.json()["answers"]
print(answers["is_urgent"]["noul"])
print(answers["department"]["choice"], answers["department"]["probabilities"])
print(answers["frustration"]["score"])

Tipi di risposta

noul: una probabilità da 0 a 1. choice: l'opzione selezionata e la sua distribuzione di probabilità. score: un punteggio numerico per criteri ordinati, con la relativa distribuzione.

Gli errori usano error.code (stato HTTP numerico) e error.message. Gestisci le risposte non 2xx prima di leggere answers.

Utilizzo e prezzi

La risposta include usage.input_tokens, usage.output_tokens e può includere usage.cost. Tariffe di riferimento verificate il 2026-10-12: input 0.042 USD per milione di token; output 0 USD. Una tariffa di output pari a zero non rende gratuito l'utilizzo in input. Le tariffe possono cambiare; usa il prezzo pubblicato del modello e gli sconti applicabili del tuo account per le stime.

Autenticazione

Le richieste alla LLM API richiedono una chiave di Felo API Platform. Usa Authorization: Bearer ... oppure X-API-Key.

Authorization: Bearer YOUR_API_KEY

X-API-Key: YOUR_API_KEY

Vedi la guida all'autenticazione per i dettagli sulla creazione e gestione delle chiavi API.

URL di base

Usa l'host pubblico di Felo API Platform:

https://openapi.felo.ai

Per i client SDK, configura l'URL di base specifico del protocollo mostrato in Utilizzo di base.

Header comuni

Scoperta dei modelli

Il catalogo generale include tutte le categorie di modelli. Usa gli elenchi dedicati per scoprire i modelli video o di decisione:

Tutti e tre gli endpoint accettano il parametro di query facoltativo provider (ad esempio openrouter) e restituiscono {"object":"list","data":[...]}. Ogni voce contiene id, object, created, owned_by e model_kind. Gli elenchi dedicati usano la categoria effettiva dopo le sovrascritture della mappatura dei provider abilitati.

Vengono restituiti solo i modelli abilitati, elencati, non eliminati e con un prezzo attuale corrispondente alle condizioni del provider; un prezzo pari a zero è valido. I modelli appena sincronizzati restano nascosti finché un amministratore non li elenca. Tutti gli elenchi condividono l'ordinamento configurato, con nome e ID del modello come criteri di spareggio. Nessuna corrispondenza restituisce HTTP 200 con un array data vuoto. La scoperta legge il catalogo locale e non invoca né fattura una chiamata al modello.

Solo GET /api/v1/models accetta exclude_video_and_decisions (booleano, predefinito false). Impostalo su true per escludere i tipi effettivi video_generation e decisions; i modelli di immagine restano inclusi. Può essere combinato con provider. Ometterlo o impostarlo su false mantiene il catalogo completo. Valori booleani non validi restituiscono HTTP 422.

curl "https://openapi.felo.ai/api/v1/models?exclude_video_and_decisions=true&provider=openrouter" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
curl "https://openapi.felo.ai/api/v1/videos/models?provider=openrouter" \
  -H "Authorization: Bearer ${FELO_API_KEY}"
curl "https://openapi.felo.ai/api/v1/decisions/models?provider=openrouter" \
  -H "Authorization: Bearer ${FELO_API_KEY}"

Scegli l'endpoint di chiamata in base a model_kind: chat per Responses, Chat Completions o Messages come supportato dal modello; video_generation per POST /api/v1/videos/generations; decisions per POST /api/v1/decisions; image_generation per POST /api/v1/images/generations. I dettagli restano su GET /api/v1/models/{model_id}. Un modello elencato non è necessariamente compatibile con ogni endpoint di chiamata.

I modelli di immagine non hanno un endpoint di elenco dedicato. Filtra GET /api/v1/models per model_kind: "image_generation". Vedi Generazione di immagini per i campi delle richieste di immagini.

Modelli e prezzi

Le richieste usano il canale predefinito del modello, a meno che tu ne vincoli uno con X-Felo-Channel. Passa un elenco ordinato, separato da virgole, di codici canale pubblici dal catalogo dei modelli; ometti l'header per usare il predefinito. Usa default solo da solo. Viene inoltrato solo il gruppo di provider del primo canale; non esiste alcun fallback automatico. Vedi Canali e routing dei provider.

I prezzi sono indicati in USD. Le tariffe per token sono mostrate per 1 milione di token per leggibilità; la fatturazione usa la precisione per token dello snapshot dei prezzi corrente. Le tariffe della cache si applicano solo quando la risposta del protocollo include l'utilizzo della cache. Un trattino indica l'assenza di una tariffa separata pubblicata o di un limite pubblicato. L'utilizzo della ricerca web, quando riportato dal servizio del modello, viene addebitato a $0.01 per ricerca.

Claude Haiku 5.5 usa prezzi a scaglioni: i prompt fino a 100K token sono fatturati alle tariffe standard sopra indicate, mentre le richieste il cui prompt supera 100K token sono fatturate a $0.50 input, $2.50 output, $0.05 lettura cache e $0.0625 scrittura cache per 1M di token sull'intera richiesta.

GPT-5.6 è disponibile in tre livelli: Luna per carichi di lavoro rapidi ed efficienti in termini di costi; Terra per attività bilanciate di programmazione, ragionamento e agentiche; e Sol per ragionamento complesso e programmazione di punta. Ogni livello espone anche un ID modello -pro (gpt-5.6-luna-pro, gpt-5.6-terra-pro e gpt-5.6-sol-pro) che usa lo stesso modello sottostante con la modalità di ragionamento pro. Prezzi, lunghezza del contesto e output massimo restano invariati per gli ID -pro.

DeepSeek V4 Flash supporta modalità di ragionamento e non ragionamento, output JSON, chiamate agli strumenti, Responses API e compatibilità con l'API Anthropic. È disponibile tramite le superfici Responses, Chat Completions e Messages di Felo. Il prezzo della scrittura cache non è ancora pubblicato.

Utilizzo di base

Questi esempi usano gli SDK ufficiali OpenAI e Anthropic. Imposta FELO_API_KEY con la tua chiave di Felo API Platform prima di eseguire gli esempi.

export FELO_API_KEY="YOUR_API_KEY"

Installare gli SDK

SDK OpenAI

Usa l'SDK OpenAI per la Responses API e la Chat Completions API.

##### JavaScript

npm install openai

##### Python

pip install openai

SDK Anthropic

Usa l'SDK Anthropic per la Messages API.

##### JavaScript

npm install @anthropic-ai/sdk

##### Python

pip install anthropic

Configurare i client

Gli endpoint compatibili con OpenAI usano l'URL di base dell'SDK OpenAI con /api/v1, perché l'SDK aggiunge percorsi delle risorse come /responses e /chat/completions.

JavaScript

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.FELO_API_KEY,
  baseURL: "https://openapi.felo.ai/api/v1",
});

Python

import os
from openai import OpenAI

openai = OpenAI(
    api_key=os.environ.get("FELO_API_KEY"),
    base_url="https://openapi.felo.ai/api/v1",
)

Gli endpoint compatibili con Anthropic usano l'URL di base dell'SDK Anthropic senza /v1, perché l'SDK aggiunge /v1/messages.

JavaScript

import Anthropic from "@anthropic-ai/sdk";

const anthropic = new Anthropic({
  apiKey: process.env.FELO_API_KEY,
  baseURL: "https://openapi.felo.ai/api",
});

Python

import os
from anthropic import Anthropic

anthropic = Anthropic(
    api_key=os.environ.get("FELO_API_KEY"),
    base_url="https://openapi.felo.ai/api",
)

Usare la Responses API

Usa la Responses API per le nuove integrazioni compatibili con OpenAI e per gli oggetti di risposta in stile agente.

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FELO_API_KEY,
  baseURL: "https://openapi.felo.ai/api/v1",
});

const response = await client.responses.create({
  model: "gpt-5.6-sol",
  input: "Write a one-sentence bedtime story about a unicorn.",
});

console.log(response.output_text);

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("FELO_API_KEY"),
    base_url="https://openapi.felo.ai/api/v1",
)

response = client.responses.create(
    model="gpt-5.6-sol",
    input="Write a one-sentence bedtime story about a unicorn.",
)

print(response.output_text)

Usare Chat Completions

Usa Chat Completions quando la tua applicazione invia già messages in stile OpenAI.

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FELO_API_KEY,
  baseURL: "https://openapi.felo.ai/api/v1",
});

const completion = await client.chat.completions.create({
  model: "gpt-5.6-sol",
  messages: [
    {
      role: "user",
      content: "Give me one sentence about why API compatibility matters.",
    },
  ],
});

console.log(completion.choices[0].message.content);

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("FELO_API_KEY"),
    base_url="https://openapi.felo.ai/api/v1",
)

completion = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[
        {
            "role": "user",
            "content": "Give me one sentence about why API compatibility matters.",
        }
    ],
)

print(completion.choices[0].message.content)

Usare Messages

Usa Messages quando il tuo client o framework di agenti si aspetta forme di richiesta e risposta compatibili con Anthropic.

JavaScript

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.FELO_API_KEY,
  baseURL: "https://openapi.felo.ai/api",
});

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 128,
  messages: [
    {
      role: "user",
      content: "Summarize the value of direct model APIs in one sentence.",
    },
  ],
});

const text = message.content
  .filter((block) => block.type === "text")
  .map((block) => block.text)
  .join("");

console.log(text);

Python

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ.get("FELO_API_KEY"),
    base_url="https://openapi.felo.ai/api",
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=128,
    messages=[
        {
            "role": "user",
            "content": "Summarize the value of direct model APIs in one sentence.",
        }
    ],
)

text = "".join(block.text for block in message.content if block.type == "text")
print(text)

Documentazione ufficiale

• Avvio rapido dell'API OpenAI
• OpenAI Create response
• OpenAI Create chat completion
• Claude Messages API
• SDK TypeScript di Anthropic
• SDK Python di Anthropic

Per la configurazione dei client agente, vedi Configurazione di Claude Code e Codex.

Riferimento dei protocolli

Responses

Usa questo endpoint per client e integrazioni compatibili con la OpenAI Responses API.

Endpoint

POST https://openapi.felo.ai/api/v1/responses

Corpo della richiesta

Richiesta SDK

const response = await client.responses.create({
  model: "gpt-5.6-sol",
  input: "Reply with exactly: responses ok",
});

console.log(response.output_text);

Percorso del testo nella risposta

output_text

Chat Completions

Usa questo endpoint per client e SDK compatibili con OpenAI Chat Completions.

Endpoint

POST https://openapi.felo.ai/api/v1/chat/completions

Corpo della richiesta

Richiesta SDK

const completion = await client.chat.completions.create({
  model: "gpt-5.6-sol",
  messages: [
    {
      role: "user",
      content: "Reply with exactly: chat completions ok",
    },
  ],
});

console.log(completion.choices[0].message.content);

Percorso del testo nella risposta

choices[0].message.content

Messages

Usa questo endpoint per client e SDK compatibili con Anthropic Messages.

Endpoint

POST https://openapi.felo.ai/api/v1/messages

Corpo della richiesta

Richiesta SDK

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 64,
  messages: [
    {
      role: "user",
      content: "Reply with exactly: messages ok",
    },
  ],
});

const text = message.content
  .filter((block) => block.type === "text")
  .map((block) => block.text)
  .join("");

console.log(text);

Richiesta con blocchi di contenuto

const message = await client.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 64,
  messages: [
    {
      role: "user",
      content: [
        {
          type: "text",
          text: "Reply with exactly: messages ok",
        },
      ],
    },
  ],
});

Percorso del testo nella risposta

content[].text

Streaming

Imposta stream su true per ricevere Server-Sent Events. Il formato del payload degli eventi segue il protocollo scelto:

• Gli stream Responses restituiscono eventi di risposta compatibili con Responses.
• Gli stream Chat Completions restituiscono chunk di completamento chat compatibili con OpenAI.
• Gli stream Messages restituiscono eventi di messaggio compatibili con Anthropic.

const stream = await client.responses.create({
  model: "gpt-5.6-sol",
  input: "Write one sentence.",
  stream: true,
});

I client dovrebbero analizzare lo stream in base al protocollo che usano, invece di aspettarsi un unico schema di eventi condiviso tra tutti e tre gli endpoint.

Errori

La LLM API restituisce, quando possibile, la forma di errore del protocollo scelto. Le cause comuni includono: