Prima o poi, chi vuole costruire qualcosa con l'intelligenza artificiale — un assistente interno, uno script che riassume documenti, un bot — deve passare dalle API: chiamare un modello da codice, non dall'interfaccia web. Questa guida mostra come fare le prime chiamate in Python ai tre fornitori più usati — OpenAI (GPT), Anthropic (Claude) e Google (Gemini) — con esempi che funzionano, e come gestire streaming, «function calling», costi ed errori.

A chi serve, cosa otterrai, prerequisiti

È per chi sa un minimo di Python (non serve essere esperti) e vuole integrare un modello in un programma. Al termine saprai: ottenere le chiavi API dai tre provider, installare i rispettivi SDK ufficiali, fare una chiamata semplice, ricevere la risposta «in streaming», gestire una conversazione con più messaggi, far chiamare al modello una tua funzione, e tenere sotto controllo spesa ed errori. Prerequisiti: Python 3.9 o superiore, un editor o un notebook, e — importante — un metodo di pagamento sui portali dei provider (le API sono a consumo; quasi tutti offrono un piccolo credito iniziale o un piano gratuito limitato, ma vanno verificati al momento perché cambiano spesso).

Passo 1 - Ottenere le chiavi API

  • OpenAI: vai su platform.openai.com, sezione API keys, crea una nuova chiave (inizia con sk-). Copiala subito: non sarà più mostrata.
  • Anthropic: vai su console.anthropic.com, sezione API Keys, crea la chiave.
  • Google Gemini: vai su aistudio.google.com (Google AI Studio), «Get API key».

Non incollare mai le chiavi nel codice. Salvale in variabili d'ambiente, ad esempio in un file .env (da escludere dal controllo di versione):

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

Passo 2 - Installare gli SDK

pip install openai anthropic google-genai python-dotenv

All'inizio dei tuoi script carica le variabili:

from dotenv import load_dotenv
load_dotenv()

Passo 3 - La prima chiamata, con i tre provider

OpenAI (API chat completions, la più conosciuta):

from openai import OpenAI
client = OpenAI()  # legge OPENAI_API_KEY dall'ambiente
resp = client.chat.completions.create(
    model="gpt-5.5",  # controlla nella docs l'elenco aggiornato dei modelli
    messages=[
        {"role": "system", "content": "Sei un assistente che risponde in italiano, conciso."},
        {"role": "user", "content": "Spiega cos'è un'API in 3 frasi."}
    ]
)
print(resp.choices[0].message.content)

Anthropic (API messages):

import anthropic
client = anthropic.Anthropic()  # legge ANTHROPIC_API_KEY
msg = client.messages.create(
    model="claude-sonnet-4-6",  # usa l'id del modello più recente dalla console
    max_tokens=500,
    system="Sei un assistente che risponde in italiano, conciso.",
    messages=[{"role": "user", "content": "Spiega cos'è un'API in 3 frasi."}]
)
print(msg.content[0].text)

Google Gemini:

from google import genai
client = genai.Client()  # legge GOOGLE_API_KEY
resp = client.models.generate_content(
    model="gemini-2.5-flash",  # verifica le versioni disponibili (es. le Gemini 3.x)
    contents="Spiega cos'è un'API in 3 frasi, in italiano."
)
print(resp.text)

Risultato atteso da tutti e tre: tre frasi in italiano che descrivono un'API come un'interfaccia con cui due programmi si parlano secondo regole prefissate. Differenze da notare: OpenAI mette il messaggio di sistema dentro messages; Anthropic ha un parametro system separato e richiede max_tokens; Gemini ha un'interfaccia più sintetica con contents.

Passo 4 - Ricevere la risposta in streaming

Per mostrare il testo mentre viene generato (come fa ChatGPT), si usa lo streaming. Esempio con OpenAI:

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Scrivi una breve filastrocca sull'autunno."}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Con Anthropic si usa client.messages.stream(...) come context manager e si itera su text_stream; con Gemini c'è client.models.generate_content_stream(...). In tutti i casi il vantaggio è la reattività percepita: l'utente vede l'output comparire subito.

Passo 5 - Conversazioni con più turni

I modelli non «ricordano» nulla tra una chiamata e l'altra: la memoria sei tu a fornirla, rimandando l'intera lista di messaggi a ogni richiesta. Esempio (OpenAI):

