Document Utilities

Google Gemini API Reference

Google's Gemini API exposes content generation through generateContent methods. You send structured contents data, optional system instructions, and generation settings, then receive candidate responses with metadata that can be inspected before display.

Endpoint Pattern

  • Method: POST
  • URL pattern: https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
  • Auth: API key via query param ?key=GEMINI_API_KEY

JSON Structure Explained

Section Type Role
contents array Conversation blocks with parts text segments.
systemInstruction object Global behavior guidance for the model.
generationConfig object Sampling controls such as temperature and max output tokens.
safetySettings array Safety thresholds for harmful categories.

VS Code Style cURL Example

# Gemini generateContent
curl -X POST \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": {
      "parts": [{"text": "You are a strict technical documentation assistant."}]
    },
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Explain RAG in simple terms."}]
      }
    ],
    "generationConfig": {
      "temperature": 0.3,
      "maxOutputTokens": 256
    }
  }'

VS Code Style Python Example

import requests

url = (
    "https://generativelanguage.googleapis.com/v1beta/models/"
    "gemini-1.5-flash:generateContent?key=GEMINI_API_KEY"
)

payload = {
    "contents": [
        {
            "role": "user",
            "parts": [{"text": "Summarize model distillation."}],
        }
    ],
    "generationConfig": {"temperature": 0.2, "maxOutputTokens": 220},
}

resp = requests.post(url, json=payload, timeout=60)
resp.raise_for_status()
response_json = resp.json()
print(response_json["candidates"][0]["content"]["parts"][0]["text"])

Response Notes

Gemini often returns output under candidates, each containing content and parts. For deterministic apps, teams commonly inspect safety results and candidate counts before selecting display text.

Implementation tip: Normalize Gemini response extraction into a helper so application code remains stable even if provider response schemas evolve.