OpenRouter: una guida con esempi pratici

Gestire diverse API di provider di IA diventa presto frustrante. Ogni provider ha metodi di autenticazione, modelli di prezzo e specifiche API differenti. Gli sviluppatori finiscono per perdere ore a passare da OpenAI, Anthropic, Google e altre piattaforme solo per accedere a modelli diversi.

OpenRouter risolve questa complessità offrendo un'API unificata che ti collega a oltre 400 modelli di decine di provider. Puoi accedere a GPT-5, Claude 4, Gemini 2.5 Pro e a centinaia di altri modelli usando una singola chiave API e un'interfaccia coerente. La piattaforma gestisce automaticamente fallback, controllo dei costi e instradamento tra provider dietro le quinte.

In questo tutorial, ti spiego tutto quello che devi sapere su OpenRouter: dall'impostazione della tua prima chiamata API all'implementazione di funzionalità avanzate come gli output strutturati. Alla fine, saprai come creare applicazioni affidabili che non dipendono da un singolo provider.

Cos'è OpenRouter?

OpenRouter è una piattaforma con API unificata che ti dà accesso a oltre 400 modelli di IA di decine di provider tramite un singolo endpoint. Invece di gestire chiavi API separate per OpenAI, Anthropic, Google, Meta e altri, usi una sola chiave per raggiungere l'intero catalogo di modelli.

La piattaforma funziona come un router intelligente, inviando le tue richieste al provider giusto e occupandosi di autenticazione, fatturazione e gestione degli errori. Questo approccio risolve diversi problemi tipici dell'uso di più provider di IA.

Problemi che OpenRouter risolve

Lavorare con più provider di IA diventa presto caotico. Ognuno ha il suo formato API, il suo processo di login e il suo sistema di fatturazione. Finisci per mantenere codice separato per ogni servizio, rallentando lo sviluppo e rendendo faticoso testare nuovi modelli.

Le cose peggiorano quando i provider vanno giù o ti colpiscono con limiti di velocità. L'app si rompe e non puoi fare altro che aspettare. In più, capire quale provider offre il prezzo migliore per modelli simili significa monitorare i costi manualmente su piattaforme diverse.

Il problema più grande è rimanere bloccati con un solo provider. Se costruisci tutto attorno alla sua API specifica, passare in seguito a modelli migliori o più economici diventa un progetto a sé.

Come OpenRouter risolve tutto questo

OpenRouter affronta questi problemi con un set di funzionalità collegate tra loro:

• Una sola chiave API funziona con oltre 400 modelli di tutti i principali provider
• Passaggio automatico a provider di backup quando la prima scelta fallisce
• Prezzi affiancati per tutti i modelli, così confronti i costi all'istante
• Compatibile con il codice OpenAI esistente — ti basta cambiare l'URL dell'endpoint
• Monitoraggio in tempo reale che instrada le richieste al provider più veloce disponibile

Questi elementi lavorano insieme per rendere lo sviluppo con l'IA più semplice e affidabile.

Chi dovrebbe usare OpenRouter?

Tipi di utenti diversi traggono valore da questo approccio unificato:

• Gli sviluppatori possono provare nuovi modelli senza creare account ovunque, accelerando la sperimentazione
• I team enterprise ottengono l'uptime necessario grazie ai backup automatici quando i provider falliscono
• Chi ha budget limitati può trovare l'opzione più economica per le proprie esigenze senza fare acrobazie con i fogli di calcolo
• I ricercatori hanno accesso immediato ai modelli all'avanguardia senza l'onere di configurare account

Ora che hai capito cosa offre OpenRouter, vediamo come configurare la tua prima chiamata API.

Prerequisiti

Prima di tuffarti in OpenRouter, ti serve avere alcune cose pronte sulla tua macchina. Questo tutorial presuppone che tu abbia familiarità con la programmazione Python di base e abbia già lavorato con le API. Non serve essere esperti, ma dovresti conoscere concetti come inviare richieste HTTP e gestire risposte JSON.

