Understanding Gemini API Usage in PintarRPH Web

This guide explains how PintarRPH Web uses the Google Gemini API and helps you understand your API usage.

Note: As of v2.45.0, PintarRPH includes a built-in server-side LLM. A Gemini API key is optional — RPT and RPH generation works without any key configuration. This guide explains the BYOK (Bring Your Own Key) option for teachers who want to use their own Gemini keys.

Platform: https://pintarrph.com

Table of Contents

1. What is the Gemini API?
2. How PintarRPH Uses AI
3. API Call Breakdown by Feature
4. Understanding Costs & Free Tier
5. Multiple API Keys
6. Usage Optimization Tips
7. Monitoring Your Usage
8. Data Privacy
9. FAQ

What is the Gemini API?

The Google Gemini API is an AI service that powers the intelligent features in PintarRPH Web:

• Generates creative teaching activities
• Extracts information from documents and PDFs
• Analyzes curriculum standards (DSKP)
• Creates differentiated learning activities
• Understands document structures and layouts

Think of it as your AI teaching assistant that helps automate time-consuming tasks.

How PintarRPH Uses AI

PintarRPH uses AI-powered features with specialized multi-agent systems to help you create teaching plans:

Main Features (You Will Use These Most)

1. RPH Weekly Generator - Creates daily lesson plans (Rancangan Pengajaran Harian)
   - 7 specialized agents including ValidationAgent (FREE validation)
   - 2 API calls per teaching day (Activity + Differentiation agents)

2. RPT Annual Plan Generator - Creates yearly teaching plans (Rancangan Pengajaran Tahunan)
   - 6 specialized agents including ValidationAgent (FREE validation)
   - ~2 API calls per annual plan (Element Library + Assignment agents)
   - Exports in V2 format (cleaner 3-column layout)

Supporting Features (Automatic / Admin-Only)

Note: DSKP, BukuText, and academic calendar content is now pre-bundled on the server. You do not need to run extraction steps or upload calendars. The following features are handled automatically by the system.

3. Calendar Setup - Automatically configured from shared KPM calendar when you save your schedule
4. DSKP Content - Pre-bundled SK/SP learning standards for all supported subjects
5. BukuText Content - Pre-bundled textbook content for all supported subjects
6. Public Holiday Sync - Automatically included in shared calendar data

Quality Assurance (FREE - No API Calls)

ValidationAgent - Automatic quality validation for RPH and RPT
- Validates 20+ criteria (KPM compliance, content quality)
- Returns quality score (0-100) with feedback
- Uses Python logic (not AI) - completely FREE

API Call Breakdown by Feature

Here is exactly how many API calls each feature uses:

1. RPH Weekly Generator (MOST USED)

What it does:
- Generates complete daily lesson plans for a week using 7 specialized agents
- Creates Set Induksi, Aktiviti Utama, Aktiviti Penutup
- Generates differentiated activities (cemerlang, sederhana, perlu perhatian)
- Creates TP1-TP6 assessment descriptors
- Automatic quality validation before export (FREE - no API calls)

API Calls per Generation:

2 API calls x number of teaching days

Examples:
  3 teaching days = 6 API calls
  5 teaching days = 10 API calls
  1 teaching day  = 2 API calls

Why 2 calls per day?
- 1st call: ActivityGenAgent - Generate activities (Set Induksi, Aktiviti Utama, Penutup)
- 2nd call: DifferentiationAgent - Generate differentiation and TP levels

The 7 Specialized Agents:

Multi-language Support:
- Supports BM (Bahasa Melayu), BI (English), ARAB (Arabic), Jawi
- Activities generated in the subject's language automatically

2. RPT Annual Plan Generator

What it does:
- Creates yearly teaching plan (52 weeks) using 6 specialized agents
- Maps TEMA and Units to school weeks
- Assigns PAK21, KBAT, NILAI elements intelligently
- Distributes content across teaching weeks
- Automatic quality validation before export (FREE - no API calls)

API Calls per Generation:

~2 API calls per annual plan

Breakdown:
  1 call: ElementLibraryAgent - Get element library (PAK21, KBAT, NILAI)
  1 call: ElementAssignmentAgent - Distribute elements across weeks

The 6 Specialized Agents:

Note: Element library is cached after first call, making subsequent generations faster.

3-6. Pre-Bundled Content (No User API Calls Needed)

The following features are now handled automatically by the system using pre-bundled content:

You do not need to run any extraction steps or upload any documents. All content is ready to use as soon as you set up your teaching schedule.

Understanding Costs & Free Tier

