Gemini Developer API durch einen HTTP-Proxy schicken

google-genai 2.30.1 über HTTPS_PROXY und CONNECT führen, TLS mit SSL_CERT_FILE prüfen und Transportfehler von 401, 403 und 429 trennen.

Dieser Text ist für Entwickler, die google-genai 2.30.1 über einen HTTP-Proxy zur Gemini Developer API schicken und einen Verbindungsfehler einordnen wollen. Die Beispiele nutzen Dummy-Daten. Top Proxy verkauft keine IPs und verteilt keine API-Schlüssel. Ein Treffer im Browser auf Meine IP beweist nicht die Route dieses Clients.

01Welchen Gemini-Client dieser Text nimmt#

Gemini ist eine Produktfamilie, kein einzelner Socket. Die Web-Oberfläche und die mobile App haben eigene Proxy-Wege, oft den Systemproxy des Geräts. Die Gemini CLI ist ein anderes Binary. Vertex AI bzw. die Gemini Enterprise Agent Platform verlangt Projekt, Region und Cloud-Anmeldung. Dieser Text nimmt genau einen dokumentierten Client: das Python-Paket google-genai 2.30.1 gegen die Gemini Developer API mit einem API-Schlüssel.

Die README von googleapis/python-genai, abgerufen am 15. Oktober 2026, sagt klar: Sync- und Async-Client nutzen standardmäßig httpx. aiohttp kommt erst, wenn Sie google-genai[aiohttp] extra installieren. In diesem Lauf war aiohttp nicht installiert. Der sichtbare Transport hieß SyncHttpxClient. Wer die Extra-Variante nimmt, bekommt ein anderes Request-Objekt und muss deren Doku lesen, nicht diese Schritte.

Die offizielle Übersicht der Gemini API unter ai.google.dev/gemini-api/docs beschreibt Modelle, Schlüssel und Aufrufe. Sie beschreibt keinen Proxy. Die Troubleshooting-Seite spricht von 429, 403, Timeouts und Netzfehlern, nicht von HTTPS_PROXY. Deshalb gehört die Proxy-Frage in die SDK-README und in den HTTP-Stack darunter, nicht in eine Vermutung über Google-Konten.

Ein Proxy ändert die TCP-Route. Er ändert nicht, ob Ihr Schlüssel gilt, ob die Rechnung stimmt und ob Ihr Land in der Liste der verfügbaren Regionen steht. Am 15. Oktober 2026 nannte Available regions Germany in der Länderliste für Google AI Studio und die Gemini API. Das ist eine Dokumentationszeile. Es ist keine Zusage für Ihr Konto.

Pin die Version, bevor Sie Umgebungsvariablen anfassen. Die PyPI-Metadaten von google-genai 2.30.1 verlangen httpx ab 0.28.1. Dieser Text hat httpx 0.28.1 und Python 3.14.6 gelesen, plus OpenSSL 3.6.3 in genau diesem Interpreter.

python3 -m venv .venv
.venv/bin/pip install 'google-genai==2.30.1'
.venv/bin/python -c "import google.genai, httpx; print(google.genai.__version__, httpx.__version__)"

Wenn die Ausgabe nicht 2.30.1 und 0.28.1 zeigt, gelten die folgenden Felder nicht. Ältere Pakete hatten andere Client-Namen. Neuere können HttpOptions wieder verschieben.

02Den HTTP-Proxy vor dem Client setzen#

Die README, Abschnitt Proxy, ab Zeile 269 der main-Datei vom 15. Oktober 2026, setzt den Hop über Umgebungsvariablen, bevor der Client entsteht:

export HTTPS_PROXY='http://username:***@proxy_uri:port'
export SSL_CERT_FILE='client.pem'

httpx und aiohttp lesen laut derselben README urllib.request.getproxies. Das ist die Systemliste aus der Umgebung, nicht ein geheimes SDK-Feld namens proxy=. google-genai 2.30.1 übergibt an httpx.Client in diesem Build kein eigenes proxy=-Argument, solange Sie client_args leer lassen. Der Default trust_env von httpx bleibt damit an. Wer HTTPS_PROXY erst nach genai.Client(...) setzt, kommt zu spät.

Das URL-Schema des Proxys und das Schema des Ziels sind zwei Knöpfe. Für ein HTTPS-Ziel wie generativelanguage.googleapis.com reicht ein HTTP-Proxy, der CONNECT spricht. Ein https:// vor der Proxy-URL ist in dieser README nicht der dokumentierte Normalfall.

SOCKS5 steht in derselben README extra. httpx kann SOCKS, wenn httpx[socks] liegt und Sie client_args={'proxy': 'socks5://user:pass@host:port'} an types.HttpOptions geben. Das ist ein anderer Weg. Er wurde hier nicht ausgeführt. HTTPS_PROXY=socks5://... ohne dieses Extra ist kein nachgewiesener Pfad.

Der Proxy-Checker sagt, ob ein Host überhaupt HTTP annimmt. Er sagt nicht, ob google-genai denselben Hop nimmt.

