Skip to content

Native Gemini API reference: generateContent

The native Gemini format reference: request fields, JSON output, function calling, streaming, image generation and errors.

Updated October 2, 2026
On this page

Google's native format for Gemini models, the one the Gemini libraries and Gemini CLI use. The model id goes in the URL, not in the body. Gemini chat models also work in Chat Completions and Messages.

POSThttps://api.5abeer.ai/v1beta/models/{model}:generateContent

Authentication#

Send your key in the x-goog-api-key header, with the Gemini base URL. A key for Gemini models is needed: Claude and GPT keys don't work under /v1beta. The URL forms:

  • /v1beta/models/{model}:generateContent for a full reply.
  • /v1beta/models/{model}:streamGenerateContent?alt=sse for a streamed reply.
  • /v1beta/models/{model}:countTokens to count the input tokens without calling the model.

Quick example#

curl --request POST "https://api.5abeer.ai/v1beta/models/gemini-4-argon:generateContent" \
  --header "x-goog-api-key: $KHABEER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"contents":[{"role":"user","parts":[{"text":"Write a product idea in one sentence."}]}]}'
Response
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Hello! How can I help you today?"
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "modelVersion": "gemini-4-argon"
}

The key is read from KHABEER_API_KEY, so it never appears in your code.

Parameters#

Your request is passed on in Gemini's own format, so the fields below behave as in Google's documentation. Supported means we pass it to the model; rejected means the request fails, here because the key is for another provider.

ParameterDescriptionClaudeGPTGemini
contentsarrayrequiredThe conversation: user and model turns, each with parts of text or images.ClaudeRejectedGPTRejectedGeminiSupported
systemInstructionobjectSystem instructions in parts.ClaudeRejectedGPTRejectedGeminiSupported
generationConfigobjectOutput settings: temperature, topP, topK, maxOutputTokens, stopSequences, responseMimeType, responseSchema, thinkingConfig and responseModalities.ClaudeRejectedGPTRejectedGeminiSupported
toolsarrayfunctionDeclarations for functions the model can call.ClaudeRejectedGPTRejectedGeminiSupported
toolConfigobjectWhen the model calls functions: AUTO, ANY or NONE.ClaudeRejectedGPTRejectedGeminiSupported
safetySettingsarrayContent filter thresholds per category.ClaudeRejectedGPTRejectedGeminiSupported

Image generation#

The Gemini image models generate images through this same endpoint: add "responseModalities": ["TEXT", "IMAGE"] to generationConfig, and the image comes back as inlineData with Base64 data, as in the image example. The image models are in the Images page's models list.

Streaming#

Call :streamGenerateContent?alt=sse instead of :generateContent. Each event is a partial reply in the same shape as the full one, and the last event carries usageMetadata. Details in Streaming.

Examples#

Instructions, settings and JSON output#

curl https://api.5abeer.ai/v1beta/models/gemini-3.1-pro:generateContent \
  -H "x-goog-api-key: $KHABEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "systemInstruction": {
      "parts": [
        {
          "text": "Answer in one sentence."
        }
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Give me one product idea."
          }
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.4,
      "topP": 0.9,
      "topK": 40,
      "maxOutputTokens": 300,
      "stopSequences": [
        "END"
      ],
      "responseMimeType": "application/json",
      "responseSchema": {
        "type": "OBJECT",
        "properties": {
          "idea": {
            "type": "STRING"
          }
        },
        "required": [
          "idea"
        ]
      }
    },
    "safetySettings": [
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "threshold": "BLOCK_MEDIUM_AND_ABOVE"
      }
    ]
  }'
Response shape
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "{\"idea\":\"Lumen Notes: a notebook that turns voice memos into tidy to-do lists.\"}"
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 21,
    "candidatesTokenCount": 18,
    "totalTokenCount": 39
  },
  "modelVersion": "gemini-3.1-pro"
}

Calling a function#

curl https://api.5abeer.ai/v1beta/models/gemini-3.1-pro:generateContent \
  -H "x-goog-api-key: $KHABEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "What is the weather in Cairo?"
          }
        ]
      }
    ],
    "tools": [
      {
        "functionDeclarations": [
          {
            "name": "get_weather",
            "description": "Get the weather for a city",
            "parameters": {
              "type": "OBJECT",
              "properties": {
                "city": {
                  "type": "STRING"
                }
              },
              "required": [
                "city"
              ]
            }
          }
        ]
      }
    ],
    "toolConfig": {
      "functionCallingConfig": {
        "mode": "AUTO"
      }
    }
  }'
Response shape
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "functionCall": {
              "name": "get_weather",
              "args": {
                "city": "Cairo"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 21,
    "candidatesTokenCount": 18,
    "totalTokenCount": 39
  },
  "modelVersion": "gemini-3.1-pro"
}

Streaming#

curl -N https://api.5abeer.ai/v1beta/models/gemini-3.1-pro:streamGenerateContent?alt=sse \
  -H "x-goog-api-key: $KHABEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "Write a product idea in one sentence."
          }
        ]
      }
    ]
  }'
Stream events
data: {"candidates":[{"content":{"role":"model","parts":[{"text":"Lumen Notes: a notebook that turns "}]},"index":0}],"modelVersion":"gemini-3.1-pro"}

data: {"candidates":[{"content":{"role":"model","parts":[{"text":"voice memos into tidy to-do lists."}]},"finishReason":"STOP","index":0}],"usageMetadata":{"promptTokenCount":21,"candidatesTokenCount":18,"totalTokenCount":39},"modelVersion":"gemini-3.1-pro"}

Generating an image#

curl https://api.5abeer.ai/v1beta/models/gemini-2.5-flash-image:generateContent \
  -H "x-goog-api-key: $KHABEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "A minimal orange logo for a note-taking app."
          }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": [
        "TEXT",
        "IMAGE"
      ]
    }
  }'
Response shape
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "Here is the logo."
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
            }
          }
        ]
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 21,
    "candidatesTokenCount": 18,
    "totalTokenCount": 39
  },
  "modelVersion": "gemini-2.5-flash-image"
}

The request above was run on the local test stack on 2026-10-02; the reply shows the shape, and its text is an example.

Errors#

Errors raised while serving the request come in Google's shape: error with a numeric code, a message and a status such as INVALID_ARGUMENT or RESOURCE_EXHAUSTED. The key, balance and limit checks answer {"code", "message"} with codes such as INVALID_API_KEY and USAGE_LIMIT_EXCEEDED. The full mapping is in Limits and error codes.

Models#

per 1M tokens

Official price from the provider's page, checked October 19, 2026.

All models and prices