Prima richiesta da Google Colab: conserva la chiave API in Secrets

Puoi eseguire la tua prima richiesta in un notebook Colab senza installare nulla sul tuo computer. Salva la chiave in Colab Secrets, leggila con userdata.get(...), punta il pacchetto openai su https://api.cheaptokens.dev/v1 e stampa choices[0].message.content e usage. La chiave non risiede mai in una cella, quindi condividere il notebook non significa condividere la tua chiave.

Quest'ultimo punto è il motivo per cui vale la pena. Supponi di finire il notebook e di inviare il link a un compagno di corso. Se la chiave è incollata in una cella, ora ce l'ha anche lui. Se risiede in Secrets, riceve il codice e nient'altro.

Questa guida si basa su la prima richiesta con requests semplice. Qui l'unica novità è dove risiede la chiave e come un notebook la legge. Per la stessa idea su un laptop, vedi memorizzare una chiave in una variabile d'ambiente.

Cosa ti serve#

• Un account Google e un nuovo notebook su colab.research.google.com.
• Una chiave API CheapTokens e un saldo ricaricato. Chiavi e saldo sono nel tuo account; la documentazione mostra i passaggi esatti.
• Cinque minuti.

L'API è compatibile con OpenAI Chat Completions, quindi il pacchetto Python openai standard funziona con un base_url diverso. Il README di openai-python (verificato il 5 novembre 2026) indica Python 3.10 o superiore e pip install openai.

Inserisci la chiave in Colab Secrets#

Nella barra laterale sinistra del notebook c'è un'icona a forma di chiave, che apre il pannello Secrets. Aggiungi un nuovo secret, chiamalo CHEAPTOKENS_KEY, incolla la tua chiave come valore e attiva l'accesso al notebook per il notebook su cui stai lavorando. Il testo dei pulsanti può cambiare, quindi cerca l'icona a forma di chiave invece di un percorso di menu.

Scegli ora il nome che vuoi: è la stringa che passerai al codice. Un nome sbagliato è un errore facile da commettere, e la sezione sugli errori mostra come si presenta.

Esegui la prima richiesta#

Colab legge i secret con google.colab.userdata.get(name), una funzione nel modulo colabtools di Google (docstring verificate il 5 novembre 2026). Installa l'SDK, leggi il secret, invia una richiesta.

!pip install -q openai

from google.colab import userdata
from openai import OpenAI

client = OpenAI(
    api_key=userdata.get('CHEAPTOKENS_KEY'),
    base_url='https://api.cheaptokens.dev/v1',
)

resp = client.chat.completions.create(
    model='deepseek-ai/DeepSeek-V4-Flash-0731',
    messages=[{'role': 'user', 'content': 'Explain a token in one sentence.'}],
    max_tokens=200,
)
print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

Il primo print mostra la risposta del modello. Il secondo stampa due numeri: i token inviati e i token scritti dal modello. È l'intero costo della richiesta, ed è per questo che lo stampiamo ogni volta.

Quanto costa la richiesta#

I token sono ciò per cui paghi, quindi guarda la seconda riga dell'output. Supponi che una domanda breve come quella sopra usi circa 40 token in ingresso e che la risposta sia di 150 token in uscita. Quella richiesta costa $0.000016 al prezzo attuale, e mille di esse costano $0.0156. Sostituisci 40 e 150 con i due numeri stampati dal tuo notebook.

DeepSeek-V4-Flash è il default qui per un motivo: contesto da 380K, fino a 32.768 token di output per risposta e un unico prezzo a qualsiasi ora del giorno, senza fasce di punta. Un saldo copre ogni modello, quindi puoi cambiare il modello in questa cella senza modificare altro. Prova zai-org/GLM-5.3-Flash (contesto da 390K, fino a 8.192 token di output) ed esegui di nuovo la cella. Vedi tutti i modelli e i prezzi per l'elenco completo.

Quando una cella fallisce#

Gli errori dal lato dei secret arrivano per primi, prima che qualsiasi richiesta lasci Colab. Il codice sorgente di colabtools (verificato il 5 novembre 2026) dice che userdata.get può sollevare tre errori.

• SecretNotFoundError: non esiste alcun secret con quel nome. Confronta la stringa in userdata.get('...') con il nome nel pannello Secrets, lettera per lettera. Maiuscole e minuscole contano.
• NotebookAccessError: il secret esiste, ma questo notebook non ha accesso. Attiva l'interruttore di accesso nel pannello Secrets ed esegui di nuovo la cella.
• TimeoutException: Colab non ha risposto alla richiesta del secret. Il messaggio di errore dice che i secret possono essere recuperati solo quando il codice viene eseguito dall'interfaccia di Colab, quindi esegui la cella nel notebook Colab stesso, non in uno script esportato.

Se il secret si carica e la richiesta fallisce comunque, il problema è sul lato API. Un 401 significa che la chiave è sbagliata o mancante; un 404 di solito indica un base URL o un id del modello errato. API 401 o 404: chiave, base URL, id del modello analizza entrambi i casi, e elencare i modelli con GET /v1/models mostra come copiare l'id esatto.

Condivisione e rotazione#

Condividi il notebook e il codice che chiama userdata.get va con esso; la chiave non è in nessuna cella né output, quindi non c'è nulla da esporre. Chi apre il notebook ha bisogno del proprio secret con lo stesso nome, altrimenti ottiene SecretNotFoundError (vedi sopra).

Se crei una nuova chiave, aggiorna il valore nel pannello Secrets; il codice resta lo stesso perché nomina solo il secret.

Un'abitudine resta comunque importante: non stampare mai la chiave. Una cella come print(userdata.get('CHEAPTOKENS_KEY')) la mette nell'output, e gli output vengono salvati con il notebook.

Prossimo passo: metti la risposta in un ciclo, in una chat o in un piccolo strumento. La documentazione copre il resto dell'API.