1. Paketversion pinnen, siehe oben.
2. HTTPS_PROXY setzen, bevor Python startet, mit Host, Port und falls nötig User in der URL.
3. Den Client erzeugen und eine Anfrage schicken, deren Ziel Sie kennen.
4. Das Proxy-Log auf CONNECT prüfen, nicht nur den Python-Status.

Passwörter gehören in die Umgebung oder in einen Secret-Store, nicht in Git und nicht in Screenshots. Dummy-User in diesem Text sind Etiketten.

03TLS mit SSLCERTFILE prüfen und Geheimnisse halten#

Die README nennt SSL_CERT_FILE optional neben dem Proxy. In google-genai 2.30.1 ist das kein frommer Wunsch an OpenSSL allein. _ensure_httpx_ssl_ctx in _api_client.py baut ein ssl.SSLContext mit cafile=os.environ.get('SSL_CERT_FILE', certifi.where()). Ohne Variable nimmt das SDK also certifi, nicht automatisch jede Firmen-CA aus dem Schlüsselbund.

httpx 0.28.1 selbst kann SSL_CERT_FILE lesen, wenn verify is True und trust_env stimmt. Sobald das SDK ein fertiges Context-Objekt als verify= übergibt, zählt dieser SDK-Zweig, nicht der httpx-Zweig. Deshalb die Datei setzen, bevor Client startet, und nicht hoffen, dass ein späteres export noch greift.

verify=False ist kein Normalfall und kommt in diesem Text nicht vor. Ein abgeschaltetes TLS beweist nicht, dass der Proxy sauber tunnelt. Es beweist nur, dass niemand mehr das Zertifikat prüft.

Firmenproxys legen oft eine eigene CA in den Tunnel. Dann muss genau diese Datei in SSL_CERT_FILE stehen. Eine CA aus einem alten Lauf hilft nicht, wenn der Origin neu ausgestellt wurde. localhost und ein öffentlicher Google-Host sind verschiedene Namen. Das Zertifikat muss zu dem Host passen, den CONNECT ankündigt.

Schwärzen Sie User, Passwort und API-Schlüssel in jeder Ausgabe. Ein Stacktrace von google-genai kann die Proxy-URL mitschleifen, wenn sie in der Umgebung steht. Redact vor dem Ticket, nicht danach.

1. Die CA-Datei legen, die zu Ihrem Hop oder Ziel gehört.
2. SSL_CERT_FILE exportieren.
3. Denselben Lauf ohne die Datei wiederholen, wenn Sie TLS vom Proxy trennen wollen.
4. verify=False nicht als Workaround behalten.

In einem kontrollierten Loopback-Lauf am 15. Oktober 2026 blieb CONNECT autorisiert, sobald das Passwort stimmte. Ohne SSL_CERT_FILE hob httpx ConnectError mit Kette SSLCertVerificationError: certificate verify failed: self-signed certificate. Der Tunnel war da. Das Origin-Zertifikat hing am Socket, certifi vertraute ihm nicht. Das ist fehlendes CA-Vertrauen, nicht ein fehlendes Zertifikat. Das ist Methodik gegen einen lokalen Origin, kein Google-Aufruf.

04Die Route lokal nachweisen#

Ein Browser auf Meine IP oder der Proxy-Checker prüft den Browser bzw. eine eingegebene Proxy-Zeile. google-genai ist ein anderer Prozess. Er erbt nicht magisch die Firefox-Einstellungen. Mobile-IPs aus dem Katalog unter Mobile Proxys ändern die Herkunftsadresse, sobald der Client sie wirklich nutzt. Sie ändern nicht die Python-Bibliothek.

Nutzen Sie Ihren noch laufenden Proxy und das Ziel, das Sie wirklich sprechen wollen. Ein Loopback-Labor ist hier nur Methodik. Es ist kein Paket zum Kopieren in Produktion. Die Ports aus dem Lauf sind danach weg.

Gegen die Gemini Developer API lassen Sie base_url weg. Das SDK setzt dann https://generativelanguage.googleapis.com/. Eine eigene base_url ist in der README der Weg zu einem API-Gateway, nicht der Ersatz für HTTPS_PROXY. Beides nicht in denselben Topf werfen.

Das Skript unten ist die vollständige, getestete Datei public_client.py. GEMINI_BASE_URL ist nur für ein eigenes Ziel. Für Google lassen Sie sie ungesetzt. GEMINI_API_KEY setzen Sie selbst. Dummy-Werte aus einem Labor sind keine Google-Schlüssel.

import os

from google import genai
from google.genai import types

api_key = os.environ["GEMINI_API_KEY"]
http_options = types.HttpOptions(timeout=20000)
base_url = os.environ.get("GEMINI_BASE_URL")
if base_url:
    http_options.base_url = base_url

with genai.Client(api_key=api_key, http_options=http_options) as client:
    response = client.models.generate_content(
        model="gemini-flash-latest",
        contents="ping",
    )
