Gemini Setup

Google's Gemini is the recommended AI provider for Capyseo.

Get API Key

Go to Google AI Studio
Click "Get API Key"
Create a new project or select existing
Copy the API key

Set Environment Variable

# Linux/macOS
export GEMINI_API_KEY=your_key_here

# Windows (PowerShell)
$env:GEMINI_API_KEY = "your_key_here"

# Windows (CMD)
set GEMINI_API_KEY=your_key_here

Permanent Setup

# Add to ~/.bashrc or ~/.zshrc
echo 'export GEMINI_API_KEY=your_key_here' >> ~/.bashrc
source ~/.bashrc

Usage

CLI

# Auto-detected from env
capyseo analyze ./dist --ai

# Explicit provider
capyseo analyze ./dist --ai --ai-provider gemini

# Specific model
capyseo analyze ./dist --ai --ai-provider gemini --ai-model gemini-2.5-pro

Config File

// capyseo.config.js
export default {
  ai: {
    enabled: true,
    provider: 'gemini',
    model: 'gemini-2.5-flash', // or 'gemini-2.5-pro'
    cacheDir: '.capyseo-cache',
    cacheTTL: 86400000,
  },
};

Programmatic

import { SEOAnalyzer, GeminiProvider } from '@capyseo/core';

const analyzer = new SEOAnalyzer({
  aiProvider: 'gemini',
  aiApiKey: process.env.GEMINI_API_KEY,
  aiModel: 'gemini-2.5-flash',
});

Available Models

Model	Speed	Quality	Cost
`gemini-2.5-flash`	Fast	Good	Low
`gemini-2.5-pro`	Slower	Best	Higher

Recommended: gemini-2.5-flash for most use cases.

Features

Meta Description Generation

[x] [meta-description] Missing meta description
    AI Suggestion: "Build modern web applications with our
    comprehensive React tutorial. Learn hooks, state management,
    and best practices for production-ready code."

Alt Text Generation

[!] [image-alt] Image missing alt: hero.jpg
    AI Suggestion: "Developer typing on laptop with code
    editor open showing React components"

Content Analysis

capyseo generate meta https://example.com

Output:

Title: "React Hooks Guide - Complete Tutorial for Beginners"
Description: "Master React Hooks with practical examples..."
Primary Keyword: react hooks
Secondary Keywords: useState, useEffect, custom hooks
Readability: 72/100

CI/CD Integration

GitHub Actions

- name: SEO Analysis
  run: capyseo analyze ./dist --ai --ci --min-score 80
  env:
    GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}

GitLab CI

seo:
  script:
    - capyseo analyze ./dist --ai
  variables:
    GEMINI_API_KEY: $GEMINI_API_KEY

Caching

Responses are cached to reduce API calls:

ai: {
  cacheDir: '.capyseo-cache',
  cacheTTL: 86400000, // 24 hours
}

Cache structure:

.capyseo-cache/
├── meta-description-abc123.json
├── alt-text-def456.json
└── content-analysis-ghi789.json

Add to .gitignore:

.capyseo-cache/

Rate Limits

Gemini has generous rate limits:

Free tier: 60 requests/minute
Paid tier: Higher limits

Capyseo uses caching to stay within limits.

Troubleshooting

"API key not valid"

Check key is correct
Ensure no extra spaces
Verify key in Google AI Studio

"Quota exceeded"

Wait and retry
Enable caching
Consider paid tier

No AI Suggestions

Check --ai flag is set
Verify GEMINI_API_KEY is set:
echo $GEMINI_API_KEY
Check config has ai.enabled: true

Pricing

Tier	Cost	Limits
Free	$0	60 req/min
Pay-as-you-go	~$0.0001/req	Higher limits

For most SEO analysis, the free tier is sufficient.