Proxy Configuration

Configure HTTP and SOCKS5 proxies, SSL certificates, and custom authentication for the Google Gen AI SDK

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

export HTTPS_PROXY='http://username:[e-mail]:8080'

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

pip install httpx[socks]

Configure SOCKS5 Proxy

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:[e-mail]: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:[e-mail]: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:[e-mail]:1080'},
        async_client_args={'proxy': 'socks5://user:[e-mail]: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
        }
    )
)

Using Pre-configured Client with Proxy

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