The generateContent endpoint is the core API for all Gemini interactions.

Endpoints

text

# Developer API
POST https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent
POST .../{model}:streamGenerateContent?alt=sse

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

Request Structure

json

{
  "contents": [
    { "role": "user", "parts": [{ "text": "Hello" }] }
  ],
  "system_instruction": {
    "parts": [{ "text": "You are helpful." }]
  },
  "generationConfig": {
    "temperature": 1.0, "topP": 0.8, "topK": 10,
    "maxOutputTokens": 800, "responseMimeType": "text/plain"
  },
  "safetySettings": [
    { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_ONLY_HIGH" }
  ]
}

No "system" Role

There is no "system" role in contents. System instructions go in the separate system_instruction field.

Parts Types

Type	Structure	Use
Text	`{"text": "..."}`	Any text
Inline data	`{"inline_data": {"mime_type": "...", "data": "base64"}}`	Images/audio
File data	`{"file_data": {"file_uri": "..."}}`	Uploaded files
Function call	`{"function_call": {...}}`	Tool invocation

Response

json

{
  "candidates": [{
    "content": { "role": "model", "parts": [{"text": "..."}] },
    "finishReason": "STOP",
    "safetyRatings": [...]
  }],
  "usageMetadata": {
    "promptTokenCount": 45, "candidatesTokenCount": 123, "totalTokenCount": 168
  }
}

FinishReason: STOP, MAX_TOKENS, SAFETY, RECITATION, OTHER.