Usare l’SDK OpenAI per chiamare l’API Gemini: guida all’integrazione modificando solo base_url, key e nome del modello

Google è stata molto chiara: la Gemini API supporta la compatibilità OpenAI, quindi può essere chiamata con l’SDK Python di OpenAI, l’SDK JavaScript e via REST; negli esempi ufficiali il base_url è https://generativelanguage.googleapis.com/v1beta/openai/ e il nome del modello è gemini-3.5-flash (Google AI for Developers).
È molto pratico per i team che hanno già codice basato sull’SDK OpenAI. Non serve riscrivere un client, né modificare la struttura dei messaggi: prima cambi tre configurazioni, fai girare tutto, poi decidi se usare o meno le funzionalità native di Gemini.

Prima vediamo quali sono le tre cose da modificare

La documentazione di Google lo dice chiaramente dopo gli esempi: le modifiche riguardano solo api_key, base_url e model. Anche l’SDK Python di OpenAI supporta la configurazione di base_url o OPENAI_BASE_URL (openai-python), mentre nel SDK Node il campo corrispondente è baseURL (openai-node).

Esempio Python minimo:

from openai import OpenAI

client = OpenAI(
    api_key="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": "用一句话解释什么是向量数据库。"},
    ],
)

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

Se il tuo vecchio codice usa già client.chat.completions.create(), molto probabilmente devi solo estrarre in configurazione la parte in cui inizializzi il client. Non codificare il nome del modello direttamente nelle funzioni di business: più avanti, passare a Batch, Flex o a un altro modello sarà molto più doloroso.

In Node.js la logica è la stessa

Nella versione JavaScript cambia solo il nome del campo, da base_url a baseURL:

import OpenAI from "openai";

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

const resp = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [{ role: "user", content: "给我一个 Redis 限流方案。" }],
});

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

Anche REST può essere usato direttamente: POST https://generativelanguage.googleapis.com/v1beta/openai/chat/completions, con l’header di richiesta Authorization: Bearer $GEMINI_API_KEY. È utile per usare prima curl ed escludere problemi legati a SDK, proxy o variabili d’ambiente.

Non valutare i prezzi a sensazione: calcolali sull’output

Al 2026-06-14, la pagina ufficiale dei prezzi di Gemini indica per gemini-3.5-flash un prezzo standard di $1.50 / 1M tokens per l’input e $9.00 / 1M tokens per l’output, mentre Batch e Flex costano entrambi $0.75 / 1M tokens per l’input e $4.50 / 1M tokens per l’output (prezzi della Gemini API). La documentazione ufficiale specifica anche che il prezzo dell’output include i thinking tokens, quindi per i task di ragionamento non guardare solo il prezzo dell’input.

Modalità	Input / 1M tokens	Output / 1M tokens	Scenari adatti
Standard	$1.50	$9.00	Richieste online, bassa latenza
Batch	$0.75	$4.50	Elaborazione batch offline
Flex	$0.75	$4.50	Quando è accettabile una pianificazione elastica

Il mio consiglio è semplice: per chat, Agent e plugin di editor usa prima Standard; per riepiloghi di log, pulizia dati e valutazioni offline, usa il più possibile Batch/Flex. Nei task con output lunghi, la differenza di costo si amplifica.

Gli errori più comuni durante la migrazione

Primo, non dimenticare /openai/ alla fine di base_url. Molti 404 e molti errori di “modello inesistente” dipendono dal fatto che si sta chiamando il percorso nativo di Gemini, non quello compatibile.
Secondo, tieni separate le variabili d’ambiente. OPENAI_API_KEY può continuare a essere usata per OpenAI; per Gemini è meglio usare una variabile separata, GEMINI_API_KEY, senza far competere due provider in CI per la stessa variabile.
Terzo, esegui prima models.list(). La documentazione di Google fornisce esempi per elencare i modelli e recuperarne uno: prima della produzione usali per confermare che regione dell’account, permessi e ID del modello siano tutti corretti.
Quarto, streaming, function calling e input immagine hanno esempi nel layer di compatibilità, ma non dare per scontato che tutti i parametri OpenAI siano supportati uno a uno. Fai prima una regressione con una richiesta reale del tuo business.

Se vuoi mantenere meno key

Se il team usa contemporaneamente Claude, GPT e Gemini, richiedere le key una per una, collegare carte e configurare quote è fastidioso. La strada più semplice è usare onehop: cambi il base_url dell’SDK OpenAI in https://api.onehop.ai/v1, usi la key di onehop e puoi chiamare Claude, GPT e Gemini tramite interfacce compatibili con OpenAI/Anthropic. Il suo posizionamento è aiutarti a ridurre il lavoro di integrazione; i prezzi sono inferiori a quelli ufficiali, i nuovi account ricevono $10 e non serve collegare una carta.

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "把这段报错日志总结成三条原因。"}],
)

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

Se vuoi provare Claude o il routing multi-modello, puoi vedere direttamente qui: chiamare Claude e altri modelli su onehop. Se vuoi prima eseguire un piccolo esempio senza collegare una carta, passa da questo ingresso: registrati e ricevi $10 di credito di prova.

Conclusione: rendilo prima configurabile, non fissare il provider nel codice

Il valore principale della compatibilità OpenAI di Gemini, questa volta, non è “un modello in più”, ma il fatto che il costo di migrazione sia abbastanza basso. Metti base_url, api_key e model nella configurazione, mentre il codice di business continua a usare le chat completions dell’SDK OpenAI.
Dopo averlo fatto funzionare, aggiungi tre cose: registra i token di input/output, scegli Standard o Batch/Flex in base al task, e rendi l’ID del modello un interruttore di rollout graduale. Così, se oggi integri Gemini e domani Claude o un altro servizio compatibile, non dovrai più toccare il codice core di business.