Gemini native HTTP

ClearMaas’s /v1beta/ surface is a direct passthrough to Google’s Gemini API. Pick this path when you want Gemini features that don’t fit OpenAI shape �?inline audio/video data, native built-in tools like googleSearch, fully-formed generationConfig.thinkingConfig, or simply because you’re already on the google-genai SDK. For everyday chat the OpenAI-compatible path (POST /v1/chat/completions with model=google/...) is usually simpler and works across providers �?see Compatibility / Google GenAI SDK for SDK setup.

Path layout

POST https://api.clearmaas.com/v1beta/models/{model}:{action}

Recognized actions:

Action	What it does
`:generateContent`	One-shot response (JSON)
`:streamGenerateContent`	SSE stream of partial chunks

Other Gemini actions (countTokens, tunedModels.*, etc.) are not routed through this surface today.

Authentication

The gateway accepts three header forms on this surface, so the official google-genai SDK works without header hacks:

Authorization: Bearer sk-...
x-goog-api-key: sk-...
?key=sk-... (query string, last resort for tools that don’t support setting headers)

Examples

curl "https://api.clearmaas.com/v1beta/models/google/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Write a one-sentence haiku about the sea."}]}]
  }'

curl -N "https://api.clearmaas.com/v1beta/models/google/gemini-2.5-flash:streamGenerateContent" \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Tell me a long story."}]}]
  }'

curl "https://api.clearmaas.com/v1beta/models/google/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"What changed in Gemini pricing this week?"}]}],
    "tools": [{"googleSearch": {}}]
  }'

curl "https://api.clearmaas.com/v1beta/models/google/gemini-2.5-flash-image:generateContent" \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role":"user","parts":[{"text":"A watercolour of a foggy harbor at dawn."}]}],
    "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]}
  }'

Built-in tools

Gemini’s three native built-in tools work as documented by Google �? pass them in the request body’s tools array:

Tool	Effect
`{"googleSearch": {}}`	Web grounding. The response carries `groundingMetadata`. ClearMaas captures `webSearchQueries` for billing.
`{"codeExecution": {}}`	Lets the model run sandboxed Python.
`{"urlContext": {}}`	Lets the model fetch and summarize URLs you mention.

The same three tools are reachable from OpenAI-shape Chat Completions via reserved function names �?see Advanced / Web search and Advanced / Tool calling.

Getting started

Gemini native HTTP

Path layout

Authentication

Examples

Built-in tools

See also

​Path layout

​Authentication

​Examples

​Built-in tools

​See also

Path layout

Authentication

Examples

Built-in tools

See also