Ti serve Python 3.7 o successivo installato sul sistema. Useremo il pacchetto Python openai per interagire con l'API di OpenRouter, insieme a python-dotenv per gestire in modo sicuro le variabili d'ambiente. Puoi installarli entrambi con:

pip install requests openai python-dotenv

Ti serviranno anche un account e una chiave API OpenRouter. Vai su openrouter.ai per creare un account gratuito — riceverai un piccolo credito per fare delle prove. Una volta effettuato l'accesso, vai alla sezione API Keys nelle impostazioni del tuo account e genera una nuova chiave.

Dopo aver ottenuto la chiave API, crea un file .env nella directory del progetto e aggiungi la chiave così:

OPENROUTER_API_KEY=your_api_key_here

In questo modo la chiave resta al sicuro e fuori dal codice. Se intendi usare OpenRouter oltre i test, dovrai aggiungere crediti al tuo account dalla pagina Credits.

Con queste basi a posto, sei pronto per effettuare la tua prima chiamata API tramite OpenRouter.

Effettuare la tua prima chiamata API in OpenRouter

Iniziare con OpenRouter è sorprendentemente semplice se hai già usato l'SDK di OpenAI. Ti basta cambiare una riga di codice e all'improvviso hai accesso a centinaia di modelli di provider diversi.

La tua prima richiesta e configurazione

Partiamo subito con un esempio funzionante che dimostra l'approccio di OpenRouter:

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

client = OpenAI(
   base_url="https://openrouter.ai/api/v1",
   api_key=os.getenv("OPENROUTER_API_KEY"),
)

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "Write a haiku about debugging code at 2 AM"
       }
   ]
)

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

Night hum, coffee cooled
cursor blinks, bug hides somewhere
I chase ghosts 'til dawn

La magia avviene in due punti. Primo, il parametro base_url reindirizza le richieste ai server di OpenRouter invece che a quelli di OpenAI. Secondo, il nome del modello segue il formato provider/model-name - openai/gpt-5-mini invece di gpt-5-mini. Questo indica a OpenRouter quale versione del provider vuoi usare mantenendo un'interfaccia familiare. Ecco alcuni modelli comuni che puoi inserire nell'esempio sopra senza errori:

• google/gemini-2.0-flash-001
• google/gemini-2.5-pro
• mistralai/mistral-nemo
• deepseek/deepseek-r1-distill-qwen-32b

Ora che hai visto quanto è semplice lavorare con modelli diversi, potresti chiederti: cosa succede quando il modello scelto non è disponibile? Come costruire applicazioni che restano affidabili anche se i provider hanno problemi? È qui che entrano in gioco le funzionalità di routing e resilienza di OpenRouter.

Instradamento dei modelli per la resilienza

Costruire applicazioni di IA affidabili significa prepararsi all'imprevisto. I provider possono avere downtime, i modelli raggiungono i limiti di rate e a volte la moderazione dei contenuti blocca le richieste. Il model routing è la soluzione di OpenRouter — passa automaticamente tra modelli diversi per mantenere l'applicazione fluida.

Impostare fallback manuali

Il modo più semplice per aggiungere resilienza è specificare modelli di backup. Quando la tua scelta primaria fallisce, OpenRouter prova le alternative in ordine. Il parametro extra_body passa queste istruzioni di routing all'API di OpenRouter poiché l'SDK di OpenAI non supporta nativamente questa funzione:

response = client.chat.completions.create(
   model="moonshotai/kimi-k2",  # Primary choice
   messages=[
       {"role": "user", "content": "Explain quantum computing in simple terms"}
   ],
   extra_body={
       "models": ["anthropic/claude-sonnet-4", "deepseek/deepseek-r1"]
   }   
)

print(f"Response from: {response.model}")
print(response.choices[0].message.content)

Response from: moonshotai/kimi-k2
Imagine a normal computer bit as a tiny light-switch that can only be OFF (0) or ON (1)...

