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.