Overview
The Google Gen AI SDK supports HTTP and SOCKS5 proxies through both httpx and aiohttp libraries. You can configure proxies using environment variables or explicit client arguments.
HTTP Proxy with Environment Variables
Both httpx and aiohttp use urllib.request.getproxies() to read proxy settings from environment variables. This is the simplest method for configuring proxies.
Basic HTTP Proxy
export HTTPS_PROXY='http://proxy.example.com:8080'
from google import genai
client = genai.Client(api_key='GEMINI_API_KEY')
# Client will automatically use the HTTPS_PROXY environment variable
HTTP Proxy with Authentication
from google import genai
client = genai.Client(api_key='GEMINI_API_KEY')
Mixed HTTP and HTTPS Proxies
export HTTP_PROXY='http://proxy.example.com:8080'
export HTTPS_PROXY='https://secure-proxy.example.com:8443'
SOCKS5 Proxy
For SOCKS5 proxy support, you need to install httpx with the socks extra and explicitly pass proxy configuration through client arguments.
Install SOCKS5 Support
from google import genai
from google.genai import types
client = genai.Client(
api_key='GEMINI_API_KEY',
http_options=types.HttpOptions(
client_args={'proxy': 'socks5://host:port'},
async_client_args={'proxy': 'socks5://host:port'}
)
)
SOCKS5 with Authentication
from google import genai
from google.genai import types
client = genai.Client(
api_key='GEMINI_API_KEY',
http_options=types.HttpOptions(
client_args={'proxy': 'socks5://user:pass@host:port'},
async_client_args={'proxy': 'socks5://user:pass@host:port'}
)
)
SSL Certificates
Custom SSL Certificate File
Specify a custom SSL certificate file for proxy connections:
export HTTPS_PROXY='http://username:[email protected]:8080'
export SSL_CERT_FILE='client.pem'
from google import genai
client = genai.Client(api_key='GEMINI_API_KEY')
# Client will use the SSL_CERT_FILE for certificate verification
Custom SSL Context (Aiohttp)
For more control over SSL verification with aiohttp:
import ssl
from google import genai
from google.genai import types
# Create custom SSL context
ssl_context = ssl.create_default_context()
ssl_context.load_verify_locations('ca-bundle.crt')
ssl_context.load_cert_chain('client.crt', 'client.key')
client = genai.Client(
api_key='GEMINI_API_KEY',
http_options=types.HttpOptions(
async_client_args={'ssl': ssl_context}
)
)
Custom SSL Context (Httpx)
import ssl
import httpx
from google import genai
from google.genai import types
# Create custom SSL context
ssl_context = ssl.create_default_context()
ssl_context.load_verify_locations('ca-bundle.crt')
client = genai.Client(
api_key='GEMINI_API_KEY',
http_options=types.HttpOptions(
client_args={'verify': ssl_context},
async_client_args={'verify': ssl_context}
)
)
Disable SSL Verification (Not Recommended)
Disabling SSL verification exposes your application to man-in-the-middle attacks. Only use this for testing in controlled environments.
from google import genai
from google.genai import types
client = genai.Client(
api_key='GEMINI_API_KEY',
http_options=types.HttpOptions(
client_args={'verify': False},
async_client_args={'verify': False}
)
)
Proxy Bypass
Bypass Proxy for Specific Hosts
export HTTPS_PROXY='http://proxy.example.com:8080'
export NO_PROXY='localhost,127.0.0.1,.internal.com'
from google import genai
client = genai.Client(api_key='GEMINI_API_KEY')
# Requests to localhost, 127.0.0.1, and *.internal.com will bypass the proxy
Complete Proxy Configuration Examples
Corporate Proxy with SSL
export HTTPS_PROXY='http://user:[email protected]:8080'
export SSL_CERT_FILE='/etc/ssl/certs/corporate-ca.pem'
export NO_PROXY='localhost,.internal.company.com'
from google import genai
client = genai.Client(
vertexai=True,
project='your-project-id',
location='us-central1'
)
response = client.models.generate_content(
model='gemini-2.0-flash-exp',
contents='Hello, world!'
)
SOCKS5 Proxy with Retry Configuration
from google import genai
from google.genai import types
client = genai.Client(
api_key='GEMINI_API_KEY',
http_options=types.HttpOptions(
client_args={'proxy': 'socks5://user:[email protected]:1080'},
async_client_args={'proxy': 'socks5://user:[email protected]:1080'},
timeout=60000, # 60 seconds
retry_options=types.HttpRetryOptions(
attempts=3,
initial_delay=2.0,
max_delay=30.0
)
)
)
Aiohttp with Custom SSL and Proxy
import ssl
from google import genai
from google.genai import types
# Configure SSL
ssl_context = ssl.create_default_context()
ssl_context.check_hostname = True
ssl_context.verify_mode = ssl.CERT_REQUIRED
ssl_context.load_verify_locations('custom-ca.pem')
# Configure client
client = genai.Client(
api_key='GEMINI_API_KEY',
http_options=types.HttpOptions(
async_client_args={
'ssl': ssl_context,
'trust_env': True # Read proxy from environment variables
}
)
)
import httpx
from google import genai
from google.genai import types
# Create custom httpx client with proxy
sync_client = httpx.Client(
proxy='http://proxy.example.com:8080',
verify='/path/to/ca-bundle.crt',
timeout=30.0
)
async_client = httpx.AsyncClient(
proxy='http://proxy.example.com:8080',
verify='/path/to/ca-bundle.crt',
timeout=30.0
)
client = genai.Client(
api_key='GEMINI_API_KEY',
http_options=types.HttpOptions(
httpx_client=sync_client,
httpx_async_client=async_client
)
)
Troubleshooting
Verify Proxy Configuration
import os
print(f"HTTPS_PROXY: {os.getenv('HTTPS_PROXY')}")
print(f"HTTP_PROXY: {os.getenv('HTTP_PROXY')}")
print(f"NO_PROXY: {os.getenv('NO_PROXY')}")
print(f"SSL_CERT_FILE: {os.getenv('SSL_CERT_FILE')}")
Test Proxy Connection
import httpx
try:
response = httpx.get(
'https://generativelanguage.googleapis.com',
proxy='http://proxy.example.com:8080'
)
print(f"Proxy connection successful: {response.status_code}")
except Exception as e:
print(f"Proxy connection failed: {e}")
Common Issues
- Authentication Failures: Ensure username and password are properly URL-encoded
- SSL Certificate Errors: Verify that
SSL_CERT_FILE points to a valid certificate bundle
- SOCKS5 Not Working: Confirm that
httpx[socks] is installed
- Environment Variables Not Working: Check that variables are exported in the same shell session