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

# Gemini Native Format

> Use Google Gemini native paths and request bodies to call generateContent, streamGenerateContent, and model queries.

# Gemini Native Format

Gemini Native Format preserves the Google Gemini API paths and request bodies. It is suitable for business integrations that already use the Gemini SDK, the `contents`/`parts` structure, or safety settings configuration.

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Google API Key style is also supported:

```http theme={null}
x-goog-api-key: YOUR_API_KEY
```

Or as a query parameter:

```text theme={null}
/v1beta/models/gemini-2.0-flash:generateContent?key=YOUR_API_KEY
```

## Paths

| Method | Path                                           | Description                      |
| ------ | ---------------------------------------------- | -------------------------------- |
| `GET`  | `/v1beta/models`                               | Gemini model list                |
| `POST` | `/v1beta/models/{model}:generateContent`       | Non-streaming content generation |
| `POST` | `/v1beta/models/{model}:streamGenerateContent` | Streaming content generation     |

## Request Body

<ParamField body="contents" type="array<object>" required>
  List of conversation contents. Each content item contains `role` and `parts`.
</ParamField>

<ParamField body="contents[].parts" type="array<object>" required>
  Content parts. Supports `text`, `inlineData`, `fileData`, `functionCall`, `functionResponse`, and more.
</ParamField>

<ParamField body="contents[].parts[].videoMetadata" type="object">
  Video input metadata. Use it on the same `part` as video `inlineData` or `fileData` to control the time range and frame sampling rate the model reads.

  Supported fields:

  * `startOffset`: Video start offset, using Duration string format, such as `"3s"` or `"3.5s"`.
  * `endOffset`: Video end offset, using Duration string format, such as `"10s"`.
  * `fps`: Video sampling frame rate. Defaults to `1.0`; valid range is `0 < fps <= 24`.

  When a request includes multiple videos, each video `part` can set its own `videoMetadata`.
</ParamField>

<ParamField body="systemInstruction" type="object">
  System-level instruction (System Prompt). Used to define model behavior, role setting, and response style. Compatible with both `systemInstruction` and `system_instruction` forms.
</ParamField>

<ParamField body="generationConfig" type="object">
  Generation configuration, used to control model output behavior. Supports the following fields:

  * `temperature`: Controls output randomness; higher values produce more diverse results.
  * `topP`: Nucleus Sampling probability threshold.
  * `topK`: Samples only from the top K most probable tokens.
  * `candidateCount`: Number of candidate results to return.
  * `maxOutputTokens`: Maximum number of output tokens.
  * `stopSequences`: Stops generation when the specified strings are encountered.
  * `responseMimeType`: Specifies the output format, e.g. `text/plain`, `application/json`.
  * `responseSchema`: JSON Schema structured output constraint.
  * `presencePenalty`: Reduces repetitive topics and encourages new content generation.
  * `frequencyPenalty`: Reduces repetitive words or sentences.
  * `seed`: Fixes the random seed for reproducible results.
  * `responseLogprobs`: Whether to return token probability information.
  * `logprobs`: Number of token probabilities to return.
  * `audioTimestamp`: Whether to return audio timestamps.
  * `speechConfig`: Speech output configuration (TTS).
  * `thinkingConfig`: Gemini Thinking model reasoning configuration.
</ParamField>

<ParamField body="safetySettings" type="array<object>">
  Safety policy configuration. Each item contains `category` (risk category) and `threshold` (risk blocking level).

  Supported risk categories: `HARM_CATEGORY_HATE_SPEECH`, `HARM_CATEGORY_HARASSMENT`, `HARM_CATEGORY_SEXUALLY_EXPLICIT`, `HARM_CATEGORY_DANGEROUS_CONTENT`.
</ParamField>