Google Gemini API Free Tier

The Gemini API offers a FREE tier for development and low-volume use:

Free Tier Limits (as of 2026):
- 5 requests per minute (RPM) - Gemini 2.5 Flash
- 20 requests per day (RPD) - Gemini 2.5 Flash
- 250K tokens per minute (TPM)

What This Means for You

PintarRPH Daily Limits (Aligned with Free Tier):

The 20/day limit is designed to match the free tier and support normal teaching workflows.

Real-World Example

A typical teacher's weekly usage:

  Generate 1-2 RPH weeks per week = 1-2 generations
  Generate 6 RPT plans per year   = 6 generations total (one-time)
  DSKP + BukuText + Calendar      = Pre-bundled (0 API calls)

  TYPICAL DAILY USAGE:  0-2 generations
  FREE TIER LIMIT:      20 calls per day
  PINTARRPH LIMIT:      20 RPH + 20 RPT per day

  Result: Normal teaching use is well within the free tier.

Understanding the Limits

Per-Minute Limit (5 RPM):
- Maximum 5 requests within any 1-minute window
- Prevents rapid-fire API calls
- Normal use is not affected (you generate plans one at a time)

Daily Limit (20 RPD):
- Aligned with Gemini free tier
- Prevents abuse and mass generation
- Sufficient for 1-6 subjects, weekly lesson planning, and annual RPT generation

Multiple API Keys

All Gemini API keys are optional — the built-in server LLM handles generation when no key is configured. If you do want to use your own keys (BYOK), you can assign up to 5 separate Gemini API keys in Settings, one per feature group. This prevents one feature from consuming quota needed by another.

How fallback works for RPH: If Key 1 hits its daily limit (Error 429), the system automatically falls back to other available keys -- no interruption needed.

How to get multiple keys: Create multiple free API keys by creating multiple Google Cloud projects at Google AI Studio.

The per-user daily generation limit (20 RPH + 20 RPT) remains fixed and is enforced by the app regardless of how many keys you configure.

Usage Optimization Tips

Best Practices to Save API Calls

1. No Extraction Needed

DSKP, BukuText, and Calendar are all pre-bundled/auto-configured.
You only use API calls for RPT and RPH generation.
No setup API calls needed!

2. Batch Your Work

DO:
  Generate multiple weeks at once when planning ahead
  Queue up 2-3 RPT generations together

DON'T:
  Generate one day at a time (more efficient to do full week)
  Generate same week multiple times (edit instead)

3. Use Date Selection Wisely

DO:
  Select only the days you need for RPH generation
  Deselect holidays or non-teaching days

Example:
  If week has 3 teaching days + 2 holidays:
    Select only 3 days = 6 API calls
    Selecting all 5 days = 10 API calls (wastes 4 calls)

4. Pre-Bundled Content

These are handled automatically -- no API calls from you:
  Academic Calendar --> Auto-configured from your schedule
  DSKP Content      --> Pre-bundled for all subjects
  BukuText Content  --> Pre-bundled for all subjects
  Public Holidays   --> Included in shared calendar

Your API calls only go toward RPT and RPH generation.

Monitoring Your Usage

Check Your Usage in Google AI Studio

1. Go to: https://aistudio.google.com/app/apikey
2. Sign in with your Google account
3. Click on your API key
4. View usage statistics and quota

What to Monitor

Normal Usage (Within Limits):
- 0-20 generations per day
- No rate limit errors
- Generations complete successfully
- Daily counter shows green or yellow (15-19)

At Limit:
- 20 generations reached for the day
- Daily counter shows red (20/20)
- App displays: "Had harian telah dicapai"
- Wait until tomorrow for limit reset

Data Privacy

What Is Sent to Google Gemini API

When using AI features, the following curriculum data is sent:
- Pre-bundled DSKP content (SK/SP learning standards for the selected subject)
- Pre-bundled BukuText content (textbook topics and structure)
- Your RPT data (to generate RPH activities)
- Generation parameters (subject, year level, week number)

What Is NOT Sent to Google

• Your personal information
• Student data
• School name or teacher name
• License keys or activation data
• Calendar data (processed locally)
• Any other user documents or data

Google's Data Policy

• API requests are not used to train models
• Data is not stored beyond processing
• All API calls use secure HTTPS connections
• Read more: https://ai.google.dev/gemini-api/terms

FAQ

Q1: Do I need to pay for the Gemini API?

A: No. PintarRPH is designed to work entirely within the Gemini API free tier (20 requests/day). The app enforces a 20/day limit to ensure you never exceed the free quota.

