The generateContent API

One endpoint, every Gemini interaction

Whether you're sending text, an image, a tool call, or a JSON-mode request, you're hitting the same endpoint: generateContent. The streaming variant is streamGenerateContent?alt=sse. Memorize the shape and the rest of Gemini stops feeling like memorization.

Request structure

A request has up to four top-level fields:

contents — the conversation. List of {role, parts} objects. Roles are "user" and "model". There is no "system" role.
system_instruction — a separate top-level field for the system prompt. This is where the "you are an X" goes.
generationConfig — temperature, top-p, top-k, max output tokens, response MIME type, seed.
safetySettings — per-category thresholds for harm filtering.

Parts are the atoms

Inside a content's parts array, each part is one of:

Text — {"text": "..."}
Inline data — {"inline_data": {"mime_type": "image/png", "data": "base64..."}}
File data — {"file_data": {"file_uri": "files/abc"}} (after upload via the File API)
Function call — {"function_call": {"name": "...", "args": {...}}} (model output)
Function response — {"function_response": {"name": "...", "response": {...}}} (your tool result)

One content can hold multiple parts in its parts array — that's how you send "describe this image" + the image itself in a single user turn.

Response shape

The response wraps the model's output in candidates (almost always one) and tells you why generation stopped via finishReason: STOP (clean end), MAX_TOKENS (you ran out of budget), SAFETY (filtered), RECITATION (training data echo), or OTHER (you don't want to see this one).

Code

Endpoint URLs·text

# Developer API (AI Studio)
POST https://generativelanguage.googleapis.com/v1beta/models/{MODEL}:generateContent
POST https://generativelanguage.googleapis.com/v1beta/models/{MODEL}:streamGenerateContent?alt=sse

# Vertex AI
POST https://{LOC}-aiplatform.googleapis.com/v1/projects/{PROJECT}/locations/{LOC}/publishers/google/models/{MODEL}:generateContent

Request body — full shape·json

{
  "contents": [
    { "role": "user",  "parts": [{ "text": "Hello" }] },
    { "role": "model", "parts": [{ "text": "Hi! How can I help?" }] },
    { "role": "user",  "parts": [{ "text": "Explain transformers in 3 sentences." }] }
  ],
  "system_instruction": {
    "parts": [{ "text": "You are a precise but warm technical tutor." }]
  },
  "generationConfig": {
    "temperature": 0.7,
    "topP": 0.95,
    "topK": 40,
    "maxOutputTokens": 800,
    "responseMimeType": "text/plain"
  },
  "safetySettings": [
    { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH" }
  ]
}

Response body·json

{
  "candidates": [{
    "content": {
      "role": "model",
      "parts": [{ "text": "Transformers process tokens in parallel using attention..." }]
    },
    "finishReason": "STOP",
    "safetyRatings": [
      { "category": "HARM_CATEGORY_HARASSMENT", "probability": "NEGLIGIBLE" }
    ]
  }],
  "usageMetadata": {
    "promptTokenCount": 45,
    "candidatesTokenCount": 123,
    "totalTokenCount": 168
  }
}

Exercise

Hand-write the JSON for a 4-message conversation (alternating user/model/user/model) with a system instruction, a temperature of 0.3, and a max output of 200 tokens. POST it via curl to generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent. Read the response and print: finishReason, totalTokenCount, and the first 100 chars of the model's reply.