Chiamare Gemini con l’OpenAI SDK: tutorial di integrazione modificando solo base_url, API Key e nome del modello

Google lo dice senza giri di parole: i Gemini models sono accessibili tramite gli SDK Python e TypeScript/JavaScript di OpenAI, e in sostanza basta modificare tre righe di codice. L’endpoint indicato dalla documentazione ufficiale di compatibilità è https://generativelanguage.googleapis.com/v1beta/openai/, e il modello di esempio è gemini-3.5-flash (Compatibilità OpenAI di Google). Per i progetti che usano già l’SDK OpenAI è molto comodo: non serve smontare subito l’astrazione del provider, né sostituire l’intero stack di chiamata; prima lo fai funzionare, poi si vede.

Prima verifica quale modello vuoi chiamare

Al 2026-06-14, la pagina dei modelli Google elenca Gemini 3.5 Flash come Stable e specifica che il codice del modello è gemini-3.5-flash; questo modello ha un limite di input di 1.048.576 token, un limite di output di 65.536 token, supporta input di testo, immagini, video, audio e PDF, e produce output testuale (Gemini 3.5 Flash). La pagina del modello è stata aggiornata l’ultima volta il 2026-05-19 UTC.

Anche i prezzi vanno verificati nella documentazione del giorno. La pagina dei prezzi Google è stata aggiornata l’ultima volta il 2026-06-09 UTC; per il tier Standard paid, gemini-3.5-flash è indicato a $1.50 / 1M tokens per l’input e $9.00 / 1M tokens per l’output, con il prezzo di output che include i thinking tokens; per Batch, input $0.75 e output $4.50 (Prezzi Gemini API).

Modello	Stato	Limite di input	Input Standard	Output Standard
gemini-3.5-flash	Stable	1,048,576	$1.50 / 1M tokens	$9.00 / 1M tokens
gemini-3-flash-preview	Preview	vedi pagina del modello	$0.50 / 1M tokens	$3.00 / 1M tokens
gemini-3.1-flash-lite	Stable	vedi pagina del modello	$0.25 / 1M tokens	$1.50 / 1M tokens

gemini-3-flash-preview e gemini-3.1-flash-lite provengono dalle pagine correnti dei modelli e dei prezzi di Google (Modelli, Prezzi). Non usare direttamente un modello Preview come valore predefinito in produzione: versioni e limiti possono cambiare.

Python: punta il client OpenAI verso Gemini

Prima installa l’SDK:

pip install openai
export GEMINI_API_KEY="你的 Gemini API Key"

Poi mantieni lo stesso modo di chiamare l’SDK OpenAI:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {"role": "system", "content": "你是一个简洁的工程助手。"},
        {"role": "user", "content": "用三句话解释什么是 API 兼容层。"},
    ],
)

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

Le modifiche reali sono solo tre: sostituire api_key con la key di Gemini, sostituire base_url con l’endpoint OpenAI-compatible di Google, e sostituire model con il nome del modello Gemini. Nota che nell’esempio ufficiale l’URL termina con /: evita di cancellarlo per poi perdere tempo a fare debug di un 404.

TypeScript: anche qui si tratta di baseURL

In un progetto Node è lo stesso:

npm install openai
export GEMINI_API_KEY="你的 Gemini API Key"

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const response = await openai.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "user", content: "给我一个 JSON Schema 校验的最小例子。" },
  ],
});

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

Se il tuo progetto ha già incapsulato il provider in variabili d’ambiente, la modifica sarà ancora più piccola:

OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
OPENAI_API_KEY="$GEMINI_API_KEY"
OPENAI_MODEL="gemini-3.5-flash"

La trappola in molti vecchi progetti è qui: non importa se la variabile si chiama ancora OPENAI_API_KEY, il valore può essere una key Gemini; ciò che determina davvero dove va la richiesta è base_url/baseURL.

Streaming, tool calling e thinking: come gestirli

La documentazione di compatibilità di Google fornisce esempi di streaming, function calling, structured outputs, image understanding e altro (Compatibilità OpenAI). In genere, per un progetto che usa già l’SDK OpenAI conviene verificare prima tre cose: chat ordinaria, stream=True e tools/function calling. Una volta superati questi test, si passa alle capacità specifiche del modello.

I parametri di thinking vanno trattati con cautela. La documentazione di compatibilità dice che reasoning_effort di OpenAI viene mappato sulla configurazione di thinking di Gemini; tuttavia Gemini 3 e alcuni modelli 2.5 non permettono di disattivare completamente il thinking. Il mio consiglio è semplice: nella prima versione non toccare il thinking; usa i valori predefiniti per stabilire una baseline di qualità e costo, poi fai benchmark separati su task lunghi, agenti di codice e pipeline di ragionamento complesse.

Se vuoi gestire meno set di key

La connessione diretta ufficiale è adatta alla produzione seria: billing, limiti e policy sui dati sono tutti chiari. Il problema è che spesso i team non usano solo Gemini, ma anche Claude, GPT, e magari devono configurare key diverse per strumenti diversi. La strada più semplice è usare onehop: cambi il base URL dell’SDK OpenAI in https://api.onehop.ai/v1 e usi un unico endpoint compatibile OpenAI/Anthropic per chiamare Claude/GPT/Gemini; i nuovi account ricevono $10, senza carta, ideale per far girare prima demo e strumenti interni.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEHOP_API_KEY"],
    base_url="https://api.onehop.ai/v1",
)

resp = client.chat.completions.create(
    model=os.environ["ONEHOP_MODEL"],
    messages=[{"role": "user", "content": "把这段日志总结成 5 条排障线索。"}],
)

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

Qui ho volutamente messo model in una variabile d’ambiente: i nomi dei modelli del gateway fanno riferimento alla console, quindi non hardcodarli nel codice. Se vuoi ridurre la gestione di billing multi-vendor e layer di compatibilità, puoi provarlo direttamente: chiamare Claude e altri modelli su onehop, oppure riscattare prima il credito: registrati e ricevi subito $10 di credito di prova.

Ultimo controllo prima dell’integrazione

Prima di andare online, non limitarti a verificare se ritorna del testo. Fai almeno quattro controlli: primo, conferma che il modello sia ancora disponibile nella pagina corrente dei modelli Google; secondo, controlla nella pagina dei prezzi i costi di input, output, Batch e Search grounding; terzo, registra in modo completo i log degli errori 401, 429 e 5xx; quarto, rendi configurabili a runtime base_url, api_key e model, così non dovrai rilasciare una nuova versione solo per cambiare modello.

Il punto di questa integrazione non è “cambiare fornitore di modelli”, ma disaccoppiare il layer SDK dal provider del modello. Prima fai funzionare gemini-3.5-flash con la OpenAI compatibility ufficiale di Google, poi decidi se usare connessione diretta, gateway o entrambe. Così le modifiche sono minime e anche il rollback è rapido.