Q2: What happens if I exceed the daily limit?

A: PintarRPH enforces limits BEFORE calling the Gemini API:

1. PintarRPH App Limit (20/day):
   - The app blocks generation after 20 RPT or 20 RPH per day
   - You will see: "Had penjanaan harian telah dicapai (20 RPH/RPT sehari). Sila cuba semula esok."
   - Solution: Wait until tomorrow (resets at midnight)

2. Gemini API Limit (if reached):
   - Error: "Rate limit exceeded" or "Daily quota exceeded"
   - This is very unlikely since the app limit prevents excessive API calls
   - Solution: Wait for the limit to reset

Q3: Can I reduce quota exhaustion errors?

A: Yes -- use multiple API keys.

You can assign up to 5 separate Gemini API keys in Settings, one per feature group. This prevents one feature from consuming quota needed by another. For RPH keys specifically, if Key 1 hits its daily limit (Error 429), the system automatically falls back to other available keys -- no interruption.

You can create multiple free API keys by creating multiple Google Cloud projects at Google AI Studio.

Q4: Why does RPH generation use 2 calls per day?

A: To generate high-quality lesson plans:

1. Call 1 - ActivityGenAgent:
   - Creates Set Induksi
   - Creates Aktiviti Utama (main activities)
   - Creates Aktiviti Penutup
   - Suggests KBAT integration
   - Recommends teaching aids (BBM)

2. Call 2 - DifferentiationAgent:
   - Creates Pengayaan (enrichment) for advanced students
   - Creates Pengukuhan (reinforcement) for average students
   - Creates Pemulihan (remedial) for struggling students
   - Generates TP1-TP6 descriptors

This ensures each daily plan is complete and differentiated.

Q5: Which model does PintarRPH use?

A: gemini-2.5-flash (default)

Why this model?
- Fast (generates plans in seconds)
- Smart (high quality teaching activities)
- Included in the generous free tier
- Latest model from Google

Can I change the model?
Yes, in Settings (Tetapan Sistem) you can change the Gemini Model field:
- gemini-2.5-flash - Fast and efficient (recommended)
- gemini-2.5-pro - Slower but more detailed
- gemini-1.5-flash - Older version

Q6: Do API calls happen offline?

A: No. API calls require an internet connection.

What requires internet:
- Generate new RPH/RPT
- All features (PintarRPH Web is entirely cloud-based)

What works without internet:
- Nothing -- PintarRPH Web requires an active internet connection at all times

Q7: Is my data sent to Google?

A: Only curriculum data is sent when using AI features:

Sent to Google Gemini API:
- Pre-bundled DSKP content (SK/SP learning standards)
- Pre-bundled BukuText content (textbook topics)
- Your RPT data (to generate RPH activities)

NOT sent to Google:
- Your personal information
- Student data
- School information
- License keys
- Calendar data

Google's Data Policy:
- API requests are not used to train models
- Data is not stored beyond processing
- Read more: https://ai.google.dev/gemini-api/terms

Q8: How does validation work? Does it use API calls?

A: No. Validation is FREE (no API calls).

The ValidationAgent checks your generated RPH/RPT quality:

What it validates:
- All required fields present
- SK/SP codes format correct
- Activities have enough detail
- Time allocation reasonable
- BBM (teaching aids) present
- Differentiation complete (3 levels)
- TP1-TP6 descriptors included

How it works:
- Uses Python logic (no AI needed)
- Runs automatically after generation
- Gives quality score (0-100)
- Shows errors and warnings
- 100% FREE (0 API calls)

Quick Reference Card

Gemini Free Tier: 20 requests per day (RPD), 5 requests per minute (RPM)
PintarRPH Limits: 20 RPT + 20 RPH per day
Alignment: Designed to match the free tier

Need Help?

Setup Issues

See: GEMINI_API_SETUP.md

API Quota Questions

Visit: https://ai.google.dev/gemini-api/docs/quota

PintarRPH Support

Email: [email protected]

Related Documentation

• QUICKSTART.md - Getting started with PintarRPH Web
• USER_GUIDE.md - Complete user guide
• GEMINI_API_SETUP.md - How to get and configure your API key
• FAIR_USAGE_POLICY.md - Daily generation limits and best practices
• LICENSE_ACTIVATION.md - License activation process
• LIMITATIONS.md - System limitations and workarounds

Last Updated: May 2026
Platform: PintarRPH Web (https://pintarrph.com)
Gemini Model: gemini-2.5-flash
PintarRPH Desktop Version: 2.48.3