Overview
The Google Gemini provider enables access to Google’s Gemini models through OpenAI-compatible API protocol. Gemini models offer strong multimodal capabilities and large context windows.
Configuration
Add Gemini models to your model_list configuration:
{
"model_list": [
{
"model_name": "gemini",
"model": "gemini/gemini-2.0-flash",
"api_key": "your-gemini-api-key",
"api_base": "https://generativelanguage.googleapis.com/v1beta",
"request_timeout": 300
}
],
"agents": {
"defaults": {
"model_name": "gemini"
}
}
}
Configuration Parameters
| Parameter | Type | Required | Default | Description |
|---|
model_name | string | Yes | - | Alias for this model configuration |
model | string | Yes | - | Model identifier with gemini/ prefix |
api_key | string | Yes* | - | Your Google AI Studio API key |
api_base | string | No | https://generativelanguage.googleapis.com/v1beta | API endpoint URL |
request_timeout | integer | No | 120 | Request timeout in seconds |
Available Models
Google provides several Gemini model families:
Gemini 2.0 Series (Latest)
gemini/gemini-2.0-flash - Fast and efficient, best for most tasksgemini/gemini-2.0-flash-exp - Experimental version with latest features
Gemini 1.5 Series
gemini/gemini-1.5-pro - Most capable 1.5 modelgemini/gemini-1.5-flash - Fast 1.5 variantgemini/gemini-1.5-flash-8b - Compact variant
Gemini 1.0 Series (Legacy)
gemini/gemini-1.0-pro - Original Gemini model
Gemini models support up to 2M token context windows (1.5 Pro) and native multimodal understanding.
Setup Instructions
Method 1: API Key (Recommended)
1. Get API Key
- Visit Google AI Studio
- Sign in with your Google account
- Click Create API Key
- Copy your API key
Edit ~/.picoclaw/config.json:
{
"model_list": [
{
"model_name": "gemini",
"model": "gemini/gemini-2.0-flash",
"api_key": "your-actual-key-here"
}
],
"agents": {
"defaults": {
"model_name": "gemini",
"max_tokens": 8192,
"temperature": 0.7
}
}
}
3. Test Connection
picoclaw agent -m "Hello Gemini, test my connection"
Method 2: Antigravity OAuth
For Google Cloud OAuth authentication:
{
"model_list": [
{
"model_name": "gemini",
"model": "antigravity/gemini-2.0-flash",
"auth_method": "oauth"
}
]
}
Advanced Configuration
Custom API Endpoint
Use a custom Gemini-compatible endpoint:
{
"model_name": "gemini-proxy",
"model": "gemini/gemini-2.0-flash",
"api_base": "https://my-proxy.com/v1beta",
"api_key": "your-key",
"request_timeout": 300
}
Extended Context
Gemini models support massive context windows:
{
"agents": {
"defaults": {
"model_name": "gemini",
"max_tokens": 8192
}
}
}
- Gemini 1.5 Pro: Up to 2M tokens
- Gemini 2.0 Flash: Up to 1M tokens
- Gemini 1.5 Flash: Up to 1M tokens
Multimodal Support
Gemini natively supports text, images, audio, and video:
{
"model_name": "gemini",
"model": "gemini/gemini-2.0-flash",
"api_key": "your-key"
}
Thinking/Reasoning Mode
Gemini 2.0 Flash supports thinking mode for complex reasoning:
{
"model_name": "gemini-thinking",
"model": "gemini/gemini-2.0-flash-thinking-exp",
"api_key": "your-key"
}
thought_signature field.
Protocol Details
Gemini uses OpenAI-compatible API through PicoClaw:
- Endpoint:
/chat/completions
- Authentication: Bearer token via
Authorization header
- Request format: OpenAI-compatible JSON
- Response format: OpenAI-compatible JSON
PicoClaw automatically:
- Strips
gemini/ prefix when sending requests
- Converts messages to Gemini format
- Handles multimodal content
- Preserves
thought_signature from Gemini 2.0
- Skips
prompt_cache_key (not supported by Gemini)
Troubleshooting
Invalid API Key
Error: 400 API key not valid
- Verify your API key is correct
- Ensure API key is from AI Studio (not Cloud Console)
- Check key hasn’t been restricted or revoked
Rate Limiting
Free tier has generous limits:
- 15 requests per minute
- 1 million tokens per minute
- 1,500 requests per day
If you need more:
- Wait for rate limit to reset
- Upgrade to paid tier
- Configure multiple API keys for load balancing
Region Restrictions
Gemini API may not be available in all regions:
- Check availability page
- Use VPN if necessary
- Contact Google Cloud for enterprise access
Timeout Errors
Increase timeout for large context or complex requests:
{
"model_name": "gemini",
"model": "gemini/gemini-2.0-flash",
"api_key": "your-key",
"request_timeout": 600
}
Model Selection Guide
| Use Case | Recommended Model | Notes |
|---|
| General tasks | gemini-2.0-flash | Best balance of speed and quality |
| Large documents | gemini-1.5-pro | 2M token context window |
| Fast responses | gemini-2.0-flash | Optimized for speed |
| Multimodal | gemini-2.0-flash | Supports text, image, audio, video |
| Complex reasoning | gemini-2.0-flash-thinking-exp | Experimental thinking mode |
| Cost-sensitive | gemini-1.5-flash-8b | Most economical option |
Cost Optimization
- Use appropriate models: Use Flash for most tasks, Pro only for complex analysis
- Leverage free tier: Generous limits for personal use
- Set
max_tokens: Limit response length to reduce costs
- Monitor usage: Check AI Studio dashboard
- Use extended context wisely: Only include necessary context
Free Tier
Google AI Studio offers generous free tier:
- 15 RPM (requests per minute)
- 1M TPM (tokens per minute)
- 1,500 RPD (requests per day)
- No credit card required
- Ideal for development and testing
Comparison with Other Providers
| Feature | Gemini | OpenAI | Anthropic |
|---|
| Context window | Up to 2M | Up to 200K | Up to 200K |
| Multimodal | Native | Limited | Limited |
| Free tier | Yes (generous) | Limited | No |
| Speed | Very fast | Fast | Fast |
| Cost | Low | Medium | Medium |
Legacy Configuration (Deprecated)
Older configuration format (still supported):
{
"providers": {
"gemini": {
"api_key": "your-key",
"api_base": "https://generativelanguage.googleapis.com/v1beta"
}
},
"agents": {
"defaults": {
"provider": "gemini",
"model": "gemini-2.0-flash"
}
}
}
model_list format for better features like load balancing and fallbacks.