print(response.text)

Timeout in HttpOptions ist in dieser Version Millisekunden. 20000 sind zwanzig Sekunden, nicht zwanzigtausend Sekunden. client.close() übernimmt der Context Manager.

1. Umgebung setzen: HTTPS_PROXY, bei Bedarf SSL_CERT_FILE, GEMINI_API_KEY.
2. Skript starten, ohne Google zu erwarten, solange der Hop noch unklar ist.
3. CONNECT im Proxy-Log suchen.
4. Erst danach den Inhalt der Modellantwort lesen.

Im Loopback zeigte der Origin die Zeile POST /v1beta/models/gemini-flash-latest:generateContent HTTP/1.1. Das SDK hängt in diesem Build also /v1beta/ und :generateContent an. Ein 200 im Checker ohne diese Zeile im SDK-Log ist ein anderer Client.

Ohne HTTPS_PROXY und mit dem künstlichen Host gemini-de.invalid kam ConnectError plus gaierror: nodename nor servname provided, or not known. Der lokale Origin blieb unberührt. Das ist der Punkt der Isolierung: die Route fehlte, Google wurde nicht gefragt.

05Transportfehler von API-Fehlern trennen#

Wenn Sie kein erfolgreiches CONNECT beobachten, ist der Hop in diesem Log nicht nachgewiesen. Das beweist nicht, dass kein Proxy konfiguriert ist. Dieselbe Lücke entsteht, wenn HTTPS_PROXY fehlt, der Host auf einer Bypass-Liste steht, der Hop unerreichbar ist, ein anderer Prozess spricht oder das Log CONNECT nicht aufzeichnet. Wenn CONNECT steht und TLS stirbt, ist der Tunnel da und die CA-Vertrauensstellung falsch. Wenn TLS steht und Google 401 oder 403 schickt, hat die Leitung gehalten. Dann sind Schlüssel, Rechnung oder Berechtigung dran, nicht der Datacenter-Tarif.

Die Troubleshooting-Doku, abgerufen am 15. Oktober 2026, rät bei 429 und 5xx zu Backoff und warnt davor, 400, 402 und 403 in derselben Schleife zu drehen. Ein Proxy, der 407 antwortet, kommt in dieser Liste nicht vor. 407 ist der Proxy, nicht Gemini.

Der Loopback-Origin antwortete bewusst mit JSON simulated-unauthorized. Das SDK hob google.genai.errors.ClientError mit Code 401 und Status UNAUTHENTICATED. Dieselbe Datei public_client.py endete mit Exit 1 und derselben Meldung. Das ist ein simulierter API-Fehler nach erfolgreichem Transport. Es ist kein Nachweis, dass Ihr echter Schlüssel bei Google durchgeht. Es ist der Nachweis, dass httpx den CONNECT-Hop genommen hat und die Antwort vom Ziel kam.

Falsches Proxy-Passwort lieferte httpx.ProxyError: 407 Proxy Authentication Required. Der Origin sah nichts. Wer 407 als Gemini-Auth liest, sucht am falschen Ende.

Async und Stream sind in google-genai vorhanden. Dieser Text behauptet dazu keine Proxy-Ergebnisse. Der Default ohne aiohttp-Extra blieb synchron über httpx. Wer generate_content_stream über denselben Hop schickt, muss das getrennt messen.

06Welches Proxy-Protokoll zu google-genai 2.30.1 passt#

Für diesen Client ist der dokumentierte Alltag ein HTTP-Proxy mit CONNECT, gesetzt über HTTPS_PROXY, optional mit User und Passwort in der URL. SOCKS5 ist der Sonderweg über HttpOptions.client_args und httpx[socks]. Wer nur SOCKS5 gekauft hat und httpx ohne Extra betreibt, hat keinen in diesem Text nachgewiesenen Pfad.

Auth am Proxy und Auth an Google sind zwei Paare. Proxy-User gehören in HTTPS_PROXY. Die README beschreibt die automatische SDK-Umgebung: ohne Argument api_key greift GEMINI_API_KEY oder GOOGLE_API_KEY, und bei beiden gewinnt GOOGLE_API_KEY. Das gedruckte Skript übergibt ausdrücklich api_key aus os.environ["GEMINI_API_KEY"]. Es verlangt also GEMINI_API_KEY und nutzt diesen Wert. GOOGLE_API_KEY überschreibt dieses Argument nicht. Ein 401 mit gesetztem Proxy-User ist trotzdem Google-Auth, sobald CONNECT und TLS gehalten haben.

Die Herkunft der Exit-IP ist wieder ein anderes Regal. Mobile Proxys beschreiben Carrier-Adressen. Ob Ihr Anbieter HTTP und User/Passwort an dem Endpunkt liefert, steht auf der Karte des Dienstes, nicht in google-genai. Daraus folgt keine pauschale Dienstempfehlung für genau diesen Client.

Kaufen Sie das Protokoll, das der Client spricht. Dann prüfen Sie CONNECT. Dann erst das Modell.