history = [{"role": "system", "content": "Sei un tutor di matematica, spieghi in italiano."}]
def chiedi(testo):
    history.append({"role": "user", "content": testo})
    r = client.chat.completions.create(model="gpt-5.5", messages=history)
    risposta = r.choices[0].message.content
    history.append({"role": "assistant", "content": risposta})
    return risposta

print(chiedi("Cos'è una frazione?"))
print(chiedi("Fammi un esempio con la pizza."))

Attenzione: la cronologia cresce e con essa il numero di token (e il costo) di ogni chiamata. Quando diventa lunga, conviene riassumere i turni più vecchi o troncarli.

Passo 6 - Far chiamare al modello una tua funzione (function calling)

I modelli possono «decidere» di invocare funzioni che dichiari tu — per leggere un database, chiamare un servizio meteo, fare un calcolo. Tu descrivi la funzione, il modello restituisce il nome e gli argomenti, tu la esegui e gli rimandi il risultato. Esempio minimale con OpenAI:

tools = [{
  "type": "function",
  "function": {
    "name": "meteo_oggi",
    "description": "Restituisce il meteo di oggi per una città",
    "parameters": {"type": "object", "properties": {"citta": {"type": "string"}}, "required": ["citta"]}
  }
}]
r = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Che tempo fa a Bologna?"}],
    tools=tools,
)
call = r.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)  # -> meteo_oggi {"citta": "Bologna"}

A quel punto esegui davvero la tua funzione meteo_oggi("Bologna"), aggiungi il risultato ai messaggi (con ruolo tool) e richiami il modello, che produrrà la risposta finale in linguaggio naturale. Anthropic e Gemini hanno meccanismi equivalenti (rispettivamente i «tool use» nei messages e i «function declarations»).

Passo 7 - Tenere sotto controllo costi e limiti

  • Paghi a token (parti di parole) sia in input sia in output: prompt più brevi e max_tokens ragionevoli riducono la spesa.
  • Per la maggior parte dei compiti usa la variante «piccola/veloce» del modello (le versioni «mini»/«flash»): costano molto meno e spesso bastano. Tieni il modello grande per i casi difficili.
  • Imposta un tetto di spesa nei portali dei provider e tieni d'occhio i consumi nei primi giorni.
  • Gestisci i limiti di frequenza (rate limit) con un retry con attesa crescente: se ricevi un errore 429, aspetta qualche secondo e riprova, raddoppiando l'attesa a ogni tentativo.

Errori comuni e soluzioni

  • 401 / «Incorrect API key» → chiave assente, sbagliata o non caricata: verifica il .env e che load_dotenv() sia eseguito prima di creare il client.
  • 429 / «Rate limit exceeded» → troppe richieste o quota esaurita: rallenta, aggiungi retry con backoff, controlla il credito residuo.
  • «model not found» / 404 sul modello → il nome del modello non è valido o non è disponibile sul tuo account: consulta l'elenco aggiornato nella documentazione del provider.
  • 400 «max_tokens is required» (Anthropic) → aggiungi il parametro max_tokens: con Claude è obbligatorio.
  • Timeout o risposte tronche → aumenta il timeout del client e/o max_tokens; per output lunghi valuta lo streaming.

Sicurezza delle chiavi (da non dimenticare)

Mai mettere le chiavi nel codice sorgente, nei repository, nelle app lato browser o mobile (dove sono visibili a chiunque): tienile sul server, in variabili d'ambiente o in un gestore di segreti. Se una chiave finisce esposta, revocala subito dal portale e creane un'altra. Per applicazioni con più utenti, instrada le chiamate attraverso un tuo backend, così la chiave non lascia mai i tuoi server.

Quale provider scegliere come prima scelta

Non c'è un vincitore assoluto: dipende dal compito. Indicazioni pratiche: OpenAI è spesso la scelta più comoda per iniziare (ecosistema enorme, tanta documentazione, l'API chat completions è lo «standard de facto» che molti altri imitano, incluso Ollama); Anthropic (Claude) eccelle su ragionamento, scrittura lunga e attività di coding/agenti; Gemini è competitivo su multimodalità (immagini, video), contesti molto lunghi e integrazione con l'ecosistema Google. Suggerimento: scrivi il tuo codice in modo da poter cambiare provider con poche righe (un piccolo strato di astrazione), prova lo stesso compito su due o tre modelli e scegli su misura. E per i dati sensibili o per abbattere i costi, ricorda che puoi puntare lo stesso codice OpenAI a un modello locale via Ollama.