Google Gemini Content Protocol

curl "https://api.poixe.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $POIXE_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Hello!"
          }
        ]
      }
    ]
  }'

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Hello there! How can I help you today?"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 2,
    "candidatesTokenCount": 10,
    "totalTokenCount": 35,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 2
      }
    ],
    "thoughtsTokenCount": 23
  },
  "modelVersion": "gemini-2.5-flash",
  "responseId": "9h9hae6BBJy8vr0PoczKOA"
}

data: {"candidates": [{"content": {"parts": [{"text": "Hello! How can I assist you today?"}],"role": "model"},"finishReason": "STOP","index": 0}],"usageMetadata": {"promptTokenCount": 2,"candidatesTokenCount": 9,"totalTokenCount": 172,"promptTokensDetails": [{"modality": "TEXT","tokenCount": 2}],"thoughtsTokenCount": 161},"modelVersion": "gemini-2.5-flash","responseId": "aSBhaaKxN7yk1e8Pw9qO-A0"}

curl "https://api.poixe.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $POIXE_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Hello!"
          }
        ]
      }
    ]
  }'

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Hello there! How can I help you today?"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 2,
    "candidatesTokenCount": 10,
    "totalTokenCount": 35,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 2
      }
    ],
    "thoughtsTokenCount": 23
  },
  "modelVersion": "gemini-2.5-flash",
  "responseId": "9h9hae6BBJy8vr0PoczKOA"
}

data: {"candidates": [{"content": {"parts": [{"text": "Hello! How can I assist you today?"}],"role": "model"},"finishReason": "STOP","index": 0}],"usageMetadata": {"promptTokenCount": 2,"candidatesTokenCount": 9,"totalTokenCount": 172,"promptTokensDetails": [{"modality": "TEXT","tokenCount": 2}],"thoughtsTokenCount": 161},"modelVersion": "gemini-2.5-flash","responseId": "aSBhaaKxN7yk1e8Pw9qO-A0"}

curl "https://api.poixe.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $POIXE_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Hello!"
          }
        ]
      }
    ]
  }'

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Hello there! How can I help you today?"
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 2,
    "candidatesTokenCount": 10,
    "totalTokenCount": 35,
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 2
      }
    ],
    "thoughtsTokenCount": 23
  },
  "modelVersion": "gemini-2.5-flash",
  "responseId": "9h9hae6BBJy8vr0PoczKOA"
}

data: {"candidates": [{"content": {"parts": [{"text": "Hello! How can I assist you today?"}],"role": "model"},"finishReason": "STOP","index": 0}],"usageMetadata": {"promptTokenCount": 2,"candidatesTokenCount": 9,"totalTokenCount": 172,"promptTokensDetails": [{"modality": "TEXT","tokenCount": 2}],"thoughtsTokenCount": 161},"modelVersion": "gemini-2.5-flash","responseId": "aSBhaaKxN7yk1e8Pw9qO-A0"}

POST Non-streaming https://api.poixe.com/v1beta/models/gemini-2.5-flash:generateContentPOST Streaming https://api.poixe.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse

This is Google’s unified generative API for developers: it uses a consistent input/output structure to cover text, multimodal, and tool-augmented scenarios.

Streaming calls (SSE)

In Gemini, non-streaming and streaming are two different endpoints, and the request URL contains the model name (for example .../models/gemini-2.5-flash:xxx), rather than only specifying the model in the body as some protocols do.

Non-streaming: POST ...:generateContent
Streaming: POST ...:streamGenerateContent?alt=sse

Authentication and request headers

Every request must carry an API key in the HTTP headers.

string

required

Google API key. Example format: $POIXE_API_KEY.

string

required

Must be set to application/json.

Request parameters

The following are the most commonly used core request fields (covering single-turn text, multi-turn chat, and common sampling controls).

object[]

required

The conversation content (or single-turn input). Gemini uses contents[] to represent “conversation history + current turn input”.

Show contents[] fields

string

The role. Common values: user / model. In most cases you only need to send user; use model to fill in earlier replies as history.

object[]

required

The list of content parts.

Show parts[] fields

string

Text content (most common).

object

System instruction (optional). Used to hold developer/system-level constraints; it is also a Content object (usually containing only text).

object

Generation parameters (optional), used to control sampling, length, and output format.

Show generationConfig fields

number

Sampling temperature. Lower values are more deterministic; higher values are more divergent.

number

Nucleus sampling. In general, adjust either this or temperature, not both.

integer

The maximum number of output tokens (limits output length).

string[]

Stop sequences (up to 5). Generation stops when one is hit (the stop sequence itself does not appear in the output).

string

Output MIME type (optional). Common values: text/plain (default) / application/json (when you need stable JSON output).

object

Output schema (optional). Use together with responseMimeType: "application/json" for structured output (a subset of JSON Schema).

object[]

The list of tools (optional). Used for capabilities such as function calling and code execution (support may vary by model and capability).

object

Tool configuration (optional). Used to specify the tool selection strategy, constraints, and so on (usually used together with tools).

object[]

Safety settings (optional). Used to override the default content safety thresholds (configured per category).

Response structure

A non-streaming request returns a GenerateContentResponse object; a streaming request returns multiple GenerateContentResponse chunks over SSE (you will continuously receive multiple data: {...} JSON lines).

object[]

The list of candidate results (usually you only need candidates[0]).

Show candidates[] fields

integer

Candidate index

object

The generated content (role + parts[]).

Show content fields

string

Usually model

object[]

The array of output parts, most commonly [{ "text": "..." }].

string

The finish reason (for example STOP).

object[]

Safety ratings (if returned).

object

Prompt safety feedback (if returned). When a prompt is filtered or blocked, you can usually find the reason here.

object

Token usage statistics (output field). We recommend interpreting and recording Gemini’s billing basis as follows: input_tokens = promptTokenCount + toolUsePromptTokenCount, output_tokens = candidatesTokenCount + thoughtsTokenCount, total_tokens = input_tokens + output_tokens (usually matches totalTokenCount).

Show usageMetadata fields

integer

Prompt input token count

integer

Input token count for tool results fed back into the context (if any)

integer

Visible output token count

integer

Thinking token count (if any)

integer

Total token count

string

The model version actually used (output field).

string

The unique response identifier (output field).

Official docs: Text generation (Gemini API)

View Gemini’s text generation guide, examples, and best practices.

API Reference

Text APIs

System APIs

Google Gemini Content Protocol

Streaming calls (SSE)

Authentication and request headers

Request parameters

Response structure

Official docs: Text generation (Gemini API)

​Streaming calls (SSE)

​Authentication and request headers

​Request parameters

​Response structure

Official docs: Text generation (Gemini API)

Streaming calls (SSE)

Authentication and request headers

Request parameters

Response structure