Gemini Native API

The Gemini Native API preserves Google Gemini request and response structures. Use it when your client needs native contents, generationConfig, safetySettings, tool calling, or multimodal parts.

If your client uses the OpenAI Chat Completions format, use Gemini Chat instead. Request and response bodies from the two protocols cannot be mixed.

Base URL and Authentication

Base URL:

https://cubicspaces.cloud

Pass your Cubicspaces API key in the x-goog-api-key request header:

x-goog-api-key: YOUR_API_KEY

Do not expose API keys in public source code, browser pages, or publicly accessible URLs.

Endpoints

Operation	Method and path
List models	GET /v1beta/models
Generate content	POST /v1beta/models/{model}:generateContent
Stream content	POST /v1beta/models/{model}:streamGenerateContent?alt=sse

Actual model availability depends on account permissions and platform configuration. Text models include:

Model
gemini-3.1-pro-preview
gemini-3.1-flash-lite
gemini-3-flash-preview

Non-streaming Request

curl "https://cubicspaces.cloud/v1beta/models/gemini-3.1-pro-preview:generateContent" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Introduce Gemini in one sentence." }
        ]
      }
    ],
    "generationConfig": {
      "thinkingConfig": {
        "thinkingLevel": "low"
      },
      "maxOutputTokens": 512
    }
  }'

The model name is part of the URL path. Do not add a separate model field to the request body.

Native Response

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          { "text": "Gemini is Google's family of multimodal generative AI models." }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 18,
    "thoughtsTokenCount": 32,
    "totalTokenCount": 62
  },
  "modelVersion": "gemini-3.1-pro-preview",
  "responseId": "example-response-id"
}

Text is normally read from:

candidates[0].content.parts[*].text

Usage fields such as thoughtsTokenCount are present only when the response contains that token type.

Streaming Request

curl -N "https://cubicspaces.cloud/v1beta/models/gemini-3.1-pro-preview:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Write a short product introduction." }
        ]
      }
    ]
  }'

Streaming responses use SSE. Each data: event contains a Gemini-native response fragment. Continue reading text from candidates[].content.parts[].text.

Request Affinity

To keep consecutive requests from the same conversation affine, send the same stable X-Affinity-Key with every request:

X-Affinity-Key: project-or-session-id

No additional cookie is required. Use a non-sensitive identifier that does not contain an API key, email address, phone number, or prompt content. See Cache & Request Affinity for details.

Common Native Fields

• contents: conversation content made of role and parts.
• systemInstruction: system-level instructions.
• generationConfig: generation settings such as maxOutputTokens, temperature, and thinkingConfig.
• safetySettings: safety policy settings.
• tools and toolConfig: function calling and other tool settings.
• cachedContent: a Gemini cached-content identifier.

Fields use Gemini-native camelCase names. Do not send OpenAI-format messages, stream, or choices fields to this endpoint.

Official References

• Gemini GenerateContent API
• Gemini 3 GenerateContent guide
• Gemini 3.1 Pro Preview model