Usare l’SDK OpenAI con l’API Gemini: come configurare base_url, nome del modello e prezzi di Gemini 3.5 Flash

La documentazione di compatibilità OpenAI di Google è stata aggiornata il 2026-05-18 e lo dice chiaramente: i modelli Gemini possono essere chiamati tramite gli SDK OpenAI Python / JavaScript; in sostanza basta modificare tre elementi: api_key, base_url, model (Google). Oggi è il 2026-06-14 e la pagina dei prezzi indica per gemini-3.5-flash, nel livello standard a pagamento: input $1.50 / 100 万 token, output inclusi i token di pensiero $9.00 / 100 万 token (Prezzi Google).

La mia valutazione è molto semplice: se hai già un progetto basato su OpenAI SDK, per ora non riscriverlo. Integra prima Gemini come backend OpenAI-compatible, verifica costi, streaming e chiamate agli strumenti, poi decidi se migrare all’SDK nativo di Gemini.

1. Modifica minima: cambia solo endpoint e nome del modello

Per Python, installa prima l’SDK OpenAI ufficiale:

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

Poi modifica il client così:

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",
    reasoning_effort="low",
    messages=[
        {"role": "system", "content": "你是一个直接、准确的代码助手。"},
        {"role": "user", "content": "用三句话解释 SSE 流式输出。"},
    ],
)

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

chat.completions.create, messages, tools e strutture simili restano nello stile OpenAI Chat Completions; anche il riferimento API di OpenAI continua a definire Chat Completions come un’interfaccia che genera risposte a partire da una lista di messaggi (OpenAI). Quindi il punto centrale della migrazione non è il codice di business, ma il livello di configurazione.

2. Non dimenticare lo slash finale in base_url

L’indirizzo nella documentazione Google è:

https://generativelanguage.googleapis.com/v1beta/openai/

Se ometti l’ultimo /, alcuni client possono creare problemi strani quando compongono i percorsi. Nel codice di produzione conviene estrarlo in variabili d’ambiente:

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

Se vuoi evitare di gestire account, quote e fatture di più provider, onehop è una strada più semplice: imposti base_url su https://api.onehop.ai/v1 e, con la stessa interfaccia compatibile OpenAI / Anthropic, puoi chiamare Claude, GPT e Gemini. I nuovi account ricevono $10 senza dover collegare una carta; è adatto per fare prima un PoC e poi valutare se collegarti direttamente ai provider ufficiali.

from openai import OpenAI

client = OpenAI(
    api_key="你的 onehop key",
    base_url="https://api.onehop.ai/v1",
)

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "给我一个 FastAPI 健康检查接口"}],
)
print(resp.choices[0].message.content)

Gli ingressi sono qui: chiama Claude e altri modelli su onehop, registrati e ricevi subito $10 di credito di prova.

3. Calcola prima il costo in base ai token di output

gemini-3.5-flash nel livello standard non è “così economico da non doverci pensare”. Il prezzo dell’output è 6 volte quello dell’input:

Modello	Livello	Input / 1 milione di token	Output / 1 milione di token
gemini-3.5-flash	Standard	$1.50	$9.00
gemini-3.5-flash	Batch	$0.75	$4.50
gemini-3.5-flash	Flex	$0.75	$4.50

Anche i valori di Batch e Flex provengono dalla stessa pagina dei prezzi di Google. Quando sviluppi un’applicazione, devi limitare max_completion_tokens, soprattutto per riassunti, generazione di codice e loop di strumenti Agent. Un input più lungo può ancora essere messo in cache; un output fuori controllo invece brucia denaro in modo diretto.

4. Come viene mappato reasoning_effort

Il livello di compatibilità Google accetta reasoning_effort in stile OpenAI e lo mappa alla configurazione thinking di Gemini (Google):

reasoning_effort	Gemini 3 Flash thinking_level
minimal	minimal
low	low
medium	medium
high	high

Se non lo passi, viene usato il valore predefinito del modello. La documentazione Google riporta anche una limitazione importante: Gemini 3 non può disattivare il thinking; none è disponibile solo per alcuni modelli 2.5. Il mio consiglio è usare online low come predefinito e salire a medium o high solo per pianificazioni complesse o chiamate a strumenti su catene lunghe. Poiché il prezzo dell’output include i token di pensiero, l’intensità di ragionamento non è una manopola gratuita.

5. Streaming e chiamate di funzione: funzionano, ma gestisci i blocchi vuoti

La chiamata in streaming mantiene la sintassi dell’SDK OpenAI:

stream = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "写一个 Redis 缓存封装"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Qui if delta è molto utile. Nelle risposte in streaming possono esserci ruoli, chiamate agli strumenti o incrementi vuoti: non dare per scontato che ogni chunk contenga testo.

Anche le chiamate di funzione passano da tools e tool_choice="auto". La documentazione di compatibilità Google fornisce un esempio di funzione meteo e conferma che la Gemini API supporta il function calling (Google). Nei progetti reali non limitarti a stampare ciò che restituisce il modello: controlla message.tool_calls, esegui la funzione locale e poi reinserisci il risultato dello strumento come messaggio nel turno successivo.

Conclusione: il costo minimo per migrare a Gemini è modificare tre righe di configurazione; ciò che va davvero monitorato sono i token di output, l’intensità del thinking, i chunk vuoti nello streaming e il ciclo completo delle chiamate agli strumenti. Se vuoi solo inserire rapidamente Claude, GPT e Gemini nello stesso progetto OpenAI SDK, usare l’ingresso unificato di onehop ti farà risparmiare parecchio tempo di configurazione: chiama Claude e altri modelli su onehop, oppure riscuoti prima il credito di prova da $10 incluso con la registrazione.