Prima richiesta in Ruby con la gem openai: base_url, chiave, usage

Sì, la gem ufficiale openai funziona con CheapTokens: passa base_url: "https://api.cheaptokens.dev/v1" e la tua chiave a OpenAI::Client.new, chiama client.chat.completions.create e leggi il testo da choices.first.message.content. Il resto di questa pagina è lo script completo, come leggere ciò che torna indietro e cosa controllare quando non funziona.

Immagina di avere un rake task che etichetta i ticket di supporto, o un job in background che riassume una nota prima di salvarla. Vuoi l'SDK ufficiale, non HTTP scritto a mano, e vuoi vedere quanti token ha usato ogni chiamata. Questo script fa esattamente questo.

Cosa ti serve prima di iniziare#

La pagina della gem su RubyGems (verificata l'8 novembre 2026) riporta openai 0.120.0, rilasciata il 5 novembre 2026, Apache-2.0. Richiede Ruby 3.3.0 o superiore; se sei bloccato su Ruby 3.2, le note della gem stessa rimandano alla linea 0.75.x. Il pacchetto è ancora 0.x e si muove veloce, quindi fissa la versione.

Nel tuo Gemfile:

gem "openai", "~> 0.120.0"

Poi bundle install. Senza Bundler, gem install openai -v 0.120.0 fa lo stesso.

Ti serve anche una chiave API dal tuo account CheapTokens. Tienila fuori dal codice: mettila in una variabile d'ambiente e, se la parola .gitignore è nuova per te, questa guida su come tenere al sicuro le chiavi è una lettura da cinque minuti.

export CHEAPTOKENS_API_KEY="sk-your-key"

Lo script#

Crea ask.rb:

require "openai"

client = OpenAI::Client.new(
  api_key: ENV.fetch("CHEAPTOKENS_API_KEY"),
  base_url: "https://api.cheaptokens.dev/v1"
)

completion = client.chat.completions.create(
  model: "deepseek-ai/DeepSeek-V4-Flash-0731",
  messages: [
    { role: "user", content: "Explain in one sentence what a token is." }
  ]
)

choice = completion.choices.first
puts choice.message.content
puts "finish_reason: #{choice.finish_reason}"
puts completion.usage

Eseguito con ruby ask.rb. Tre cose meritano un secondo sguardo.

ENV.fetch invece di ENV[...]. Se la variabile manca, fetch si ferma subito con un KeyError che la nomina. ENV[...] passa silenziosamente nil e ottieni un errore di autenticazione confuso qualche riga dopo.

base_url: è l'unica riga che differisce dagli esempi OpenAI nel README della gem. Tutto il resto è lo stesso codice, che è esattamente il punto di un'API compatibile con OpenAI. Se l'idea è nuova, cos'è base_url e come cambiarlo lo spiega con l'analogia del ristorante.

L'id del modello è quello completo, deepseek-ai/DeepSeek-V4-Flash-0731. Il nome breve di una tabella prezzi non è accettato dall'API; prendi gli id dalla documentazione CheapTokens o da GET /v1/models.

Leggere ciò che torna indietro#

La risposta è un oggetto, non un hash, quindi chiami metodi su di esso. Il testo si trova in completion.choices.first.message.content; è il percorso usato anche dal README della gem.

Altre due righe meritano di essere stampate fin dal primo giorno:

• finish_reason ti dice perché il modello si è fermato. stop è una fine normale. length significa che un limite di lunghezza ha interrotto la risposta. Se ti capita, perché le risposte vengono troncate e come risolvere.
• usage contiene i token fatturati per la chiamata: quelli che hai inviato e quelli che il modello ha scritto. Lo script stampa l'intero oggetto con puts completion.usage, così vedi entrambi i numeri come li ha restituiti l'API.

Perché registrarli? Perché i token sono la bolletta. Una domanda di una frase con una risposta di una frase è poca cosa, ma un job che gira mille volte al giorno no. Token di input vs output spiega perché il secondo numero di solito costa di più per token.

Quanto costa una chiamata così#

DeepSeek-V4-Flash su CheapTokens costa $0.015 per 1M token di input e $0.10 per 1M token di output, con lo stesso prezzo a qualsiasi ora del giorno. Prendi un job di etichettatura ticket: circa 300 token in input, 150 token in output per ticket. Un ticket costa $0.00002. Mille ticket si presentano così, con il prezzo di riferimento di OpenRouter nella colonna accanto:

Il modello supporta fino a 380K token di contesto e fino a 32.768 token in una singola risposta, quindi un job di riassunto raramente sbatte contro un muro. Se preferisci provare un secondo modello con lo stesso script, cambia solo la stringa model: in zai-org/GLM-5.3-Flash (390K di contesto, fino a 8.192 token di output).

Se non funziona#

La maggior parte dei fallimenti al primo avvio è uno di cinque casi. Scegli quello che corrisponde al tuo schermo.

I casi 401 e 404 si presentano con ogni SDK, non solo con Ruby; API 401 o 404: chiave, base URL o id del modello sbagliati li affronta in ordine.

Dove andare adesso#

Ora hai il ciclo utile più piccolo: invia, leggi il testo, registra i token. Da qui, avvolgi la chiamata in un metodo e aggiungi i numeri usage al tuo logger. Lo stesso schema esiste in altri linguaggi se il tuo stack è misto: Go, Java e C#. L'elenco completo di modelli e prezzi è nella pagina dei modelli, e il riferimento API è nella documentazione.