Google Chat Format (Gemini generateContent)

Official Documentation

Google Gemini API

📝 Introduction

All Gemini models on the gateway can be called natively via the Google Gemini API format (generateContent / streamGenerateContent).

📮 Endpoint

POST /v1beta/models/{model}:generateContent
POST /v1beta/models/{model}:streamGenerateContent?alt=sse

Authentication

Use either header:

x-goog-api-key: $WS_API_KEY

or the query parameter ?key=$WS_API_KEY.

💡 Request Examples

Basic Chat ✅

curl "http://baseurl/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $WS_API_KEY" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "Hello, Gemini!"}]
      }
    ]
  }'

Response Example:

{
  "candidates": [
    {
      "content": {
        "parts": [{"text": "Hello! How can I help you today?"}],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 4,
    "candidatesTokenCount": 10,
    "totalTokenCount": 14
  },
  "modelVersion": "gemini-2.5-flash"
}

System Instruction + Generation Config ✅

curl "http://baseurl/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $WS_API_KEY" \
  -d '{
    "system_instruction": {
      "parts": [{"text": "You are a concise assistant. Answer in one sentence."}]
    },
    "contents": [
      {"role": "user", "parts": [{"text": "Why is the sky blue?"}]}
    ],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 256,
      "topP": 0.95
    }
  }'

Streaming Response ✅

curl "http://baseurl/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $WS_API_KEY" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Tell me a short story"}]}
    ]
  }'

Responses arrive as server-sent events, each data: line containing a partial GenerateContentResponse.

Image Input ✅

curl "http://baseurl/v1beta/models/gemini-2.5-pro:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $WS_API_KEY" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {"inline_data": {"mime_type": "image/jpeg", "data": "<BASE64_IMAGE>"}},
          {"text": "Describe this image."}
        ]
      }
    ]
  }'

Function Calling ✅

curl "http://baseurl/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $WS_API_KEY" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "What is the weather in Abu Dhabi?"}]}
    ],
    "tools": [
      {
        "function_declarations": [
          {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "parameters": {
              "type": "object",
              "properties": {
                "location": {"type": "string"}
              },
              "required": ["location"]
            }
          }
        ]
      }
    ]
  }'

Using the Official SDK

from google import genai

client = genai.Client(
    api_key="sk-...",                     # your WS API key
    http_options={"base_url": "http://baseurl"},
)

resp = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Hello, Gemini!",
)
print(resp.text)

📋 Request Body Parameters

Parameter	Type	Required	Description
contents	array	Yes	Conversation turns. Each has role (user / model) and parts (text, inline_data, file_data, function_call, function_response)
system_instruction	object	No	System prompt, {"parts": [{"text": "..."}]}
generationConfig	object	No	temperature, topP, topK, maxOutputTokens, stopSequences, responseMimeType, responseSchema, thinkingConfig, responseModalities etc.
tools	array	No	function_declarations for function calling
toolConfig	object	No	Function calling mode: AUTO / ANY / NONE
safetySettings	array	No	Safety category thresholds

📥 Response Fields

Field	Type	Description
candidates	array	Generated candidates. Each contains content.parts, finishReason (STOP, MAX_TOKENS, SAFETY, ...), index
usageMetadata	object	promptTokenCount, candidatesTokenCount, totalTokenCount, thoughtsTokenCount
modelVersion	string	Model version used

OpenAI-compatible alternative

Every Gemini model can also be called through the OpenAI format at POST /v1/chat/completions — convenient if your application already uses an OpenAI SDK.