Usare l’SDK OpenAI per chiamare l’API Gemini: guida alla migrazione modificando solo base_url, API Key e nome del modello

Al 2026-06-14, la documentazione di Google sulla compatibility OpenAI di Gemini è molto diretta: se hai già codice con le librerie OpenAI in Python o TypeScript, puoi collegarlo a Gemini cambiando API Key, base_url e nome del modello; il modello usato negli esempi della documentazione è gemini-3.5-flash, e la pagina di compatibilità è stata aggiornata l’ultima volta il 2026-05-18 (Google AI for Developers). Non è “magia di un layer di adattamento”: significa semplicemente inviare le richieste dell’SDK OpenAI all’endpoint compatibile fornito da Google.

Installa prima l’SDK, senza cambiare paradigma di chiamata

Se il tuo progetto usa già l’SDK Python ufficiale di OpenAI, puoi mantenere chat.completions.create(). Il repository dell’SDK Python di OpenAI resta la fonte ufficiale del client (openai-python), e anche l’interfaccia compatibile di Google accetta questa stessa forma di chiamata.

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": "You are a concise code reviewer."},
        {"role": "user", "content": "Review this Python function for edge cases."},
    ],
)

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

La API Key va creata da Google AI Studio (AI Studio API key). Fai attenzione allo slash finale: /v1beta/openai/, non il normale endpoint nativo di Gemini /v1beta/models/....

Anche REST può seguire la forma OpenAI

Per server, debug con curl e health check dei gateway non serve necessariamente l’SDK. Il percorso REST indicato dalla documentazione di compatibilità Google è /openai/chat/completions:

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.5-flash",
    "messages": [
      {"role": "user", "content": "Give me a 5-point migration checklist."}
    ]
  }'

Durante la migrazione, esegui prima questa chiamata. Ti permette di separare quattro categorie di problemi — Key, nome del modello, uscita di rete e permessi di fatturazione — facendo risparmiare tempo rispetto al debug diretto dentro il servizio applicativo.

Come viene mappato reasoning_effort

Il controllo del thinking di Gemini e reasoning_effort di OpenAI si sovrappongono in parte, e Google dice esplicitamente di non passarli insieme. Il layer compatibile mapperà i parametri in stile OpenAI sui parametri thinking di Gemini (Google OpenAI compatibility).

OpenAI reasoning_effort	Gemini 3 thinking_level	Gemini 2.5 thinking_budget
minimal	minimal o low	1024
low	low	1024
medium	medium	8192
high	high	24576

Per una migrazione prudente, all’inizio non passare reasoning_effort e lascia che il modello usi il valore predefinito. Se vuoi controllare i costi, aggiungi low per i task con contesto lungo, poi osserva la qualità dell’output e la fattura dei token.

Non guardare solo il nome del modello quando valuti il prezzo

La pagina ufficiale dei prezzi di Google elenca chiaramente i prezzi standard di Gemini 2.5 Pro e Flash, espressi per 1 milione di token; il prezzo di output include i thinking tokens (Gemini API pricing).

Modello	Prezzo input	Prezzo output
gemini-2.5-pro, prompt ≤ 200k	$1.25	$10.00
gemini-2.5-pro, prompt > 200k	$2.50	$15.00
gemini-2.5-flash, input testo/immagini/video	$0.30	$2.50
gemini-2.5-flash, input audio	$1.00	$2.50

Il mio consiglio: per chat, classificazione e task di codice leggeri parti da Flash; per ragionamento complesso, sintesi di documenti lunghi e refactoring del codice passa a Pro. La soglia di prompt da 200k di Pro influisce direttamente sul prezzo unitario di input e output: non infilare dentro alla cieca log, frammenti recuperati via retrieval e system prompt ripetuti.

Checklist di migrazione

1. Sostituisci OPENAI_API_KEY con GEMINI_API_KEY, generata da AI Studio.
2. Cambia base_url in https://generativelanguage.googleapis.com/v1beta/openai/.
3. Cambia il nome del modello con un modello Gemini compatibile, per esempio gemini-3.5-flash.
4. Verifica prima con REST curl, poi ricollega l’SDK.
5. Sospendi temporaneamente reasoning_effort personalizzato e aggiungilo solo dopo aver confermato la qualità.
6. Registra i costi di input, output e thinking token, soprattutto la soglia dei 200k di Pro.

Se devi collegare anche Claude/GPT

Se usi solo Gemini, l’endpoint compatibile ufficiale di Google è la soluzione più pulita. Ma se nel progetto devi usare contemporaneamente Claude, GPT e Gemini, gestire molte Key, molte fatture e molti SDK diventa fastidioso. Il percorso più semplice è onehop: compatibile con OpenAI/Anthropic, basta cambiare base_url in https://api.onehop.ai/v1 e puoi chiamare Claude/GPT/Gemini con lo stesso SDK OpenAI; punta su prezzi inferiori a quelli ufficiali, $10 in regalo per i nuovi account e nessuna carta richiesta.

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.5",
    messages=[{"role": "user", "content": "Refactor this API handler."}],
)
print(resp.choices[0].message.content)

Se ora vuoi solo far partire l’integrazione multi-modello, puoi provarlo direttamente: chiamare Claude e altri modelli su onehop, oppure ottenere prima il credito: registrati e ricevi subito $10 di credito di prova. Il punto chiave della migrazione non è aggiungere una pila di layer astratti, ma ridurre le variabili a tre cose: endpoint, key, model.