> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poixe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Gemini Content Protocol

<RequestExample>
  ```bash curl theme={"theme":{"light":"min-light","dark":"min-dark"}}
  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!"
            }
          ]
        }
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json response theme={"theme":{"light":"min-light","dark":"min-dark"}}
  {
    "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"
  }
  ```

  ```json response stream theme={"theme":{"light":"min-light","dark":"min-dark"}}
  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"}
  ```
</ResponseExample>

<div className="inline-flex flex-wrap items-center gap-4 rounded-lg border px-3 py-2">
  <Badge color="gray">POST</Badge>
  <Badge color="blue">Non-streaming</Badge>
  `https://api.poixe.com/v1beta/models/gemini-2.5-flash:generateContent`

  <Badge color="gray">POST</Badge>
  <Badge color="blue">Streaming</Badge>
  `https://api.poixe.com/v1beta/models/gemini-2.5-flash:streamGenerateContent?alt=sse`
</div>

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.

<ParamField header="x-goog-api-key" type="string" required>
  Google API key. Example format: `$POIXE_API_KEY`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be set to `application/json`.
</ParamField>

## Request parameters

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

<ParamField body="contents" type="object[]" required>
  The conversation content (or single-turn input). Gemini uses `contents[]` to represent "conversation history + current turn input".

  <Expandable title="contents[] fields">
    <ParamField body="role" type="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.
    </ParamField>

    <ParamField body="parts" type="object[]" required>
      The list of content parts.

      <Expandable title="parts[] fields">
        <ParamField body="text" type="string">
          Text content (most common).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="systemInstruction" type="object">
  System instruction (optional). Used to hold developer/system-level constraints; it is also a `Content` object (usually containing only text).
</ParamField>

<ParamField body="generationConfig" type="object">
  Generation parameters (optional), used to control sampling, length, and output format.

  <Expandable title="generationConfig fields">
    <ParamField body="temperature" type="number">
      Sampling temperature. Lower values are more deterministic; higher values are more divergent.
    </ParamField>

    <ParamField body="topP" type="number">
      Nucleus sampling. In general, adjust either this or `temperature`, not both.
    </ParamField>

    <ParamField body="maxOutputTokens" type="integer">
      The maximum number of output tokens (limits output length).
    </ParamField>

    <ParamField body="stopSequences" type="string[]">
      Stop sequences (up to 5). Generation stops when one is hit (the stop sequence itself does not appear in the output).
    </ParamField>

    <ParamField body="responseMimeType" type="string">
      Output MIME type (optional). Common values: `text/plain` (default) / `application/json` (when you need stable JSON output).
    </ParamField>

    <ParamField body="responseSchema" type="object">
      Output schema (optional). Use together with `responseMimeType: "application/json"` for structured output (a subset of JSON Schema).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tools" type="object[]">
  The list of tools (optional). Used for capabilities such as function calling and code execution (support may vary by model and capability).
</ParamField>

<ParamField body="toolConfig" type="object">
  Tool configuration (optional). Used to specify the tool selection strategy, constraints, and so on (usually used together with `tools`).
</ParamField>

<ParamField body="safetySettings" type="object[]">
  Safety settings (optional). Used to override the default content safety thresholds (configured per category).
</ParamField>

## 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).

<ResponseField name="candidates" type="object[]">
  The list of candidate results (usually you only need `candidates[0]`).

  <Expandable title="candidates[] fields">
    <ResponseField name="index" type="integer">Candidate index</ResponseField>

    <ResponseField name="content" type="object">
      The generated content (`role` + `parts[]`).

      <Expandable title="content fields">
        <ResponseField name="role" type="string">Usually `model`</ResponseField>

        <ResponseField name="parts" type="object[]">
          The array of output parts, most commonly `[{ "text": "..." }]`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="finishReason" type="string">
      The finish reason (for example `STOP`).
    </ResponseField>

    <ResponseField name="safetyRatings" type="object[]">
      Safety ratings (if returned).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="promptFeedback" type="object">
  Prompt safety feedback (if returned). When a prompt is filtered or blocked, you can usually find the reason here.
</ResponseField>

<ResponseField name="usageMetadata" type="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).

  <Expandable title="usageMetadata fields">
    <ResponseField name="promptTokenCount" type="integer">Prompt input token count</ResponseField>
    <ResponseField name="toolUsePromptTokenCount" type="integer">Input token count for tool results fed back into the context (if any)</ResponseField>
    <ResponseField name="candidatesTokenCount" type="integer">Visible output token count</ResponseField>
    <ResponseField name="thoughtsTokenCount" type="integer">Thinking token count (if any)</ResponseField>
    <ResponseField name="totalTokenCount" type="integer">Total token count</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="modelVersion" type="string">
  The model version actually used (output field).
</ResponseField>

<ResponseField name="responseId" type="string">
  The unique response identifier (output field).
</ResponseField>

<br />

<CardGroup cols={1}>
  <Card title="Official docs: Text generation (Gemini API)" href="https://ai.google.dev/gemini-api/docs/text-generation?hl=zh-cn">
    View Gemini's text generation guide, examples, and best practices.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.