<ParamField body="tools" type="array<object>">
  Gemini tool declaration list, used to enable function calling, search, code execution, and other capabilities. Supports the following tool types:

  * `functionDeclarations`: Function Calling function declarations.
  * `googleSearch`: Google search capability.
  * `codeExecution`: Code execution capability.
  * `urlContext`: URL content parsing capability.
  * `retrieval`: Retrieval-Augmented Generation (RAG).
  * `googleSearchRetrieval`: Google retrieval augmentation.
</ParamField>

<ParamField body="toolConfig" type="object">
  Tool invocation configuration.

  Commonly used to configure `functionCallingConfig.mode`: `AUTO` (model automatically decides whether to call tools), `ANY` (force tool calling), `NONE` (disable tool calling).

  `allowedFunctionNames`: Specifies the list of functions allowed to be called.
</ParamField>

<ParamField body="cachedContent" type="string">
  Gemini Cached Content identifier. Used to reuse context cache, reducing token consumption and response latency for long-context requests.
</ParamField>

## Request Example

<RequestExample>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:generateContent \
    -H "x-goog-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "contents": [
        {
          "role": "user",
          "parts": [
            { "text": "Introduce the Gemini native API in three sentences." }
          ]
        }
      ],
      "generationConfig": {
        "temperature": 0.7,
        "maxOutputTokens": 300
      }
    }'
  ```
</RequestExample>

### Multimodal Input

```bash theme={null}
curl -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Identify the core information in this image." },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "BASE64_IMAGE_DATA"
            }
          }
        ]
      }
    ]
  }'
```

### Video Input with videoMetadata

Put `videoMetadata` on the same `part` as the video data. It can be used to analyze only a video segment or adjust frame sampling density.

```bash theme={null}
curl -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:generateContent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Summarize what happens between seconds 3 and 12 in this video." },
          {
            "fileData": {
              "mimeType": "video/mp4",
              "fileUri": "https://example.com/demo-video.mp4"
            },
            "videoMetadata": {
              "startOffset": "3s",
              "endOffset": "12s",
              "fps": 2
            }
          }
        ]
      }
    ]
  }'
```

### Streaming Generation

```bash theme={null}
curl -N -X POST https://octopusx.ai/v1beta/models/gemini-2.0-flash:streamGenerateContent \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Write a release announcement in 5 lines or fewer." }
        ]
      }
    ]
  }'
```

## Response Example

<ResponseExample>
  ```json 200 theme={null}
  {
    "candidates": [
      {
        "content": {
          "role": "model",
          "parts": [
            {
              "text": "The Gemini native API uses contents and parts to express input content. It supports text, images, files, and function calling. With a unified gateway, you can continue using the same API key and billing system."
            }
          ]
        },
        "finishReason": "STOP",
        "safetyRatings": [
          {
            "category": "HARM_CATEGORY_HARASSMENT",
            "probability": "NEGLIGIBLE"
          }
        ]
      }
    ],
    "usageMetadata": {
      "promptTokenCount": 18,
      "candidatesTokenCount": 58,
      "totalTokenCount": 76
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "field contents is required",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "User quota is insufficient",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "The current request rate is too high, please try again later",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## Common Safety Settings

| category                          | Description               |
| --------------------------------- | ------------------------- |
| `HARM_CATEGORY_HARASSMENT`        | Harassment content        |
| `HARM_CATEGORY_HATE_SPEECH`       | Hate speech               |
| `HARM_CATEGORY_SEXUALLY_EXPLICIT` | Sexually explicit content |
| `HARM_CATEGORY_DANGEROUS_CONTENT` | Dangerous content         |

| threshold                | Description                 |
| ------------------------ | --------------------------- |
| `BLOCK_NONE`             | Do not block                |
| `BLOCK_ONLY_HIGH`        | Block high risk only        |
| `BLOCK_MEDIUM_AND_ABOVE` | Block medium risk and above |
| `BLOCK_LOW_AND_ABOVE`    | Block low risk and above    |

## Related Interfaces

* [Chat Completions Interface (default non-streaming)](./chat-completions-non-stream)
* [Model List](./models)