OpenRouter prova prima Kimi-K2. Se non è disponibile, è limitato o bloccato, prova automaticamente Claude Sonnet 4, poi DeepSeek R1. Il campo response.model mostra quale modello ha effettivamente risposto.

Auto router per la massima comodità

Una volta compresi i fallback manuali, l'auto router diventa davvero interessante. Gestisce automaticamente selezione dei modelli e fallback, grazie al sistema di valutazione di NotDiamond:

response = client.chat.completions.create(
   model="openrouter/auto",
   messages=[
       {"role": "user", "content": "Debug this Python code in 3 sentences: def factorial(n): return n * factorial(n-1)"}
   ]
)

print(f"Auto router selected: {response.model}")
print(response.choices[0].message.content)

Auto router selected: openai/chatgpt-4o-latest
The given code is missing a base case, which causes infinite recursion and eventually a RecursionError. To fix it, add a base case like `if n == 0: return 1` before the recursive call. Here's the corrected version:

\```python
def factorial(n):
   if n == 0:
       return 1
   return n * factorial(n - 1)
\```

L'auto router analizza il tuo prompt e sceglie il miglior modello disponibile, con fallback integrati se la prima scelta non è disponibile. Ottieni resilienza senza configurazione. Tuttavia, usa l'auto-router con cautela in scenari sensibili o di alto profilo, perché tende a sottovalutare la complessità del problema e quindi a scegliere un modello di capacità inferiore.

Costruire strategie di fallback efficaci

Non tutti i modelli sono buoni backup l'uno per l'altro. I downtime dei provider possono colpire tutti i modelli di quella stessa azienda, quindi scegli fallback di provider diversi. I limiti di rate e i costi variano molto, quindi abbina modelli costosi ad alternative più economiche:

# Good fallback chain: different providers, decreasing cost
response = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=[
       {"role": "user", "content": "Your prompt here"}
   ],
   extra_body={
       "models": [
           "x-ai/grok-4",                  # Close performance
           "moonshotai/kimi-k2",           # Cheaper
           "deepseek/deepseek-r1:free"     # Free backup
       ]
   }   
)

Questo ti dà qualità premium quando disponibile, buone prestazioni come backup e disponibilità garantita come ultima risorsa. Anche le policy di moderazione dei contenuti differiscono tra provider, quindi diversificare la catena offre una copertura migliore per argomenti delicati.

Trovare modelli per la tua catena di fallback

La pagina dei modelli ti consente di filtrare per provider e funzionalità per costruire la tua catena. Molti modelli potenti come DeepSeek R1 e Kimi-K2 sono gratuiti perché open-source, e sono ottimi fallback. I modelli gratuiti hanno limiti di 50 richieste al giorno per i nuovi utenti, o 1000 richieste al giorno se hai acquistato 10 crediti.

Per applicazioni dinamiche, puoi scoprire modelli in modo programmatico:

def get_provider_models(api_key: str, provider: str) -> list[str]:
   r = requests.get(
       "https://openrouter.ai/api/v1/models",
       headers={"Authorization": f"Bearer {api_key}"}
   )
   return [m["id"] for m in r.json()["data"] if m["id"].startswith(provider)]

# Build fallbacks across providers
openai_models = get_provider_models(api_key, "openai/")
anthropic_models = get_provider_models(api_key, "anthropic/")

Questo approccio ti permette di costruire catene di fallback robuste che si adattano man mano che diventano disponibili nuovi modelli.

Streaming per risposte in tempo reale

Quando lavori con modelli di IA, soprattutto per risposte lunghe, gli utenti si aspettano di vedere l'output apparire progressivamente invece di attendere la risposta completa. Lo streaming risolve questo problema inviando porzioni di risposta man mano che vengono generate, creando un'esperienza più interattiva simile all'interfaccia di ChatGPT.

Configurazione di base dello streaming

Per attivare lo streaming in OpenRouter, aggiungi stream=True alla richiesta. La risposta diventa un iteratore che produce chunk mentre il modello li genera:

response = client.chat.completions.create(
   model="openai/gpt-5",
   messages=[
       {"role": "user", "content": "Write a detailed explanation of how neural networks learn"}
   ],
   stream=True
)

for chunk in response:
   if chunk.choices[0].delta.content is not None:
       print(chunk.choices[0].delta.content, end="")

Ogni chunk contiene un piccolo pezzo della risposta. Il campo delta.content contiene il nuovo frammento di testo, e lo stampiamo subito senza andare a capo per creare l'effetto streaming. Il parametro end="" impedisce a print di aggiungere nuove righe tra i chunk.

Creare un handler di streaming migliore

Per applicazioni in produzione, vorrai più controllo sul processo di streaming. Ecco un handler più completo che gestisce la risposta completa:

def stream_response(model, messages, show_progress=True):
   response = client.chat.completions.create(
       model=model,
       messages=messages,
       stream=True
   )
  
   complete_response = ""
  
   for chunk in response:
       if chunk.choices[0].delta.content is not None:
           content = chunk.choices[0].delta.content
           complete_response += content
          
           if show_progress:
               print(content, end="", flush=True)
  
   if show_progress:
       print()  # Add final newline
  
   return complete_response

# Use it with different models
result = stream_response(
   "anthropic/claude-sonnet-4",
   [{"role": "user", "content": "Explain quantum entanglement like I'm 12 years old"}]
)

Questo handler cattura la risposta completa mentre mostra l'avanzamento, offrendoti sia l'esperienza in streaming sia il testo finale, con una formattazione dell'output corretta.

Lo streaming trasforma l'esperienza utente da “aspettare e sperare” a “vedere i progressi in tempo reale”. Le tue applicazioni di IA risultano molto più reattive e coinvolgenti.

Gestire i reasoning tokens in OpenRouter

Alcuni modelli di IA possono mostrarti il loro “ragionamento” prima di fornire la risposta finale. Questi reasoning tokens offrono uno sguardo trasparente su come il modello affronta problemi complessi, mostrando la logica passo per passo che porta alle conclusioni. Capire questo ragionamento interno ti aiuta a verificare le risposte, fare debug del comportamento del modello e costruire applicazioni più affidabili.

Cosa sono i reasoning tokens

I reasoning tokens compaiono in un campo separato reasoning nella risposta, distinto dal contenuto principale. I modelli supportano il reasoning in modi diversi — alcuni usano livelli di effort, altri budget di token. 

Ecco un semplice esempio che mostra il reasoning in azione:

response = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=[
       {"role": "user", "content": "How many 'r's are in the word 'strrawberry'?"}
   ],
   max_tokens=2048,
   extra_body={
       "reasoning": {
           "max_tokens": 512
       }
   }
)

print("Final answer:")
print(response.choices[0].message.content)
print("\nReasoning process:")
print(response.choices[0].message.reasoning)

Final answer:
To count the 'r's in 'strrawberry', I'll go through each letter:
...
There are **4** 'r's in the word 'strrawberry'.

Reasoning process:
...

Il modello mostrerà sia la risposta finale sia il ragionamento interno che l'ha generata. Questo doppio output ti aiuta a capire se il modello ha affrontato correttamente il problema.

Controllare l'intensità del reasoning

Puoi controllare quanta energia di reasoning i modelli dedicano alle risposte in due modi. Il parametro effort funziona con modelli come la serie o di OpenAI e usa livelli che corrispondono a percentuali specifiche di token basate sul tuo max_tokens:

• High effort: usa circa l'80% di max_tokens per il reasoning
• Medium effort: usa circa il 50% di max_tokens per il reasoning
• Low effort: usa circa il 20% di max_tokens per il reasoning

# High effort reasoning for complex problems
response = client.chat.completions.create(
   model="deepseek/deepseek-r1",
   messages=[
       {"role": "user", "content": "Solve this step by step: If a train travels 240 miles in 3 hours, then speeds up by 20 mph for the next 2 hours, how far does it travel total?"}
   ],
   max_tokens=4000,  # High effort will use ~3200 tokens for reasoning
   extra_body={
       "reasoning": {
           "effort": "high" 
       }
   }
)

print("Problem solution:")
print(response.choices[0].message.content)
print("\nStep-by-step reasoning:")
print(response.choices[0].message.reasoning)

Per i modelli che supportano l'allocazione diretta dei token, come quelli di Anthropic, puoi specificare budget di reasoning esatti:

def get_reasoning_response(question, reasoning_budget=2000):
   response = client.chat.completions.create(
       model="anthropic/claude-sonnet-4",
       messages=[{"role": "user", "content": question}],
       max_tokens=10000,
       extra_body={
           "reasoning": {
               "max_tokens": reasoning_budget  # Exact token allocation
           }
       }
   )
   return response

# Compare different reasoning budgets
response = get_reasoning_response(
   "What's bigger: 9.9 or 9.11? Explain your reasoning carefully.",
   reasoning_budget=3000
)

print("Answer:", response.choices[0].message.content)
print("Detailed reasoning:", response.choices[0].message.reasoning)

Budget di token più alti in genere producono un reasoning più accurato e approfondito, mentre budget più bassi danno processi di pensiero più rapidi ma meno dettagliati.

Preservare il reasoning nelle conversazioni

Quando crei conversazioni multi-turn, devi preservare sia il reasoning sia la risposta finale per mantenere il contesto. Questo è particolarmente importante nelle discussioni complesse in cui il processo di pensiero del modello influisce sulle risposte successive:

# First message with reasoning
response = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=[
       {"role": "user", "content": "Should I invest in renewable energy stocks? Consider both risks and opportunities."}
   ],
   extra_body={
       "reasoning": {
           "max_tokens": 3000
       }
   }
)

# Build conversation history with reasoning preserved
messages = [
   {"role": "user", "content": "Should I invest in renewable energy stocks? Consider both risks and opportunities."},
   {
       "role": "assistant",
       "content": response.choices[0].message.content,
       "reasoning_details": response.choices[0].message.reasoning_details  # Preserve reasoning
   },
   {"role": "user", "content": "What about solar energy specifically? How does that change your analysis?"}
]

# Continue conversation with reasoning context
follow_up = client.chat.completions.create(
   model="anthropic/claude-sonnet-4",
   messages=messages,
   extra_body={
       "reasoning": {
           "max_tokens": 2000
       }
   }
)

print("Follow-up answer:")
print(follow_up.choices[0].message.content)
print("\nContinued reasoning:")
print(follow_up.choices[0].message.reasoning)

Il campo reasoning_details conserva la catena completa del reasoning, permettendo al modello di basarsi sulla propria analisi precedente quando risponde alle domande successive. Questo crea conversazioni più coerenti e consapevoli del contesto.

Considerazioni su costi e fatturazione

I reasoning tokens sono fatturati come token di output, quindi aumentano i costi di utilizzo. Tuttavia spesso migliorano abbastanza la qualità da giustificare la spesa, soprattutto per compiti complessi in cui la precisione conta più della velocità. Secondo la documentazione di OpenRouter, i reasoning tokens possono migliorare le prestazioni dei modelli su problemi difficili fornendo al contempo trasparenza nel processo decisionale.

Per applicazioni attente ai costi, puoi bilanciare qualità del reasoning e spesa regolando i livelli di effort o i budget di token in base alla complessità del compito. Domande semplici potrebbero non richiedere affatto reasoning, mentre problemi complessi beneficiano di un reasoning ad alto effort.

Lavorare con modelli multimodali in OpenRouter

Finora hai lavorato con il testo, ma cosa succede quando devi analizzare immagini o documenti? Magari vuoi fare domande su un grafico, estrarre informazioni da un PDF o descrivere cosa avviene in una foto. È qui che entrano in gioco i modelli multimodali — capiscono sia testo sia contenuti visivi nella stessa richiesta.

Capire le capacità multimodali

Invece di provare a descrivere un'immagine a parole, puoi inviare direttamente l'immagine e fare domande su di essa. Le tue applicazioni diventano molto più intuitive, perché il modello vede esattamente ciò con cui stai lavorando. Non devi indovinare se la tua descrizione testuale ha catturato tutti i dettagli importanti.

Usi i modelli multimodali tramite la stessa interfaccia che hai già utilizzato, solo con un parametro aggiuntivo attachments per includere i contenuti visivi. Gli allegati file funzionano con tutti i modelli su OpenRouter. Anche se un modello non supporta nativamente PDF o immagini, OpenRouter li analizza internamente e passa il contenuto al modello.

Lavorare con le immagini

Puoi includere immagini nelle richieste tramite URL o codifica base64. Se l'immagine è già online, usare l'URL è più semplice:

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "What's happening in this image? Describe the scene in detail."
       }
   ],
   extra_body={
       "attachments": [
           {
               "type": "image/jpeg",
               "url": "https://example.com/photo.jpg"
           }
       ]
   }
)

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

Per immagini locali, puoi usare la codifica base64:

import base64

def encode_image_to_base64(image_path):
   with open(image_path, "rb") as image_file:
       encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
   return encoded_string

# Analyze a local screenshot
encoded_image = encode_image_to_base64("screenshot.png")

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "This is a screenshot of a data dashboard. What insights can you extract from the charts and metrics shown?"
       }
   ],
   extra_body={
       "attachments": [
           {
               "type": "image/png",
               "data": encoded_image
           }
       ]
   }
)

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

Il modello esaminerà l'immagine reale e ti darà insight specifici su ciò che vede, non solo risposte generiche.

Elaborare documenti PDF

L'elaborazione dei PDF funziona allo stesso modo ma apre all'analisi dei documenti. Puoi fare domande su report, analizzare moduli o estrarre informazioni da documenti complessi:

def encode_pdf_to_base64(pdf_path):
   with open(pdf_path, "rb") as pdf_file:
       encoded_string = base64.b64encode(pdf_file.read()).decode('utf-8')
   return encoded_string

# Analyze a research paper
encoded_pdf = encode_pdf_to_base64("research_paper.pdf")

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {
           "role": "user",
           "content": "Summarize the key findings from this research paper. What are the main conclusions and methodology used?"
       }
   ],
   extra_body={
       "attachments": [
           {
               "type": "application/pdf",
               "data": encoded_pdf
           }
       ]
   }
)

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

Questo è ottimo per report finanziari, articoli accademici, contratti o qualsiasi PDF in cui ti serve l'analisi del contenuto effettivo. Puoi anche includere più allegati in una singola richiesta se devi confrontare immagini o analizzare più documenti insieme.

Costi e scelta del modello

Le richieste multimodali costano più di quelle solo testuali perché elaborano tipi di dati aggiuntivi. Immagini e PDF richiedono più potenza computazionale, e questo si riflette nel prezzo. Puoi controllare il pricing multimodale specifico di ogni modello sulla pagina dei modelli.

Modelli diversi hanno punti di forza differenti con i contenuti visivi. Alcuni sono migliori nell'analisi dettagliata delle immagini, altri eccellono nella comprensione dei documenti. Ti conviene sperimentare con modelli diversi per trovare quello più adatto alle tue esigenze e al tuo budget.

Usare output strutturati

Quando costruisci applicazioni reali, ti servono formati di dati prevedibili che il tuo codice possa analizzare in modo affidabile. Le risposte in testo libero sono ottime per le chat, ma pessime per applicazioni che devono estrarre informazioni specifiche. Invece di ricevere testo imprevedibile da analizzare con regex o sperare che il modello formatti correttamente, gli output strutturati obbligano i modelli a restituire JSON garantito con esattamente i campi e i tipi di dato che ti servono. Questo elimina gli errori di parsing e semplifica molto il codice dell'applicazione.

Anatomia delle richieste di output strutturati

Gli output strutturati usano un parametro response_format con questa struttura di base:

"response_format": {
   "type": "json_schema",           # Always this for structured outputs
   "json_schema": {
       "name": "your_schema_name",  # Name for your schema
       "strict": True,              # Enforce strict compliance
       "schema": {
           # Your actual JSON schema definition goes here
       }
   }
}

Esempio di analisi del sentiment

Vediamo un esempio completo che estrae il sentiment dal testo. Questo mostra come funzionano gli output strutturati nella pratica:

response = client.chat.completions.create(
   model="openai/gpt-5-mini",
   messages=[
       {"role": "user", "content": "Analyze the sentiment: 'This movie was absolutely terrible!'"}
   ],
   extra_body={
       "response_format": {
           "type": "json_schema",
           "json_schema": {
               "name": "sentiment_analysis",
               "strict": True,
               "schema": {
                   "type": "object",
                   "properties": {
                       "sentiment": {"type": "string", "enum": ["positive", "negative", "neutral"]},
                       "confidence": {"type": "number"}
                   },
                   "required": ["sentiment", "confidence"]
               }
           }
       }
   }
)

import json
result = json.loads(response.choices[0].message.content)
print(result)

{'sentiment': 'negative', 'confidence': 0.98}

Ecco cosa succede in questo schema:

• sentiment: un campo stringa limitato a tre valori specifici tramite enum. Il modello non può restituire nulla al di fuori di "positive", "negative" o "neutral"
• confidence: un campo numerico per il punteggio di confidenza del modello
• required: entrambi i campi devono essere presenti nella risposta - il modello non può ometterli
• strict: True: impone il rispetto rigoroso della struttura dello schema

Senza output strutturati, potresti ricevere risposte tipo “Il sentiment è molto negativo con alta confidenza” o “Negativo (95% sicuro)”. Con lo schema, invece, ottieni sempre JSON analizzabile che puoi usare subito nel tuo codice.

Impostare strict: True fa rispettare lo schema in modo rigido — il modello non può deviare dalla tua struttura. L'array required specifica quali campi devono essere presenti. Puoi usare enum per limitare i valori a scelte specifiche, array per liste e tipi object annidati per dati complessi.

Compatibilità dei modelli

Non tutti i modelli supportano gli output strutturati, ma la maggior parte di quelli moderni sì. Puoi controllare la pagina dei modelli per la compatibilità. Quando un modello non supporta nativamente gli output strutturati, spesso OpenRouter gestisce internamente la formattazione.

Gli output strutturati trasformano le risposte dell'IA da testo imprevedibile a dati affidabili su cui le tue applicazioni possono contare. Per qualsiasi caso d'uso in produzione che richieda estrazione di dati coerente, questa funzione è essenziale.

Conclusione

Abbiamo visto come accedere a centinaia di modelli di IA tramite l'API unificata di OpenRouter, dalla prima richiesta fino a funzionalità come streaming, reasoning tokens e output strutturati.

I fallback automatici e l'instradamento dei modelli fanno sì che le tue applicazioni restino affidabili anche quando i singoli provider hanno problemi. Con gli stessi pattern di codice, possiamo confrontare modelli, cambiare provider e trovare la soluzione perfetta per ogni task senza gestire più chiavi API.

Inizia sperimentando con richieste semplici e prova gradualmente più funzionalità man mano che crescono le tue esigenze. Testa modelli diversi per compiti diversi — alcuni funzionano meglio per la scrittura creativa, altri sono più forti nell'analisi dei dati o nei problemi di ragionamento.

Le conoscenze che hai acquisito qui ti danno ciò che serve per creare applicazioni di IA non legate a un singolo provider, lasciandoti la libertà di adattarti man mano che arrivano nuovi modelli e funzionalità.